Linux ve FreeBSD için küçük bir C kütüphanesi yazdım ve bunun için belgeleri yazacağım. Man sayfaları oluşturma hakkında daha fazla bilgi edinmeye çalıştım ve kütüphaneler için man sayfaları yapan en iyi uygulamaların talimatlarını veya açıklamalarını bulamadım. Özellikle fonksiyonların man sayfalarını koymak için hangi bölümle ilgileniyorum? 3? Belki iyi örnekler veya kılavuzlar var? Kütüphaneden her fonksiyon için man sayfaları oluşturmak kötü bir fikir mi?
Yanıtlar:
Bir kitaplık için manuel sayfalar bölüm 3'e gider.
Manuel sayfaların iyi örnekleri için, bazılarının groff ve / veya gerçekten taşınabilir olmayan belirli makrolar kullanılarak yazıldığını unutmayın.
Man sayfalarının taşınabilirliğinde her zaman bazı tuzaklar vardır, çünkü bazı sistemler özel özellikler kullanabilir (veya kullanmayabilir). Örneğin, dokümantasyonda dialog, örnekleri görüntülemek için çeşitli sistemlerde (gerekçelendirilmemiş) farklılıkları göz önünde bulundurmam (ve geçici çözüm bulmam) gerekiyordu.
Standart makrolardan bahsedildiği ilgili bölümleri okuyarak başlayın man manve FreeBSD ve Linux için bu açıklamaları karşılaştırın .
Kütüphane için bir manuel sayfa veya işlevler (veya işlev grupları) için ayrı manuel sayfalar yazmayı seçmeniz, işlevlerin açıklamalarının ne kadar karmaşık olacağına bağlıdır:
Daha fazla okuma:
Ben ronn kullanıyorum . Sen sadece markdown yaz, ve bu bir manpage dönüşecek. Ayrıca işaretli adam denilen (biraz daha az yetenekli) bir js klonu var .
İçimde END_MANaynı END_MANsınırlandırılmış yorumlu metinleri kullanarak sınırlandırılmış yorumlu metinler ve C / C ++ kodumu kullanarak komut dosyalarımı belgeliyorum /* */. Her ikisi de sed ile kolayca çıkartılabilir ve daha sonra bir mantafa dönüştürülebilir. (İnotifywait ile birlikte biraz UNIX sinyal korsanlığı ile, manpage bölümlerinizi ayıklayıp görüntüleyebilir ve manpage tarayıcısının kaynak güncellemeleri olarak yeniden yüklenmesini sağlayabilirsiniz.)
Bölüm gelince, kullanıcı seviyesi C kütüphanesi için 3 olurdu. İnsanda (1) bölüm numaralarını (diğer şeylerin yanı sıra) okuyabilirsiniz .
Bazı okunabilir, iyi yapılandırılmış bir örnek man sayfaları görmek isterseniz, ben plan9 bakmak istiyorum https://swtch.com/plan9port/unix/ nasıl çok yaratıcıları görebilirsiniz kütüphaneler cve UNIXve belgelerini sistem muhtemelen bu şeylerin çalışması için tasarlanmıştır.
Diğer yanıtları tamamlamak için, yazma adam sayfalarını basitleştirmek için kullanılabilecek bir başka markdown dildir reStructuredText ve rst2man parçası olan komut piton-docutils pakette.
Bu işaretleme dili, dokümantasyon için python tarafından benimsenmiştir ve öğrenilmesi, yazılması ve bakımı, rst2man'ın sizin için reStructuredText'ten üreteceği eski troff man makrolarından çok daha kolaydır.
HTML olarak referans sağlamak için doxygen kullanarak API'yi belgeleyebilir ve çevrimdışı okuma için man sayfaları ve diğer formatlar oluşturabilirsiniz.
Doxygen'in avantajı, JavaDoc veya PythonDoc gibi bir çeşit "satır içi" belgelemenin arayüz yorumu olarak ikiye katlanması (veya vv., Doc metni olarak ikiye katlanması); doküman metinlerini kaynak / başlık dosyalarınıza eklersiniz ve oradan çıkarılır, bu da güncel tutulma şansını artırır.
manstandart kütüphane ve sistem çağrıları dışında asla programlama için kullanmıyorum .