Doxygen
プログラマにとってはドキュメントって避けたい仕事ですよね。そんな面倒なドキュメント作りを自動化してくれるツールで Doxygen というものがあります。他にも色々あるみたいだけど、割と古くからし、有名なプロジェクトでも使用されているのでいいんじゃないかと思います。なんか日本人的な選択かな・・・。
実際のところ、会社では PHP なので PhpDocumentor がいいのかなって思っていたのですが、一生 PHP やる訳でもないので、多言語対応なツールがあったらいいなって探していました。そこで出会ったのが Doxygen です。主に C とか Java なんだろうけど、PHP、Python、Fortran、さらには MS 系の言語にも対応しているそうです。こりゃいいわ。
んで、会社事情もあり Cake なのですが、v1.2 をダウンロードして Doxygen で処理してみたら behavior の i18n だかのファイルで無限ループに吸い込まれました。どうやら下のほうで
if () { ... }
で囲まれたクラス定義があり、それを消したら進んでくれました。なんだかなぁ。他のバージョンなら大丈夫かも。会社の手を加えた Cake はいけた。
しかし残念なことに Cake の API ブックは ApiGenerator という Cake のプラグインで作られているらしい。
“This Api was created using the new Api Generator plugin for CakePHP. This plugin enables us to easily build api docs based on php5 reflection and some regex magic.”
CakePHP: the rapid development php framework: Api : Pages
バージョン 1.1 は Doxygen だったようだけど、なんで変えちゃったんだろ。あんまマッチしなかったのかな。Web で見るには ApiGenerator もいいけど、PDF とか出来るのかな。Doxygen はできる、らしい。まだやってない。
Doxygen のいいところで、クラスの相関や関数の呼び出し状況を図にしてくれる機能があります。まぁ、他のツールでもできるんだろうけど。んで、その作図機能を提供しているのが Graphviz ってやつ。こっちの方が気になってると言ってもいい。
Graphviz ってのも割と古くからあるツールっぽいです。テキストで dot という言語を書くと、ネットワーク図とかデータ相関図とかを生成することができます。面白い。暇なときに日本語のチュートリアルをやったりしてます。
Graphviz チュートリアル
ネタが古いなぁ・・・。
ちょっと考えているのが、dot で仕様を書いて、Cake のテンプレートを吐き出し、出来上がったら Doxygen でドキュメント生成。Subversion で管理しておけば、テンプレートの差分を吸収していけるから、仕様変更も対応しやすい、なんてね。
まー、結局はコメントを入れるのはプログラマだから、ドキュメントを作っていることに変わりはないんだよねー。コツコツやるか、最後にまとめてやるか。夏休みの宿題と同じだね。