第9章 ドキュメントツール

Red Hat Enterprise Linux 6 は、ソースコードからドキュメントを生成し、スタンドアローンのドキュメントを記述する Doxygen ツールを提供しています。

9.1. Doxygen

Doxygen は、オンラインの HTML とオフラインの Latex の両方で参照資料を作成するドキュメントツールです。これは、文書化されたソースファイルのセットから作成を行い、これによりドキュメントの一貫性を保ちソースコードとの正確性を保つことが容易になります。

9.1.1. Doxygen 対応の出力および言語

Doxygen は以下の主力をサポートします。
  • RTF (MS Word)
  • PostScript
  • ハイパーリンク付き PDF
  • 圧縮 HTML
  • Unix man ページ
Doxygen は以下のプログラム言語をサポートします。
  • C
  • C++
  • C#
  • Objective -C
  • IDL
  • Java
  • VHDL
  • PHP
  • Python
  • Fortran
  • D

9.1.2. 使用開始

Doxygen は設定ファイルを使ってセッティングを決定するので、これが正確に作成されることが非常に重要になります。各プロジェクトには、それぞれの設定ファイルが必要になります。最も簡単に設定ファイルを作成する方法は、doxygen -g config-file コマンドを使用する方法です。この方法だと、編集が容易なテンプレート設定ファイルが作成されます。変数 config-file は、設定ファイル名です。コマンドからコミットされた場合は、デフォルトで Doxyfile と呼ばれます。設定ファイル作成でのもうひとつの便利なオプションは、ファイル名にマイナス記号 (-) を使うことです。これは、標準出力 (stdin) から設定ファイルを Doxygen に読み取らせるようにするため、スクリプティングに便利なものです。
設定ファイルは、シンプルな Makefile と同様に、多くの変数およびタグから構成されます。
TAGNAME = VALUE1 VALUE2...
ほとんどの場合はこのままにしておいて構いませんが、編集の必要がある場合には、利用可能な全タグに関する詳しい説明は、Doxygen ドキュメント Web サイト 『configuration page』 を参照してください。また、doxywizard と呼ばれる GUI インターフェースもあります。この編集方法が望ましい場合は、機能についてのドキュメントは Doxygen ドキュメント Web サイトの 『Doxywizard usage page』 にあります。
以下の 8 つのタグは、慣れておくと便利なものです。
INPUT

C もしくは C++ ソースとヘッダーファイルで主に構成されている小規模プロジェクトの場合、なにも変更する必要はありません。ただし、プロジェクトが大型でソースディレクトリーやツリーで構成されている場合は、root ディレクトリー (単数または複数) を INPUT タグに割り当てます。

FILE_PATTERNS

ファイルパターン (たとえば、*.cpp や *.h) をこのタグに追加し、パターンのいずれかに適合するファイルのみを解析させることができます。

RECURSIVE

この設定を yes にすると、ソースツリーの再帰分析が可能になります。

EXCLUDE および EXCLUDE_PATTERNS

