kernel-doc nano-HOWTO
=====================

ソースツリー内には、ブロックコメント形式で関数を説明した抽出可能な資料
がたくさんあります。このシステムのコンポーネントは次のとおりです。

- scripts/kernel-doc

  ブロックコメントを探しそれらを直接 DocBook, man, text, HTML へマーク
  アップできる perl スクリプトです (texinfo はできません)。

- Documentation/DocBook/*.tmpl

  SGML テンプレートファイルです。普通の SGML ファイルで、抽出された資
  料がどこに配置されるべきか指示する特別な場所を保持しています。

- scripts/docproc.c

  SGML テンプレートファイルを SGML ファイルに変換するためのプログラム
  です。資料化される関数の一覧を伴って kernel-doc を起動します。

- scripts/gen-all-syms

  C のファイル一覧内の EXPORT_SYMBOL シンボルをリストするスクリプトで
  す。

- scripts/docgen

  このスクリプトは、どの関数が資料化されることになっている (このリスト
  は gen-all-syms で得られます) か指定し、docproc を起動します。

- Makefile

  Documentation/DocBook 内に DocBook ファイル、PostScript ファイル、
  PDF ファイル、html ファイルを作成するために、ターゲットしてそれぞれ
  'sgmldocs', 'psdocs', 'pdfdocs', 'htmldocs' が使用されます。

- Documentation/DocBook/Makefile

  どの C ファイルが SGML テンプレートと関係するか示しています。


資料の抽出方法
--------------

様々なサブシステム (Documentation/DocBook/*.tmpl を参照してください)
の既製の本を単に読みたいなら、単に 'make psdocs', 'make pdfdocs',
'make htmldocs' のいずれかをあなたの好みにより入力してください。それ以
外の異なるフォーマットで読みたいなら、'make sgmldocs' と入力した後、
DocBook ツールを使用し Documentation/DocBook/*.sgml を希望するフォーマッ
トに変換できます (例えば 'make htmldocs' を指定しなかったなら、
'db2html ...')。

man ページを代わりに参照したければ、次で行えます。

$ cd linux
$ scripts/kernel-doc -man $(find -name '*.c') | split-man.pl /tmp/man
$ scripts/kernel-doc -man $(find -name '*.h') | split-man.pl /tmp/man

split-man.pl を以下に示します。

-->
#!/usr/bin/perl

if ($#ARGV < 0) {
   die "where do I put the results?\n";
}

mkdir $ARGV[0],0777;
$state = 0;
while (<STDIN>) {
    if (/^\.TH \"[^\"]*\" 4 \"([^\"]*)\"/) {
	if ($state == 1) { close OUT }
	$state = 1;
	$fn = "$ARGV[0]/$1.4";
	print STDERR "Creating $fn\n";
	open OUT, ">$fn" or die "can't open $fn: $!\n";
	print OUT $_;
    } elsif ($state != 0) {
	print OUT $_;
    }
}

close OUT;
<--

あるファイル内のある関数の資料だけを見たければ、次で行えます。

$ scripts/kernel-doc -man -function fn file | nroff -man | less

あるいは次の方法で -

$ scripts/kernel-doc -text -function fn file


ソースファイルへの抽出可能な資料の追加方法
------------------------------------------

ブロックコメントの書式は以下のようなものです。

/**
 * function_name(:)? (- short description)?
(* @parameterx: (description of parameter x)?)*
(* a blank line)?
 * (Description:)? (Description of function)?
 * (section header: (section description)? )*
(*)?*/

簡単な関数の説明 (short description) は複数行にできませんが、他の説明
(description)　は複数行にできます (また空行も含むことができます)。関数
名の後に見せかけの空行を置かないでください。さもないと説明が繰り返され
てしまいます。

さらに説明文はすべて、次の特別なパターンの場合、適切に強調が施されます。

'funcname()' - 関数
'$ENVVAR' - 環境変数
'&struct_name' - 構造体名 ('struct' を含む二つまでの単語)
'@parameter' - 引き数名
'%CONST' - 定数名

例はソースツリー内をながめてください。


新しい SGML テンプレートファイルの作成方法
------------------------------------------

SGML テンプレートファイル (*.tmpl) は、抽出された資料が挿入されるべき
場所を示すエスケープシーケンスを含むことができる以外は、普通の SGML ファ
イルと同様です。

!E<ファイル名> は <ファイル名> 内の EXPORT_SYMBOL を使用してエキスポー
トされている関数の資料と置きかえられます - 関数の一覧は
Documentation/DocBook/Makefile 内に記載されたファイル群から集められま
す。

!I<ファイル名> は EXPORT_SYMBOL を使用してエキスポートされていない関数
の資料と置きかえられます。

!F<ファイル名> <関数 [関数...]> は <ファイル名> 内で記載された関数の資
料と置きかえられます。


Tim.
*/ <twaugh@redhat.com>
日本語訳：野本浩一 <hng@ps.ksky.ne.jp>