doxygenを使用してC#のドキュメントを自動生成する(その2)

前回の記事で、C#のソースコードからドキュメントの自動生成が出来るようになりました。
今回は、ソース内のクラス階層や、関数の呼び出し関係を可視化する為にグラフ(画像)を表示できるようにします。

こんな感じで、どの関数が、どの関数をコールしているかを一目で分かるようにするのが目的です。

doxygenがグラフを生成する仕組み

doxygenは、自力でグラフ画像の生成することは出来ず、graphvizというソフトを利用しています。
graphvizは、AT&Tが開発したオープンソース(Common Public License ライセンス)のソフトウェアで、テキスト形式の設定ファイルより、以下のような画像を生成することが出来ます。

graphvizのセットアップを行う

まずは、準備としてgraphvizのセットアップを行い、単体で動作することを確認します。

下記のサイトへアクセスします。
http://www.graphviz.org/

画面左のdownloadをクリックします。

Executable Packageの下にある、リンクよりダウンロードを行います。

ダウンロードが出来たらセットアップを行います。
公式サイトからは、msiイメージのみがダウンロードできるので、通常だとインストールが必要です。

今回は、exeだけ入手できれば良いので、以下のコマンドでmsiパッケージからファイルの抽出を行います。
※下記の例では、c:\workにあるmsiファイルを、c:\work\extractに展開しています(途中で折り返していますが、実際は1行で記入します)

start /wait msiexec /a c:\work\graphviz-2.28.0.msi targetdir="c:\work\extract" /qn 
/li "c:\work\install.log"

インストーラからセットアップしたい場合は、ダウンロードしたgraphviz-x.xx.msiを実行します。
以下のようにインストール先を聞かれるだけなので、セットアップ自体は簡単です。

ファイルを展開したら、上記のファイル達を、doxygen.exeのあるフォルダにコピーしてしまいます。
(この作業は必須では有りませんが、1つのフォルダに纏めておくとUSBメモリなどで持ち運ぶ際に便利です)

無事graphvizがセットアップできたら、動作確認を行います。
エディタでテスト用のファイルを作成して…

graph graphname {
    a -- b -- c;
    b -- d;
}

  <p>bin\dot.exe -Tjpg test.txt -o test.jpg</p>

test.jpgが生成されていればOKです。

doxygenでgraphvizを使用する

次に、doxygenでgraphvizを使用できるようにします。graphviz用の設定は、Doxyfileを編集します。

HAVE_DOT               = NO
DOT_PATH               =
SOURCE_BROWSER         = NO
CALL_GRAPH             = NO
CALLER_GRAPH           = NO

HAVE_DOT               = YES
DOT_PATH               = .\graphviz\bin\
SOURCE_BROWSER         = YES
CALL_GRAPH             = YES
CALLER_GRAPH           = YES

各パラメータの意味は以下のとおりです。

HAVE_DOT       : dot(graphvizに入っているコマンドdot.exe)を使用するか
DOT_PATH       : dot.exeのある場所
SOURCE_BROWSER : ドキュメントからソースへのリンクを付与するか
CALL_GRAPH     : 呼び出しグラフ(自分が誰をcallしているか)を表示するか
CALLER_GRAPH   : 呼び出されグラフ(誰から自分がcallしているか)を表示するか

上記の内、SOURCE_BROWSERはグラフ表示と直接関係ないのですが、SOURCE_BROWSERをYESにしておかないと画像が出力されないようなのでYESにしてます。

ここまで設定したら、再度doxygen.exeを実行します。

実行後、ドキュメントを確認すると…、なぜか画像が出来ていません

htmlフォルダの中を確認してみると、graph_legend.htmlというファイルが追加で作成されています。
graph_legendのファイルは、文字通りグラフの凡例なので、どうやらHAVE_DOTの定義自体は認識されているようです。

ここで、なぜ画像が生成されないのか、小一時間悩んだのですが…　どうやら今回対象としたMarkdownSharpは、クラス数･コードの構造がシンプルすぎで表示すべきグラフがまったく無かったという凡ミスでした。

ですので、今回は確認のために以下のパラメータを追加で変更しました。

EXTRACT_PRIVATE        = NO
　↓
EXTRACT_PRIVATE        = YES

EXTRACT_PRIVATEは、プライベートなメソッドの情報をドキュメント生成するかのフラグです。他から利用するライブラリ等のドキュメントを生成する場合は、privateなメソッド情報は不要なのでNOのままの方が分かりやすいのですが、ライブラリ自体の解析をしたい場合はYESしておくと便利なパラメータです。

改めて、doxygen.exeを実行します。なにやらグラフが生成されてそうなログが出力されました。

クラスのドキュメントを確認すると…、無事呼び出しグラフが出力されました!!
(画像が横長すぎて画面からはみ出てますが…この辺は次回調整します)

今回は以上です。
次回は、細かな見た目の改善を行います。