第9章 ドキュメントツール
9.1. Doxygen
9.1.1. Doxygen 対応の出力および言語
- RTF (MS Word)
- PostScript
- ハイパーリンク付き PDF
- 圧縮 HTML
- Unix man ページ
- C
- C++
- C#
- Objective -C
- IDL
- Java
- VHDL
- PHP
- Python
- Fortran
- D
9.1.2. 使用開始
doxygen -g config-file コマンドを使用する方法です。この方法だと、編集が容易なテンプレート設定ファイルが作成されます。変数 config-file は、設定ファイル名です。コマンドからコミットされた場合は、デフォルトで Doxyfile と呼ばれます。設定ファイル作成でのもうひとつの便利なオプションは、ファイル名にマイナス記号 (-) を使うことです。これは、標準出力 (stdin) から設定ファイルを Doxygen に読み取らせるようにするため、スクリプティングに便利なものです。
TAGNAME = VALUE1 VALUE2...
doxywizard と呼ばれる GUI インターフェースもあります。この編集方法が望ましい場合は、機能についてのドキュメントは Doxygen ドキュメント Web サイトの 『Doxywizard usage page』 にあります。
INPUTC もしくは 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. ソースの文書化
- まず、
EXTRACT_ALLがnoに設定され、警告が正確に生成され、ドキュメントが適切にビルドされることを確認します。これにより、doxygen は文書化されたメンバー、ファイル、クラス、ネームスペースのドキュメントを作成できます。 - このドキュメントを作成するには 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 インターフェースを文書化します。
- 次に、特別なドキュメントブロックを HTML および / Latex 出力ディレクトリーに書き込む前に、解析します。以下の手順が含まれます。
- 特別なコマンドを実行します。
- 空白およびアスタリスク (*) をすべて削除します。
- 空白の行を新たな段落として取り扱います。
- 単語が対応するドキュメントにリンク付されます。単語の前にパーセンテージ記号 (%) がある場合は、その記号を削除して単語を残します。
- テキストに特定のパターンが見つかった場合は、メンバーへのリンクが作成されます。この例は、Doxygen ドキュメント Web サイトの 『automatic link generation page』 にあります。
- ドキュメントが Latex についての場合は、HTML タグが Latex のタグに相当するものに変換されます。サポート対象の HTML タグは Doxygen ドキュメント Web サイトの 『HTML commands page』 にあります。
