カーネルセクション9のマンページに、関数、データ構造、およびヘッダーを文書化する方法を教えてください。

カーネルソースには、たとえば次のように文書化された関数とデータ構造が含まれていますpanic.c。

/**
 *  panic - halt the system
 *  @fmt: The text string to print
 *
 *  Display a message, then perform cleanups.
 *
 *  This function never returns.
 */
void panic(const char *fmt, ...)

毎回ソースを調べる代わりに、これらのAPIをマンページとして表示し、この既存のドキュメントフレームワークを活用すると便利です。

前述の関数とデータ構造を文書化したカーネルセクション9マンページ（/usr/share/man/man9）をどのようにインストール/作成しますか？

コンテンツはソース .cファイル¹から直接（これも参照）解析されます。

Linuxカーネル内の関数とデータ構造の埋め込み、「C」フレンドリー、維持が容易で一貫性のある抽出可能なドキュメントを提供するために、Linuxカーネルは関数とそのパラメーター、および構造とそれらのドキュメント化に一貫したスタイルを採用しています。メンバー。

このドキュメントの形式は、kernel-doc形式と呼​​ばれます。これは、このDocumentation / kernel-doc-nano-HOWTO.txtファイルに記載されています。

このスタイルは、いくつかの単純な規則を使用して、ソースファイル内にドキュメントを埋め込みます。スクリプト/ kernel-doc perlスクリプト、Documentation / DocBookの一部のSGMLテンプレート、およびその他のツールは、これらの規則を理解し、この埋め込みドキュメントをさまざまなドキュメントに抽出するために使用されます。[...]

開始コメントマーク「/ **」はkernel-docコメント用に予約されています。そのようにマークされたコメントだけがkernel-docスクリプトによって考慮されます。そのようにマークされたコメントはkernel-doc形式でなければなりません。

つまり、このようにフォーマットされたコメントのみがこの方法で抽出でき、プロセスで使用されるPerlスクリプトを利用できるということです。kernel-doc make

kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]
  [ -no-doc-sections ]
  [ -function funcname [ -function funcname ...] ]
  c file(s)s > outputfile

したがって、mandocs ターゲットに限定されません。

インストール後、「make psdocs」、「make pdfdocs」、「make htmldocs」、または「make mandocs」は、要求された形式でドキュメントをレンダリングします。

カーネルリポジトリ/ソースには、ドライバ固有のテキストファイルもあります。より一般的には、そのLinuxのマン・ページプロジェクト（MAN1通じMAN8は）ある利用できるダウンロードします。最後に、kernel.orgはいくつかの出力ドキュメントも保持しています。

^{1.マンページを生成するためにこのような手法が使用されるのは、カーネルだけではありません。GNU coreutilsもそのようなケースの1つです。そのマンページのほとんどは、コンテンツの出力が使用法のユーティリティソースファイル（1 2）にある出力を使用して生成さcommand --helpれます。}

Ubuntuを使用していると仮定すると、

apt-get install linux-manual-3.2

または同様（正しいバージョンを選択）。別のドキュメントパッケージもあります

apt-get install linux-doc

これはhtmlです。

カーネルソースコードをダウンロードし、ソースディレクトリで実行します。

make mandocs

manドキュメントが作成された後、実行します

make installmandocs

これにより、マニュアルページがにインストールされ/usr/local/man/man9/ます。これで、を入力するman <api-name>か、API名をvim押すだけで編集している場合は、manページを表示できますK。