バイト先のWebアプリケーション用ソースコードの量が増えてきたので、
そろそろドキュメント生成ツールでも使おうということで、そのメモ。

バイト先では、PHP & symfonyフレームワークで書いてるんで、
ドキュメント生成ツールにはPhpDocumentor1を使います。

インストールはPEARを使えば楽勝。

 $ pear install PhpDocumentor

で、ドキュンメントの生成にはphpdocコマンドを使います。

 $ phpdoc -d apps,lib -t doc/phpdoc

これで、appsとlibディレクトリ以下すべてのphpファイルをHTMLドキュメント化して、
doc/phpdoc以下に吐き出してくれます。

ただ、デフォルトで生成するHTMLには、charset=iso-8859-1が指定されているため、
日本語コメントは文字化けしてしまいます。

対処法としては、HTML内にcharset指定のないHTMLドキュメントを生成するのが楽です2。

 $ phpdoc -d apps,lib -t doc/phpdoc -o HTML:Smarty:PHP

この場合、デフォルトで生成したHTMLとはレイアウトが変わってしまいます。
デフォルトレイアウトが好きな方は、下記サイトを参考にテンプレートを書き換えてください。
http://je-pu-pu.jp/blog/archives/2006/04/phpdocumentor.html

参考文献

  1. 現バージョンは1.4.2です [↩]
  2. とはいえ、webサーバのDefaultCharsetが間違っていたり、ブラウザの文字コード自動判定が失敗した場合は、文字化けが起きるので注意 [↩]