doxygen というドキュメント生成に興味が湧いたので、作成した baserCMS用プラグインのドキュメントが生成できないか試してみました。
パッケージ管理に Macports 使ってるんで、それにないか検索してみたらあったのでそれを利用してみました。
■ Doxygen: http://www.doxygen.jp/
環境
- mac OS X: 10.8.5
- macports: 2.3.3
- 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 をブラウザで開くと見ることができますよ。
参考記事
- Doxygen
- MacPortsの基本的な使い方とコマンド : アシアルブログ
- ソースコードを読むのに Doxygen + Graphviz が便利な件 | CUBE SUGAR STORAGE
- コードリーディングのお供には Doxygen & Graphviz が良いかもしれない | きのこる庭
- PHPソースからドキュメントを生成するツール - Shin x blog
- doxygenを使ってPHPのドキュメント自動生成
- Erica女史みたいにDocumentを作る方法 - haoyayoi Dev Style - iPhoneアプリ開発グループ
あとがき
こういうドキュメントを一緒に添えておくと、プラグインをフォークしてごにょごにょする際にも役立ちそう。。。かな。
イベント処理を一覧で閲覧できるので、この辺もプラグインの動作概要を把握するのに良さそうです。
baserCMSのプラグインを作ったときは、このドキュメントも出力して github の wiki に置いとくようにしようかな。