今更ながらDoxygenの使い方をまとめました。
Table of Contents
1 Doxygenとは
ソースコードからHTMLドキュメントを作成するツールです。Doxygenの作法に則ったソースコードにコメントを書くことでHTMLドキュメントに反映されます。JavaDoc形式のコメントもサポートしています。
APIドキュメントとソースコードを一致させるのに苦労している場合は是非導入すべきです。多くのオープンソースでも採用されています。よそから持ってきたソースコードを読む際にも有用です。
2 コメントの例
関数のコメントは以下のようになります。
/** * Comment for foo function. * @param value Comment for value. * @return Comment for return value. */ bool foo(int value)
出力されるHTMLは以下のようになります。
コメントの形式の雛形を出力するツールを導入すると良いでしょう。emacsならばDoxymacsがあります。
3 Doxyfile
doxygenの設定を記述するファイルです。最低限の変更が必要なのは以下の３つです。
| INPUT | ソースコードのディレクトリとファイル |
| RECURSIVE | ソースコードを再帰的に見つける |
| OUTPUT_DIRECTORY | doxygenの生成物を出力するディレクトリ |
| EXCLUDE | 除去するディレクトリとファイル |
INPUTでディレクトリ全体を指定してから、EXCLUDEでソースコードを除去するのも良いでしょう。INPUTやEXCLUDEは+=で複数行に渡り設定することができます。
EXCLUDE = <directory> EXCLUDE += <sourcecode>
3.1 doxygen -gで作成
必要最低限の雛形が作成されます。以下はカレントディレクトリ配下のソースコードを全て含める場合の例です。
$ doxygen -g $ sed -i -e 's/^INPUT *= */INPUT = ./g' \ -e 's/^RECURSIVE *= *NO/RECURSIVE = YES/g' \ -e 's/^OUTPUT_DIRECTORY *= */OUTPUT_DIRECTORY = doxygen/g' Doxyfile $ doxygen
3.2 DoxyWizardで作成
GUIのガイドに従ってDoxyfileを作成するツールです。
OSXの場合はHomebrewでインストールすると良いでしょう。
$ brew install doxygen --with-doxywizard
Ubuntu 14.04の場合はaptでdoxywizardパッケージをインストールできます。
$ sudo apt-get install -y doxygen-gui
4 Warningをエラーとして扱う
オプションがあれば良いのですが、どうもないらしいので、Warningメッセージがあった場合はエラーとして扱うラッパースクリプトを用意します。
DoxygenのWarningメッセージは標準エラー出力に出力されるため、標準エラー出力をファイル保存しておき、保存されたファイルをWarningメッセージでgrepします。
#!/bin/sh touch doxygen.log doxygen 2> doxygen.log grep " warning: " doxygen.log if [ $? -eq 0 ]; then exit 1 fi exit 0
このスクリプトをMakefile等で呼び出すようにしておけば、makeの延長でエラーとなります。Doxygenコメントがないコミットをなくすことができるでしょう。