はじめに
私事ですが、最近転職しました。
新しい組織での業務をキャッチアップするために、ソースコードを読み解いて理解する必要がありますが、私はよくDoxygenを使います。
ドキュメント生成だけじゃない
Doxygenと言えば、主に「コメントに記載した引数や返り値の情報をHTMLに整形して出力する」ことが目的のツールであると認識されていると思いますが、その他にも様々な機能があり、コードの読解にとても役に立ちます。
- ディレクトリ階層
- クラス階層
- 関数の呼び出し・被呼び出しグラフ
- 変数の宣言部、使用部へのジャンプ
上記がHTMLでリンクをたどれるように出力されるので、プロジェクト全体を把握するのにだいぶ助けとなります。
それぞれ、Graphviz、GNU Globalが必要となります。あらかじめインストールしておくことをお勧めします。
大半のLinuxディストリビューションであればパッケージが用意されていますので、yumなりaptなりでインストールできます。
対応している言語についても、公式ドキュメントに以下のようにあります。
C/C++、Java、(Corba およびマイクロソフト) Java、Python、 IDL、C#、Objective-C をサポートしており、D と PHP のソースにもある程度対応しています。
Ruby、JavaScriptは対応してないのか、、、残念。
手順
(1) ドキュメントを生成したいソースツリーの最上部で、下記を実行します。
$ doxygen -g
(2) 生成されたDoxyfileをプロジェクトに合わせてカスタマイズしていきます。
各項目の詳細な説明はリファレンスをご参照ください。
以下は、私のおすすめ設定です。
# プロジェクト名。Doxygenドキュメントのタイトルなどに使われます。
-PROJECT_NAME = "My Project"
+PROJECT_NAME = "任意のプロジェクト名"
# 言語を選択します。（が、あんまり影響はないかも。）
-OUTPUT_LANGUAGE = English
+OUTPUT_LANGUAGE = Japanese
# FULL_PATH_NAMES がYESの場合、ファイル名がフルパスで出力され、けっこうわずらわしいです。
-FULL_PATH_NAMES = YES
+FULL_PATH_NAMES = NO
# とりあえず全部出す
-EXTRACT_ALL = NO
+EXTRACT_ALL = YES
# とりあえず全部出す
-EXTRACT_PRIVATE = NO
+EXTRACT_PRIVATE = YES
# とりあえず全部出す
-EXTRACT_STATIC = NO
+EXTRACT_STATIC = YES
# とりあえず全部出す
-EXTRACT_ANON_NSPACES = NO
+EXTRACT_ANON_NSPACES = YES
# ソースツリーのフォルダ構成が深い場合はマスト
-RECURSIVE = NO
+RECURSIVE = YES
# 外部パッケージのディレクトリなどはパッケージの数によっては時間がかかりますので、適宜除外します。
-EXCLUDE =
+EXCLUDE = ./vendor
# ソースコードをドキュメントに含めます
-SOURCE_BROWSER = NO
+SOURCE_BROWSER = YES
# 被呼び出し関数一覧
-REFERENCED_BY_RELATION = NO
+REFERENCED_BY_RELATION = YES
# 呼び出し関数一覧
-REFERENCES_RELATION = NO
+REFERENCES_RELATION = YES
# HTMLの出力ディレクトリを指定します。任意のディレクトリ名でかまいません。
-HTML_OUTPUT = html
+HTML_OUTPUT = doxygen
# LaTexいらない
-GENERATE_LATEX = YES
+GENERATE_LATEX = NO
# 呼び出しグラフ
-CALL_GRAPH = NO
+CALL_GRAPH = YES
# 被呼び出しグラフ
-CALLER_GRAPH = NO
+CALLER_GRAPH = YES
(3) doxygen コマンドを実行し、ドキュメントを生成します。
いかがでしたでしょうか？（って言いたいだけ
使いようによってはコードリーディングの大きな助けとなります。もう一度Doxygenを見直してみてはいかがでしょうか。