doxygen 使ってbaserCMSプラグインのドキュメントを生成してみた

doxygen というドキュメント生成に興味が湧いたので、作成した baserCMS用プラグインのドキュメントが生成できないか試してみました。
パッケージ管理に Macports 使ってるんで、それにないか検索してみたらあったのでそれを利用してみました。

■ Doxygen: http://www.doxygen.jp/

環境

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

結構な数の関連ライブラリが併せてインストールされます。
※ 途中、コンソール画面が数分止まるような場面もあって心配しちゃいました。
　 → 直前に macports のバージョンアップしたのでその影響かな？

手順.2

完了したら、出力したいプロジェクトのルートに移動して以下。

$ doxygen -g

Configuration file `Doxyfile' created.
Now edit the configuration file and enter
doxygen Doxyfile
to generate the documentation for your project

doxygen 用の設定ファイルが生成されます。

手順.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

手順.3-1

以下を設定するとクラス階層が図で出力されました。すごい見やすい。

■ Graphviz で出力するための DOT ファイルを作る
HAVE_DOT = NO
　→ YES
■ コールグラフ（呼び出す側）を作成する
CALL_GRAPH = NO
　→ YES
■ コールグラフ（呼び出される側）を作成する
CALLER_GRAPH = NO
　→ YES

手順.3-2

他にも設定すると良いんじゃないかな？という項目
■ 要素は全てドキュメント化する
EXTRACT_ALL = NO
　→ YES
■ private メンバーを全てドキュメントに出力する
EXTRACT_PRIVATE = NO
　→ YES
■ static メンバーを全てドキュメントに出力する
EXTRACT_STATIC = NO
　→ YES

手順.4

出力したいプロジェクトのルートに移動し、ドキュメント出力用のコマンドを実行。

$ doxygen

これで doc ディレクトリ内にドキュメントが生成されました。
中の html/index.html をブラウザで開くと確認できます。

。。。というワケで、OptionalLink を使って出力してみたドキュメント置いときマス。
▼ doc_optionallink.zip
・DLして解凍して、中の /html/index.html をブラウザで開くと見ることができますよ。

参考記事

あとがき

こういうドキュメントを一緒に添えておくと、プラグインをフォークしてごにょごにょする際にも役立ちそう。。。かな。
イベント処理を一覧で閲覧できるので、この辺もプラグインの動作概要を把握するのに良さそうです。

baserCMSのプラグインを作ったときは、このドキュメントも出力して github の wiki に置いとくようにしようかな。

doxygen 使ってbaserCMSプラグインのドキュメントを生成してみた｜Materializing [マテリアライジング]