Apakah saya perlu menulis halaman manual untuk pustaka C?

Saya menulis perpustakaan C kecil untuk Linux dan FreeBSD, dan saya akan menulis dokumentasi untuk itu. Saya mencoba mempelajari lebih lanjut tentang cara membuat halaman manual dan tidak menemukan petunjuk atau deskripsi praktik terbaik membuat halaman manual untuk perpustakaan. Khususnya saya tertarik pada bagian apa untuk menempatkan halaman manual fungsi? 3? Mungkin ada contoh atau manual yang bagus? Buat halaman manual untuk setiap fungsi dari perpustakaan ide yang buruk?

Halaman manual untuk perpustakaan akan masuk di bagian 3.

Untuk contoh halaman buku panduan yang baik, ingatlah bahwa beberapa ditulis menggunakan detail spesifik groff dan / atau menggunakan makro spesifik yang tidak terlalu portabel.

Selalu ada beberapa kesulitan dalam portabilitas halaman manual, karena beberapa sistem mungkin (atau mungkin tidak) menggunakan fitur-fitur khusus. Misalnya, dalam mendokumentasikan dialog, saya harus mengingat (dan mengatasi) perbedaan dalam berbagai sistem untuk menampilkan contoh (yang tidak dibenarkan).

Mulailah dengan membaca bagian yang relevan di man manmana ia menyebutkan makro standar, dan bandingkan deskripsi tersebut untuk FreeBSD dan Linux.

Apakah Anda memilih untuk menulis satu halaman buku panduan untuk perpustakaan, atau memisahkan halaman buku panduan untuk fungsi-fungsi (atau kelompok fungsi) tergantung pada seberapa rumitnya deskripsi fungsi-fungsi tersebut:

• ncurses memiliki beberapa ratus fungsi di beberapa lusin halaman buku panduan.
• dialog memiliki beberapa lusin fungsi dalam satu halaman buku panduan. Yang lain pasti akan menunjukkan lebih banyak contoh.

Bacaan lebih lanjut:

• man - tampilkan halaman dokumentasi manual online (FreeBSD)
• man-pages - konvensi untuk menulis halaman manual Linux
• groff_mdoc - referensi untuk implementasi mdoc groff
• HowTo: Buat halaman manual dari awal. (FreeBSD)
• Apa Itu "Bikeshed"?

Saya menggunakan ronn . Anda cukup menulis penurunan harga, dan itu akan mengubahnya menjadi halaman manual. Ada juga (agak kurang mampu) klon js yang disebut man-ditandai .

Saya telah mendokumentasikan skrip saya dengan menggunakan END_MANheredocs yang dibatasi dan kode C / C ++ saya dengan menggunakan END_MANheredocs yang dibatasi sama kecuali di dalam /* */. Entah mudah diekstraksi dengan sed dan kemudian diolah menjadi halaman manual. (Dengan sedikit peretasan sinyal UNIX bersama dengan inotifywait, Anda dapat mengekstrak dan melihat bagian halaman manual Anda secara langsung dan membuat peramban halaman manual dimuat sebagai sumber memperbarui.)

Adapun bagian, maka 3 akan untuk perpustakaan tingkat pengguna C. Anda dapat membaca tentang nomor bagian (antara lain) di man (1) .

Jika Anda ingin melihat beberapa halaman manual contoh yang dapat dibaca dan terstruktur dengan baik, saya akan melihat perpustakaan Plan9 https://swtch.com/plan9port/unix/ di mana Anda dapat melihat bagaimana pencipta cdan UNIXdan dokumentasinya. Sistem mungkin dimaksudkan untuk hal-hal ini berfungsi.

Untuk melengkapi jawaban lain, bahasa markdown lain yang dapat digunakan untuk menyederhanakan penulisan halaman manual adalah reStructuredText dan perintah rst2man yang merupakan bagian dari paket python-docutils .

Bahasa penurunan harga ini telah diadopsi oleh python untuk dokumentasinya , dan jauh lebih mudah untuk dipelajari, ditulis, dan dipelihara, daripada makro troff man tua yang baik yang akan dihasilkan rst2man untuk Anda dari reStructuredText Anda.

Anda dapat mendokumentasikan API menggunakan doxygen untuk memberikan referensi sebagai HTML, dan juga menghasilkan halaman manual dan format lain untuk dibaca secara offline.

Keuntungan dari doxygen adalah bahwa itu semacam "inline" dokumentasi seperti JavaDoc atau PythonDoc, dua kali lipat sebagai komentar antarmuka (atau vv., Komentar dua kali lipat sebagai teks dokumen); Anda menambahkan teks dokumen ke file sumber / header Anda, dan itu diekstraksi dari sana, yang meningkatkan kemungkinan diadakannya pembaruan.