web-dev-qa-db-ja.com

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

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

12
Valeriy

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

マニュアルページの良い例については、いくつかはgroffの特定の詳細を使用して記述されているか、実際には移植できない特定のマクロを使用していることに注意してください。

システムによっては特別な機能を使用する場合としない場合があるため、manページの移植性には常にいくつかの落とし穴があります。たとえば、 dialog を文書化する場合、例を表示するためのさまざまなシステムの違い(正当化されていない)を考慮(および回避)する必要がありました。

最初にreadingman manの関連セクションで標準マクロについて言及し、compareFreeBSDおよびLinuxに関する説明。

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

  • ncurses には、数十のマニュアルページにまたがる数百の関数があります。
  • dialog は、1つのマニュアルページに数十の機能があります。他の人はもっと多くの例を必ず示すでしょう。

参考文献:

25
Thomas Dickey

ronn を使用します。あなたは単にマークダウンを書くだけで、それをマンページに変えます。 marked-man と呼ばれる(やや能力が低い)jsクローンもあります。

私は、END_MANで区切られたheredocsを使用してスクリプトを文書化し、END_MAN内を除いて同じ/* */で区切られたheredocsを使用してC/C++コードを文書化しています。どちらもsedで簡単に抽出でき、マンページにレンダリングできます。 (inotifywaitとともに少しのUNIXシグナルハッカーを使用すると、マンページセクションをライブで抽出して表示し、ソースの更新時にマンページブラウザをリロードできます。)

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

読みやすく、よく構造化されたサンプルのmanページを確認したい場合は、Plan9 https://swtch.com/plan9port/unix/ ライブラリを参照してください。 cUNIXの作成者とそのドキュメントシステムは、おそらくこれらを機能させることを目的としています。

10
PSkocik

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

このマークダウン言語は、python for its documentation )で採用されており、rst2manが生成する古き良きtroff manマクロよりも学習、記述、保守がはるかに簡単です。あなたのためにあなたのreStructuredTextから。

3
meuh

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

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

1
Murphy