doxygen と Graphviz でドキュメントを生成してみる＠Mac OS X

まず、doxygen と Graphviz をインストールしましょう

graphviz のHP

左側に Download の項目があるのでそこをクリック。
すると、OS ごとにページが分かれてるっぽい感じになってるので、それぞれに対応したものを取っちゃって下さい。
今回は Mac OS の snow leopard を使います。

pkg ファイルなので DL が完了したらすぐインストールしちゃいましょう。

インストールが完了したら、

$ which dot

で PATH が通っているか確認。通ってたら次へ。通ってなかったら PATH の設定を書き込んであげます。
/usr/local/bin
の PATH を通せばいいはず。

次に doxygen のインストールをします。

doxygen のHP

Doxygen

今度は右側に Download の項目があります。こちらの方も Mac OS X版を取りましょう。
dmg ファイルを取ったら、インストールしましょう。

こっちも PATH を通す必要があるので、

export PATH=/Applications/Doxygen.app/Contents/Resources/:$PATH

を記述して、 source コマンドで読み込みします。
これで準備完了。

それじゃー実際に作ってみます。

ドキュメントを作りたいディレクトリまでまずは移動します。
移動したら、

$ doxygen -g [ConfigName]

で設定ファイルを作成します。
（[ConfigName]は省略可能です。省略した場合は "Doxyfile" という名前で作成されます。）

それじゃあ実際に設定をいじりましょう。
いろんな場面にあった設定があるわけなので、一概に言う事は出来ないのですが、今回の私の場合だと以下の設定になりました。

PROJECT_NAME           = PROJECT_X
OUTPUT_LANGUAGE        = Japanese
OPTIMIZE_OUTPUT_FOR_C  = YES
FILE_PATTERNS          = *.c *.h
SOURCE_BROWSER         = YES
ALPHABETICAL_INDEX     = YES
EXTRACT_ALL            = YES
GENERATE_LATEX         = NO
HAVE_DOT               = YES
CALL_GRAPH             = YES
CALLER_GRAPH           = YES

こんな感じでした。
設定ファイルは1,000行軽く超えちゃっててびっくりしました。ほとんどコメントでしたけどね。

さて、これで準備は整いました。あとは

$ Doxygen [ConfigName]

をするだけです。最初の設定ファイルを作るときに [ConfigName] を省略した人はこっちも省略でオッケー。

すると、今いるディレクトリに html というディレクトリが作られているはず。
そのディレクトリの中の index.html が今回の目的のファイルです。

$ open html/index.html

で開けます。

でも、この状態だとほとんど何も書き込まれていない状態で少し寂しい。
そのため、 doxygen ではソースにコメントを付けることで、作者やプロジェクトの説明、日付、変数の解説といったいろんなことを記述できるようになります。
その辺りはまた今度追記します。

早速追記。

まずは、main ページの書き方について
プログラムのtopに記述します。

/** \mainpage
  * \date 6/24
  * \author えいちゃ
  * \par タイトル
  * 説明。*/

こんな感じです！
最初の "/**" で doxygen のコメントというように認識されます。

次に、関数の説明の仕方です。
これは、関数の頭に書いてあげましょう。

/** @brief [関数の説明]
  * @param [変数名] [変数の説明]
  * @param [変数名] [変数の説明]
  * @retval [返り値の説明] */

こんな感じ。

これで、最低限の内容は書けている感じに。

書き終わったら、もう一度 doxygen コマンドを使って、再度 html/index.html を open してください。
すると...

あとは自分の目で確認してみてください。