これらは、回避するファイルパターンを追加することで解析されるファイルをさらに細かくチューニングするために使用されます。たとえば、ソースツリーからすべての test ディレクトリーを省略するには、EXCLUDE_PATTERNS = */test/* を使用します。

EXTRACT_ALL

これを yes に設定すると、doxygen はプロジェクトが完全に文書化されるとどのように見えるかが分かるように、ソースファイル内のすべてが文書化されているかのように振る舞います。しかし、このモードでは、文書化されていないメンバーに関する警告は生成されません。終了時これを修正するには、no に設定を戻します。

SOURCE_BROWSER および INLINE_SOURCES

SOURCE_BROWSER タグを yes に設定すると、doxygen は相互参照を生成し、ソースファイル内で存在するドキュメントでソフトウェアの定義について分析します。これらのソースは、INLINE_SOURCES を yes に設定することでドキュメント内に含めることもできます。

9.1.3. Doxygen の実行

doxygen config-file を実行すると、html、rtf、latex、xml、および/または man ディレクトリーが doxygen が開始されたディレクトリー内に作成され、対応するファイルタイプのドキュメントが含まれます。
HTML OUTPUT

このドキュメントは、カスケードスタイルシート (CSS) や一部では DHTML や Javascript をサポートする HTML ブラウザーで閲覧することができます。ブラウザー (たとえば、Mozilla、Safari、Konqueror、Internet Explorer 6) を html の index.html に向けます。

LaTeX OUTPUT

Doxygen は、Makefile を latex ディレクトリーに書き込み、Latex ドキュメントの最初のコンパイルを容易にします。これを行うには、最新の teTeX ディストリビューションを使用します。このディレクトリーに含まれるものは、USE_PDFLATEX が no に設定されているかどうかに依存します。設定されている場合は、latex ディレクトリーで make と入力すると、refman.dvi が生成されます。これは、xdvi で閲覧するか、refman.ps と入力して make ps に変換することができます。これには dvips が必要であることに注意してください。

便利なコマンドは多くあります。make ps_2on1 は 2 ページを 1 ページに印刷できます。また、ghostscript インタプリターがインストールされていれば、make pdf コマンドで PDF に変換することもできます。ほかには make pdf_2on1 も有効なコマンドです。これを実行する際は、PDF_HYPERLINKS および USE_PDFLATEX タグを yes に設定します。こうすることで、Makefile には refman.pdf を直接ビルドするターゲットのみが含まれることになります。
RTF OUTPUT

このファイルは、RTF 出力を単一ファイルである refman.rtf と組み合わせることで Microsoft Word にインポートするように設計されています。情報の中にはフィールドを使ってエンコードされるものもありますが、これはすべてを選択し (CTRL+A または 編集 -> すべて選択)、右クリックをして toggle fields オプションをドロップダウンメニューから選ぶと表示することができます。

XML OUTPUT

xml ディレクトリーへの出力は多くのファイルで構成され、各複合ファイルは index.xml に加えて doxygen が収集したものです。XSLT スクリプトである combine.xslt も、すべての XML ファイルを単一ファイルに組み合わせるために作成されます。また、インデックスファイル用の index.xsd と複合ファイル用の compound.xsd という 2 つのXML スキーマファイルが作成され、これらは可能性のある要素、それらの属性、それらの構成方法を説明します。

MAN PAGE OUTPUT

man ディレクトリーからのドキュメントは、manpath の man path に正確な man ディレクトリーがあることを確認した後で man プログラムを使って閲覧できます。man ページ形式の制限により、図や相互参照、式といった情報は失われることに留意してください。

9.1.4. ソースの文書化

ソースを文書化するには 3 つのステップがあります。
  1. まず、EXTRACT_ALL が no に設定され、警告が正確に生成され、ドキュメントが適切にビルドされることを確認します。これにより、doxygen は文書化されたメンバー、ファイル、クラス、ネームスペースのドキュメントを作成できます。
  2. このドキュメントを作成するには 2 つの方法があります。
    特別な ドキュメントブロック
    このコメントブロックには追加のマーキングが含まれていることで Doxygen はこれがドキュメントの一部であることが分かり、C もしくは C++ で書かれています。簡単な説明もしくは詳細な説明で構成されています。これらはどちらもオプションです。しかし、本文 の説明はオプションではありません。これがメソッドもしくは関数の本文で見つかるすべてのコメントブロックを結びつけます。

    注記

    簡単もしくは詳細な説明は 1 つ以上が認められますが、順番が指定されないのでこれは推奨されません。
    以下で、コメントブロックを詳細な説明としてマークする方法を詳述します。
    • JavaDoc スタイルで 2 つのアスタリスク (*) で始まる C スタイルコメントブロック 
      /**
 * ... documentation ...
 */
    • Qt スタイルを使用した C スタイルコメントブロック。もうひとつのアスタリスクの代わりに感嘆符 (!) で構成されています。 
      /*!
 * ... documentation ...
 */
    • ドキュメント行の最初のアスタリスクは、なくても構いません。
    • C++ では最初と最後の行は空白でもよく、スラッシュ 3 つか、スラッシュ 2 つと感嘆符を付けます。 
      ///
/// ... documentation
///
      または 
      //!
//! ... documentation ...
//!
    • 別の方法としては、コメントブロックをより見やすくするために、アスタリスクもしくはスラッシュの行を使うことができます。 
      /////////////////////////////////////////////////
