phpdocumentorを利用する

phpでプログラムを作成していながら、ドキュメントを残すぐらいであれば、提携フォーマットでコメントをソースに埋め込んでphpdocumentorを動かしてマニュアルを作ったほうが賢い。
インストールはpearパッケージなので簡単。
# /usr/local/lib/php4/bin/pear install –alldeps phpdocumentor
たとえば、特定のファイルをマニュアル化するのであれば、あらかじめ作成した出力先をdocとすると
phpdoc -f hogehoge.php -t doc/ -o HTML:frames:default
とすればよい。
(ディレクトリ丸ごとならば -d オプションを使う。)
ただ日本語のコメントは文字化けしてしまう。多くのサイトでは該当するテンプレート
/usr/share/pear/data/PhpDocumentor/phpDocumentor/Converters/HTML/frames/templates/default/templates/
にある
blank.tpl
header.tpl
index.tpl
top_frame.tpl
のcharsetを変更すればよいと書いてあるが、作成するプログラムがサイトによって異なることもあるだろうし、もともとインストールされているデフォルトテンプレートをゴリゴリ書き換えるのは気持ち悪い。
phpdocコマンドにはテンプレートで使用するファイルを切り替える-tbというオプションがあるが、どうやらうまく動いていないようなので、いっそのことテンプレートを丸ごとコピーしてそれを指定することにした。
たとえば、Shift-JISでプログラムの文字コードが統一された携帯向けコンテンツのマニュアルを作成する場合、
cd /usr/share/pear/data/PhpDocumentor/phpDocumentor/Converters/HTML/frames/templates
cp -pR default default_sjis
としてdefaultテンプレートをコピー
cd default_sjis/templates/
で移動して、
blank.tpl
header.tpl
index.tpl
top_frame.tpl
のcharsetをShift-JISへ変更する。
phpdoc -f hogehoge.php -t doc/ -o HTML:frames:default_sjis
とすると
/usr/share/pear/data/PhpDocumentor/phpDocumentor/Converters/HTML/frames/templates/default/
ではなく
/usr/share/pear/data/PhpDocumentor/phpDocumentor/Converters/HTML/frames/templates/default_sjis/
以下のものが利用されるようになる。
/usr/share/pear/data/PhpDocumentor/phpDocumentor/Converters/
の中にはいろんなテンプレートがあって、PDFにしたりすることもできるみたいだ。
ドキュメントをオンラインだけでなく、紙でも残す必要がある場合には、これを使えばよさそうだ。
例)phpdoc -f hogehoge.php -t doc/ -o PDF:default:default


(※)
なぜかしら -f オプションはワイルドカードを使えるらしいがマッチする最初のファイルで処理を終了してしまう。カンマ区切りで指定できるので、複数指定する場合にはそれでやるとか・・・(面倒だけど)

カテゴリーPHP

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です