Doxygenで呼び出し関係図を含むドキュメントを生成する
保守対象のC#のソースコードを都度々々一から解析してAstahのコミュニティ・エディションでこつこつUML化するのにはいい加減飽きてきたので、既存リソースからドキュメント生成するツールを探していました。
結果、DoxygenというJavaやC#やその他いろいろに対応した汎用ツールがあることを知り、実際に使用してみました。
使用するにあたり参考にしたのはこちらのサイトの以下の2つの記事です：
2年前の記事ということで、若干当時と状況が違うようでしたので、私が今回行った手順を以下にメモしておきます。
Doxygenの実行ファイルを取得
Doxygenの公式サイトにアクセス。［Doxygen］→［Downloads］と進んで、
「A binary distribution for Windows. All versions of Windows since XP are supported.」というセクションのリンク「32-bit doxygen binary in a zip」をクリックして32bit版をダウンロードします。
ちなみに本記事を執筆している段階では、上記実行ファイルのバージョンは1.8.6でした。
Graphvizの実行ファイルを取得
Doxygenはクラス図等を生成するのにGraphvizという外部プログラムを使用します。
こちらも公式サイトにアクセス。［Download］→［Windows］→［Stable and development Windows Install packages］と進み、「current stable release」となっている「graphviz-2.36.zip」（本記事執筆時点での最新安定版）をダウンロードします。
DoxygenとGraphvizを任意のパスに配置
ダウンロードしたDoxygenとGraphvizのZipファイルを解凍し、それぞれの実行ファイルを任意のパスに配置します。
ちなみに私の場合は下記のようにしました：
C:\
├doxygen
│└1.8.6
│ ├doxygen.exe
│ └...
└graphviz
└2.36
└bin
├dot.exe
└...
実行ファイルのフォルダパスを環境変数Pathに追加
環境変数Pathの末尾に前述の実行ファイルのフォルダパスを追加（...;C:\doxygen\1.8.6;C:\graphviz\2.36\bin）して［OK］。これで下準備は完了です。
この手順は必須ではないものの、やっておいたほうがやはり何かと便利です。とくにGraphvizのパス指定については、環境変数で設定しない場合、Doxygenのドキュメント生成設定ファイルで個別に設定することになり面倒です。
Doxygenのドキュメント生成設定ファイルを作成
ここからはドキュメント化したい個別のプロジェクト（あるいは単にソースコードのファイルセット）に対して行う作業。
Doxygenはドキュメント生成時の設定（ドキュメント化対象のファイルセットの指定も含む）をDoxyfileという名前のテキストファイルから読み取ります。
以下のように何のオプションも設定せずコマンドを実行すると、カレントディレクトリの「Doxyfile」ファイルを使用してドキュメント生成が行われます。もし「Doxyfile」というファイルが見つからなければ、USAGEが表示されます。
doxygen
またもしカレントディレクトリ以外のところに格納された設定ファイルを使用する場合は、以下のようにファイルパス指定で実行します。
doxygen C:\foo\bar\Doxyfile
以下のコマンドを実行するとDoxyfileの初期設定ファイルが作成できます。
doxygen -g
Doxyfileを書き換える
Doxyfikeをテキストエディタで開き、以下の要領で修正を加えます。
| 設定項目名（TAG） | 意味 | 変更内容 |
|---|---|---|
| INPUT | ドキュメント化の対象としたいソースコードの格納されたディレクトリのパス | デフォルトではブランクとなっているので、適宜設定を行うこと*1。 |
| RECURSIVE | INPUTで指定されたディレクトリ配下を再帰的にスキャンするかどうか | デフォルトでNOとなっているので、YESに変更する。もし対象のソースコードが上記INPUTで指定したフォルダ直下にフラットに格納されているのであればNOのままでよいが、ふつうはディレクトリツリーに格納されているはず。 |
| HAVE_DOT | Graphvizが利用可能かどうか＝Graphvizによる図（画像）の作成を行うかどうか | デフォルトがNOとなっているので、YESに変更する。 |
| CALL_GRAPH | メソッド呼び出し関係図を生成するかどうか | デフォルトではNOとなっているのでYESに変更する*2。 |
| CALLER_GRAPH | 被メソッド呼び出し関係図を生成するかどうか | デフォルトではNOとなっているのでYESに変更する*3。 |
なお、前述の2つの記事では「DOT_PATH」というGraphvizの実行ファイル（dot.exe）が格納されたパスを設定する項目（TAG）も変更対象として登場します。しかし、同パスがあらかじめ環境変数Pathに設定されていれば、この設定変更は不要です*4。
Doxygenを実行してドキュメント生成を行う
以上で準備は完了です。あとはdoxygenコマンドを実行すると、カレントディレクトリに「html」と「latex」というフォルダが作成され、その配下にそれぞれのフォーマットでドキュメントが出力されます。
以下のように各クラスごとにドキュメントが生成され*5：
加えて以下のように呼び出し／被呼び出し図も表示されています：
*1:INPUTをブランクのままにすると、Doxygenはカレントディレクトリ配下をスキャンしてドキュメント化対象のソースコードを探そうとします。
*2:なお、doxygen -gコマンドで自動生成されたDoxyfileのコメントには、CALL_GRAPHについて「Note that enabling this option will significantly increase the time of a run.」（このオプションを有効化するとDoxygenの実行時間が顕著に増加します）とあります。
*3:CALL_GRAPHと同じくDoxygenの実行速度に影響「大」のようです。
*4:DOT_PATHのデフォルト値はブランクです。同項目がブランクとなっている場合、Doxygenは環境変数Pathを使用してGraphvizの実行ファイルを探します。
*5:この例ではEXTRACT_PRIVATEやEXTRACT_PACKAGE、EXTRACT_STATICといった設定項目についてもYESに変更した上でドキュメント生成を行っています。これらの設定項目によって、ドキュメント化対象となるクラスやクラス・メンバーのアクセス・レベルを変更できます。
