Cライブラリのmanページを書く必要がありますか？

LinuxとFreeBSD用の小さなCライブラリを作成し、そのドキュメントを作成します。私はマニュアルページの作成についてもっと学ぼうとしましたが、ライブラリ用のマニュアルページを作成するベストプラクティスの指示や説明は見つかりませんでした。特に、私は関数のマニュアルページをどのセクションに置くことに興味がありますか？3？たぶん良い例やマニュアルがありますか？ライブラリから各関数のマニュアルページを作成するのは悪い考えですか？

ライブラリのマニュアルページはセクション3に移動します。

マニュアルページの良い例として、いくつかはgroffの特定の詳細を使用して書かれていること、および/または実際には移植性のない特定のマクロを使用することに留意してください。

一部のシステムは特別な機能を使用する場合としない場合があるため、マンページの移植性には常にいくつかの落とし穴があります。たとえば、文書化ではdialog、例を表示するためのさまざまなシステムの違いを念頭に置いて回避する必要があります（正当化されていません）。

ことから始め読み込みの関連セクションman manには、標準のマクロを言及ところを、と比較 FreeBSDとLinuxのためのそれらの記述を。

ライブラリに1つのマニュアルページを作成するか、関数（または関数のグループ）に個別のマニュアルページを作成するかは、関数の説明がどの程度複雑になるかによって異なります。

• ncursesには、数十のマニュアルページに数百の機能があります。
• ダイアログには、1つのマニュアルページに数十の機能があります。他の人はもっと多くの例を見せることでしょう。

参考文献：

• man-オンラインマニュアルドキュメントページを表示（FreeBSD）
• man-pages-Linux manページを書くための規則
• groff_mdoc-groffのmdoc実装のリファレンス
• 方法：最初からマンページを作成します。（FreeBSD）
• 「自転車置き場」とは何ですか？

ronnを使用します。単にマークダウンを書くだけで、それはマンページに変わります。また、marked-manと呼ばれる（多少機能が劣る）jsクローンもあります。

END_MAN区切りのあるヒアドキュメントを使用してスクリプトをドキュメント化し、END_MAN内を除く同じ区切りのヒアドキュメントを使用してC / C ++コードをドキュメント化しました/* */。どちらもsedを使用して簡単に抽出でき、マンページにレンダリングできます。（inotifywaitに加えてUNIXシグナルハッカーを少し使用すると、マンページセクションを抽出してライブで表示し、ソースが更新されるとマンページブラウザをリロードできます。）

セクションに関しては、ユーザーレベルのCライブラリの場合は3です。（特に）セクション番号についてはman（1）で読むことができます。

あなたには、いくつか読み、よく構造化例のmanページを見たい場合は、私はPlan9のを見て取ると思いhttps://swtch.com/plan9port/unix/あなたはどのように非常にのクリエイター見ることができるライブラリcとUNIX、そのドキュメントをシステムはおそらくこれらのことを機能させることを目的としていました。

他の回答を補足するために、manページの記述を簡素化するために使用できる別のマークダウン言語は、reStructuredTextおよびpython-docutilsパッケージの一部であるrst2manコマンドです。

このマークダウン言語は、Pythonのドキュメントで採用されており、rst2manがreStructuredTextから生成する古き良きtroff manマクロよりも、学習、作成、保守がはるかに簡単です。

doxygenを使用してAPIを文書化し、参照をHTMLとして提供し、オフラインで読むためのマニュアルページやその他の形式を生成することもできます。

doxygenの利点は、JavaDocやPythonDocのような一種の「インライン」ドキュメントであり、インターフェースコメント（またはvv。、docテキストとしてのコメント）を兼ねることです。ソース/ヘッダーファイルにドキュメントテキストを追加すると、そこから抽出され、最新の状態に保たれる可能性が向上します。