web-dev-qa-db-ja.com

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

カーネル sources には関数とデータ構造が含まれています。 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をmanpagesとして表示し、この既存のドキュメントフレームワークを活用すると便利です。

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

kernelmandocumentation
9
kakeh

内容は 直接解析 （また参照 this ）source.cファイルから1：

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

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

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

開始コメントマーク「/ **」はkernel-docコメント用に予約されています。そのようにマークされたコメントのみがkernel-docスクリプトによって考慮され、そのようにマークされたコメントはkernel-doc形式である必要があります。

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

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

したがって、mandocstarget に限定されません。

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

カーネルリポジトリ/ソースには、ドライバ固有の テキストファイル もあります。より一般的には、彼らのLinux man-pages project（man1throughman8）は available でダウンロードできます。最後に、kernel.orgは output のドキュメントも保持しています。

1.マンページを生成するためにこのような手法が使用されるのは、カーネルだけではありません。 GNUcoreutilsはそのような他のケースの1つです。そのマンページのほとんどは 生成 を使用しています内容がusage関数にあるcommand --helpの出力ユーティリティソースファイル（ 12 ）。

6
user44370

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

apt-get install linux-manual-3.2

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

apt-get install linux-doc

これはhtmlです。

4
Faheem Mitha

カーネルソースコードをダウンロード およびソースディレクトリで実行

make mandocs

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

make installmandocs

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

3
manav m-n