Cライブラリのマニュアルページを作成する必要がありますか?

Cライブラリのマニュアルページを作成する必要がありますか?

私はLinuxとFreeBSD用の小さなCライブラリを書いており、それを文書化する予定です。マニュアルページの作成について詳しく調べようとしましたが、ライブラリ用のマニュアルページの作成に関するベストプラクティスの説明や説明が見つかりませんでした。特に、関数のマニュアルページのどの部分が配置されているかに興味があります。サム?たぶん良い例やマニュアルがありますか?ライブラリのすべての機能についてマニュアルページを作成するのは悪い考えですか?

答え1

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

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

一部のシステムでは特殊機能を使用する場合と使用しない場合があるため、マニュアルページの移植性には常にいくつかのトラップがあります。たとえば、ロギング時にdialog、さまざまなシステムで示されている例の違いを覚えて解決する必要があります(これは不合理です)。

次から始まった読むman man標準マクロの関連部分に言及し、比較するこの説明はFreeBSDとLinuxに関するものです。

ライブラリ用に1つのマニュアルページを作成するか、関数(または機能グループ)に対して別々のマニュアルページを作成するかを選択するかどうかは、関数の説明の複雑さによって異なります。

  • 呪い何十ものマニュアルページに何百もの機能があります。
  • 会話単一のマニュアルページには数十の機能があります。他の人は間違いなくより多くの例を見せるでしょう。

追加資料:

答え2

私は使うロン。 Markdownを作成すると、マンページに変換されます。もう一つあります(少し能力が落ちます)JSそのクローンはおっぱい

私はいつもEND_MAN区切られたheredocsを使って私のスクリプトを文書化し、同じ区切りEND_MANのheredocsを使って私のC / C ++コードを文書化しました(例外/* */. sedを使用して両方を簡単に抽出してマンページにレンダリングできます。のUNIXシグナルハックとして)inotifywaitを使用すると、マンページセクションをリアルタイムで抽出して表示し、ソースが更新されたらマンページブラウザを再ロードできます。

その部分は、ユーザーレベルのCライブラリの場合は3です。章番号について読むことができます(何よりも)。男(1)

読みやすく、よく設定されたサンプルマニュアルページを表示するには、Plan9を見てみましょう。https://swtch.com/plan9port/unix/作成者とドキュメントシステムがこれをどのようにc実行したかを学ぶことができるライブラリです。UNIX

答え3

他の答えを補うためにマニュアルページの作成を簡素化するために使用できる別のMarkdown言語は次のとおりです。テキストの再構成そして最初の人コマンドは次の一部ですPython-docutilsパック。

このMarkdown言語はPythonで採用されています。文書、rst2manがreStructuredTextによって生成された以前のtroff manマクロよりも学習、作成、およびメンテナンスが簡単です。

答え4

以下を使用してAPIをログに記録できます。強力な酸素HTMLで参照を提供し、オフライン読み取り用のマニュアルページやその他の形式を生成します。

doxygenの良い点は、JavaDocやPythonDocなどの「インライン」ドキュメントであることです。この文書は、ソース/ヘッダーファイルに文書テキストを追加して抽出します。そこから文書テキストを作成すると、最新の状態を維持する可能性が高くなります。

関連情報