ドキュメントの作り方

開発を進めていくうちにドキュメントは作っておきたいけど、面倒そうだなってことがあると思います。そこでDoxygenとGraphvizを使ってドキュメントを生成する方法を共有します。

個人的にドキュメントを生成するサーバにDebianを使っているので、DoxygenとGraphvizはapt-getコマンドでインストールできます。

$ sudo apt-get install doxygen

$ sudo apt-get install graphviz

Macの方はこちらの記事がとても分かりやすいです。
http://d.hatena.ne.jp/eitya/20110623/1308826061

インストールが終わるとdotコマンドとdoxygenコマンドが使えるようになっています。
コマンドが使えない方はパスを通してください。

プロジェクトのルートディレクトリに移動して、以下のコマンドでドキュメントを生成するための設定ファイルを作ります。

$ doxygen -g

Doxyfileという名前で設定ファイルが生成されます。
そのファイルを開いて言語の設定や対象とするファイルの設定を行います。

個人的にプロジェクトのlibsディレクトリはドキュメント化から省くように設定しました。プロジェクトによって変わる所があると思いますが、だいたい以下の項目を設定しました。

PROJECT_NAME = "Cocos2d-x Test Project"
OUTPUT_LANGUAGE = Japanese
FILE_PATTERNS = *.cpp *.h *.mm *.java
SOURCE_BROWSER = YES
ALPHABETICAL_INDEX = YES
EXTRACT_ALL = YES
GENERATE_LATEX = NO
HAVE_DOT = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES
EXCLUDE_PATTERNS = */cocos2dx_test/libs/*

そして、設定ファイルがあるディレクトリで以下のコマンドを実行するとhtmlディレクトリが生成されます。

$ doxygen

htmlディレクトリの中のindex.htmlをブラウザで開いてみてください。

クラス同士の関係が図で表示され、メソッドの詳細なども表示されたと思います。

さらにクラスやメソッドの説明をしっかり書いたり、ドキュメントの生成を定期的に行うようにすることで、もっと見やすいドキュメントになっていきます。

説明の書き方は以下が参考になります。
http://www.02.246.ne.jp/~torutk/cxx/doxygen/doxygenstyles.html