PhpDocumetorでPhpDoc事始め

PhpDocumentorのインストール

pearコマンドでPhpDocumentorをインストールします。

# pear install phpDocumentor
Starting to download PhpDocumentor-1.2.3.tgz (2,656,621 bytes)
..........................................................................
..........................................................................
..........................................................................
..........................................................................
........................................done: 2,656,621 bytes
install ok: PhpDocumentor 1.2.3

私の環境では、/usr/local/lib/php/PhpDocumentor 以下にソースライブラリ群が、/usr/local/bin 以下に phpdoc プログラム(もちろんPHPで書かれています)がインストールされました。

PhpDocumentorの使用方法

$ phpdoc -d "ソースのディレクトリパス" -t "出力先のディレクトリパス"

これだけで簡単に -t に指定したディレクトリにドキュメントが生成されます。

PhpDocumentorの日本語コメントへの最適化

PhpDocumentorは標準で日本語コメントもサポートしますが、出力するHTMLファイルのcharsetが「iso-8859-1」のため、正しくブラウザで表示されません。
私の環境では、標準で自動的に「euc-jp」文字コードで生成されますので、テンプレートを一式「euc-jp」に置換します。

$ cd /usr/local/lib/php/PhpDocumentor
$ find ./ -exec grep -l -I -E "charset=" {} \; > /tmp/phpDocumentor.tpl.list
$ perl -p -e "s/\.\//perl -p -i -e \"s\/charset=iso-8859-1\/charset=euc-jp\/g\" \.\//g" /tmp/phpDocumentor.tpl.list > /tmp/phpDocumentor.tpl.list.sh

このシェルスクリプトを実行できるように編集し、実行パーミッションを与えます。

$ vi /tmp/phpDocumentor.tpl.list.sh
Line1: #!/bin/sh
Line2: cd /usr/local/lib/php/PhpDocumentor

$ chmod +x /tmp/phpDocumentor.tpl.list.sh

あとは、rootで /tmp/phpDocumentor.tpl.list.sh を実行します。

# /tmp/phpDocumentor.tpl.list.sh