きのうJubatus 0.7.0がリリースされました。banditアルゴリズムのサポート、組み合わせ特徴のサポート、近傍探索ベースの線形分類器の追加など、なかなか熱い内容になっていると思います。さて、先日のJubatusカジュアルもくもく会 #1に参加したときに、「Doxygenのドキュメントとかソースコードの資料ありますか？」という声を小耳に挟んだので、Doxygenで自動生成して公開してみました。
JubatusのソースコードはDoxygenのスタイルでコメントされているわけではないので、少しさみしい雰囲気ですが、クラスの継承関係図やコールグラフなどがソースコードリーディングの役に立つかもしれません。Doxygenの設定ファイルは、次の方針で用意しました。
- html形式で出力する
- jubatus_coreオリジナルのソースコードのみを対象とする(サードパーティのソースコードは対象としない)
- ソースコードも埋め込んで実装も見れるようにする
- クラスの継承関係図やコールグラフも見れるようにする
DoxygenとGraphvizは、現時点でhomebrewでインストールできる最新版を使いました。
- Doxygen 1.8.9.1
- Graphviz 2.38.0
Doxyfileとビルドスクリプトへの修正パッチは自分のリポジトリのfeature-doxygenブランチに置いてあります。DoxygenとGraphvizがインストールされている環境であれば、
$ ./waf docs
もしくは、
$ make docs
を実行することでbuild/docsディレクトリ以下にドキュメントが自動生成されます。./waf distcleanでドキュメントも削除されます。
どの程度役に立つか分かりませんが、特徴抽出周りのソースコードを読み直したいと思っていたので、自分で使ってみようと思います。
以下はDoxygenのデフォルト設定から修正した設定名と設定値です。
| 設定名 | 設定値 | 説明 |
|---|---|---|
| PROJECT_NAME | jubatus_core | プロジェクト名。 |
| PROJECT_NUMBER | 0.1.0 | バージョン番号。jubatus_coreのバージョン番号をそのまま使用。 |
| PROJECT_BRIEF | “Jubatus: Online machine learning framework for distributed environment” | 概要。ソースコードのコメントから引用。 |
| OUTPUT_DIRECTORY | build | distclean時に一緒に消えるようにbuildディレクトリ以下にドキュメントを生成する。 |
| EXTRACT_ALL | YES | コメントがついていないモジュールもすべてドキュメントに出力する。 |
| EXTRACT_PRIVATE | YES | クラスのプライベートメンバもすべてドキュメントに出力する。 |
| EXTRACT_PACKAGE | YES | パッケージや内部スコープを持つメンバーをすべてドキュメントに出力する。 |
| EXTRACT_STATIC | YES | クラスのstaticメンバもすべてドキュメントに出力する。 |
| SORT_BRIEF_DOCS | YES | 名前空間やクラスのメンバ、ファイルの概要を名前のアルファベット順でソートする。宣言順の方が良いけど、読みにくいのでソートする。 |
| SORT_GROUP_NAMES | YES | グループの名前の階層をアルファベット順でソートする。グループのアノテーションは使われていないと思うが、ソートしておく。 |
| SORT_BY_SCOPE_NAME | YES | クラス一覧を名前空間を含めた完全修飾名のアルファベット順でソートする。 |
| INPUT | jubatus/core | jubatus/core以下を対象とする。jubatus/utilはpficommonの移植なので除く。 |
| FILE_PATTERNS | *.h *.hpp *.cpp | 対象とするファイル名のパターン。jubatus/util用に*.hも追加したが、不要かもしれない。 |
| RECURSIVE | YES | ディレクトリを再帰的に見るために必要。 |
| EXCLUDE | jubatus/core/third_party | サードパーティのライブラリ(Eigen)のドキュメントは除く。 |
| EXCLUDE_PATTERNS | *_test.cpp | テストに含まれるクラスや関数は除く。 |
| SOURCE_BROWSER | YES | ソースコードも見れるように。 |
| INLINE_SOURCES | YES | 関数やクラスの本体をドキュメントに直接埋め込む。 |
| REFERENCED_BY_RELATION | YES | 参照している機能をリストアップする。 |
| REFERENCES_RELATION | YES | 参照されている機能をリストアップする。 |
| VERBATIM_HEADERS | NO | ヘッダファイルをコピーしないようにする。SOURCE_BROWER有効時にはNOにして無駄をなくす。 |
| HTML_OUTPUT | docs | docsディレクトリにHTML形式のドキュメントを生成する。 |
| GENERATE_LATEX | NO | latexは必要ないのでOFFに。 |
| HAVE_DOT | YES | Graphvizがあることを想定する。UML_LOOK、CALL_GRAPH、CALLER_GRAPHに必要。 |
| UML_LOOK | YES | UMLに似た継承関係図とコラボレーション図を生成する。 |
| TEMPLATE_RELATIONS | YES | 継承関係図やコラボレーション図にテンプレートを含める。 |
| CALL_GRAPH | YES | コールグラフを生成する。ドキュメント生成にとても時間がかかるようになる。 |
| CALLER_GRAPH | YES | コールグラフを生成する。ドキュメント生成にとても時間がかかるようになる。 |
| DOT_MULTI_TARGETS | YES | dotコマンドが速くなる。バージョン1.8.10以上でないと使えないオプション。 |