/// ... documentation ...
/////////////////////////////////////////////////
      または 
      /********************************************//**
 * ... documentation ...
 ***********************************************/
      通常のコメントブロックの最後にあるスラッシュ 2 つが特別なコメントブロックの開始となっていることに注意してください。
    ドキュメントに簡単な説明を加えるには 3 つの方法があります。
    • 簡単な説明を追加するには、コメントブロックの上に \brief を使います。この簡単なセクションは段落の最後で終わり、それ以降の段落は詳細な説明になります。 
      /*! \brief brief documentation.
 *         brief documentation.
 *
 *  detailed documentation.
 */
    • JAVADOC_AUTOBRIEF を yes に設定することで、簡単な説明は最初のドットとその後の空白もしくは新たな行までしか続きません。このため、簡単な説明は単一行に制限されています。 
      /** Brief documentation. Detailed documentation continues * from here.
 */
      これは、上記の 3 つのスラッシュ (///) のコメントブロックでも使用できます。
    • 3 つ目のオプションは、特別な C++ スタイルコメントを使用して、1 行以上に及ばないようにします。 
      /// Brief documentation.
/** Detailed documentation. */
      または 
      //! Brief documentation.

//! Detailed documentation //! starts here
      上記の例の空白の行は、簡単な説明と詳細な説明を分けるために必要で、JAVADOC_AUTOBRIEF を no に設定する必要があります。
    Qt スタイルを使って文書化された C++ コードの例は、『Doxygen documentation website』 にあります。
    ファイル、構造体、ユニオン、クラス、enum のメンバーの後にドキュメントを持ってくることも可能です。 < マーカーをコメントブロック \ の後に追加します。 
    int var; /*!< detailed description after the member */
    Qt スタイルでは以下のようになります。 
    int var; /**< detailed description after the member */
    または 
    int var; //!< detailed description after the member
         //!<
    または 
    int var; ///< detailed description after the member
         ///<
    メンバーユースの後の簡単な説明は、以下のようになります。 
    int var; //!< brief description after the member
    または 
    int var; ///< brief description after the member
    これらの例と HTML の作成方法は 『Doxygen documentation website』 で確認できます。
    他の場合でのドキュメント
    文書化しているコードの前にドキュメントを置くのが望まれますが、特にファイルを文書化する場合などはファイルの前にドキュメントを置くことは不可能なので、異なる場所にしか置けない場合もあります。異なる場所に置くと情報の重複が発生する可能性があるので、絶対に必要な場合以外はこれを避けることが最善策となります。
    これを行うには、構造コマンドをドキュメントブロック内に持つことが重要になります。構造コマンドは JavaDoc では、バックスラッシュ (\) もしくはアットマーク (@) で始まり、その後に 1 つ以上のパラメーターが続きます。 
    /*! \class Test
    \brief A test class.
    
    A more detailed description of class.
 */
    上記の例では、\class コマンドが使われています。これは、コメントブロックにクラス 'Test' のドキュメントが含まれていることを示しています。他の例では、
    • \struct: C 構造体を文書化します。
    • \union: union を文書化します。
    • \enum: 列挙タイプを文書化します。
    • \fn: 関数を文書化します。
    • \var: 変数、typedef、enum 値を文書化します。
    • \def: #define を文書化します。
    • \typedef: document a type definition
    • \file: ファイルを文書化します。
    • \namespace: ネームスペースを文書化します。
    • \package: Java パッケージを文書化します。
    • \interface: IDL インターフェースを文書化します。
  3. 次に、特別なドキュメントブロックを HTML および / Latex 出力ディレクトリーに書き込む前に、解析します。以下の手順が含まれます。
    1. 特別なコマンドを実行します。
    2. 空白およびアスタリスク (*) をすべて削除します。
    3. 空白の行を新たな段落として取り扱います。
    4. 単語が対応するドキュメントにリンク付されます。単語の前にパーセンテージ記号 (%) がある場合は、その記号を削除して単語を残します。
    5. テキストに特定のパターンが見つかった場合は、メンバーへのリンクが作成されます。この例は、Doxygen ドキュメント Web サイトの 『automatic link generation page』 にあります。
    6. ドキュメントが Latex についての場合は、HTML タグが Latex のタグに相当するものに変換されます。サポート対象の HTML タグは Doxygen ドキュメント Web サイトの 『HTML commands page』 にあります。

9.1.5. リソース

詳細情報は以下の Doxygen web サイトで見られます。