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

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

- scripts/kernel-doc

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

- Documentation/DocBook/*.tmpl

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

- scripts/docproc.c

  SGML テンプレートファイルを SGML ファイルに変換するためのプログラム
  です。ファイルが参照されると、内部関数と外部関数を区別できるように
  するため、その中のエクスポートされているシンボル (EXPORT_SYMBOL) を
  サーチします。文書化する関数の一覧を与えて kernel-doc を起動します。
  加えて、このプログラムは、参照されている全てのファイルの位置を特定
  するために SGML テンプレートファイルをスキャンするのにも使われます。
  これは、make で使われるような依存情報を生成するために使用されます。

- 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 を使用してエクスポートされていない関数
の文書と置きかえられます。

!D<ファイル名> は、EXPORT_SYMBOL を使用してエクスポートされている関数を
サーチする追加ファイル群を指定するのに使用されます。

!F<ファイル名> <関数 [関数...]> は、<ファイル名> 内のリストされている
関数の文書と置きかえられます。


Tim.
*/ <twaugh@redhat.com>

------------------------------------------------------------
翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
最終更新： 2004/05/04
翻訳者：   野本 浩一 <hng(a)ps.ksky.ne.jp>
更新：     川崎 貴彦 <takahiko(a)hakubi.co.jp>