doxygen というドキュメント生成に興味が湧いたので、作成したbaserCMS用プラグインのドキュメント生成やってみました。
パッケージ管理に Macports 使ってるんで、それにないか検索してみたらあったのでそれを利用。
環境
- mac OS X: 10.8.5
- macports: 2.3.3
＠2015/02/15 の port install で入ったバージョン
- doxygen: 1.8.7_0
- graphviz: 2.38.0_0+pangocairo+x11
手順
手順.1
$ sudo port install doxygen graphviz
結構な数の関連ライブラリが併せてインストールされました。
手順.2
完了したら、出力したいプロジェクトのルートに移動して以下。
$ doxygen -g
doxygen 用の設定ファイルが生成されます。
Configuration file `Doxyfile' created.
Now edit the configuration file and enter
doxygen Doxyfile
to generate the documentation for your project
手順.3
生成された設定ファイルの内容をそれなりに編集。
変更してみた内容は以下。
※ 全て変更しなきゃいけないルールはないです。必要に応じて調整すると良いです。
| オプション名 | デフォルト値 | 変更した値 | 内容 |
|---|---|---|---|
| PROJECT_NAME | My Project | OptionalLink | プロジェクト名を設定 |
| OUTPUT_DIRECTORY | doc | ドキュメントを出力するディレクトリを指定 | |
| OUTPUT_LANGUAGE | English | Japanese | 出力言語指定 |
| RECURSIVE | NO | YES | 再帰的なソースディレクトリの解析 |
| FILTER_SOURCE_FILES | NO | YES | ソースコードページを生成する |
| STRIP_CODE_COMMENTS | YES | NO | ソースコードページではソース内のコメントを削除する |
| SOURCE_BROWSER | NO | YES | ソースファイルのリストが生成されます。 |
手順.3-1
以下を設定するとクラス階層が図で出力されました。すごい見やすい。
| オプション名 | デフォルト値 | 変更した値 | 内容 |
|---|---|---|---|
| HAVE_DOT | NO | YES | Graphviz で出力するための DOT ファイルを作る |
| CALL_GRAPH | NO | YES | コールグラフ（呼び出す側）を作成する |
| CALLER_GRAPH | NO | YES | コールグラフ（呼び出される側）を作成する |
手順.3-2
他にも設定すると良いんじゃないかな？という項目
| オプション名 | デフォルト値 | 変更した値 | 内容 |
|---|---|---|---|
| EXTRACT_ALL | NO | YES | 要素は全てドキュメント化する |
| EXTRACT_PRIVATE | NO | YES | private メンバーを全てドキュメントに出力する |
| EXTRACT_STATIC | NO | YES | static メンバーを全てドキュメントに出力する |
手順.4
出力したいプロジェクトのルートに移動し、ドキュメント出力用のコマンドを実行。
$ doxygen
これで doc ディレクトリ内にドキュメントが生成されました。
中の html/index.html をブラウザで開くと確認できます。
▼ 生成したドキュメントのサンプルはこっちの記事に置いてます。
http://www.materializing.net/archives/2015/02/15011711.php
参考記事
追記@2015/02/18
- git clone した baserCMSを使ってそのまま出力してみた
- 684.6MBのドキュメントになった（56,832ファイル）。所要時間は1時間くらい https://twitter.com/arata/status/567712199569715200