読者です 読者をやめる 読者になる 読者になる

M12i.

学術書・マンガ・アニメ・映画の消費活動とプログラミングについて

Doxygenで呼び出し関係図を含むドキュメントを生成する

Java C#

保守対象のC#ソースコードを都度々々一から解析してAstahのコミュニティ・エディションでこつこつUML化するのにはいい加減飽きてきたので、既存リソースからドキュメント生成するツールを探していました。
結果、DoxygenというJavaC#やその他いろいろに対応した汎用ツールがあることを知り、実際に使用してみました。

f:id:m12i:20140125220619p:plain

使用するにあたり参考にしたのはこちらのサイトの以下の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」(本記事執筆時点での最新安定版)をダウンロードします。

DoxygenGraphvizを任意のパスに配置

ダウンロードしたDoxygenGraphvizの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

f:id:m12i:20140125221313p:plain

加えて以下のように呼び出し/被呼び出し図も表示されています:

f:id:m12i:20140125221327p:plain

*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に変更した上でドキュメント生成を行っています。これらの設定項目によって、ドキュメント化対象となるクラスやクラス・メンバーのアクセス・レベルを変更できます。