phpDocumentorを導入して,Ext JSのAPIドキュメントっぽく出力

phpDocumentorのインストール

phpDocumentorは,PHPのコメントを解析して,自動でドキュメントを出力してくれます.

とりあえずpearでインストール

% sudo pear install phpdocumentor

するするっと.

インストールとか使い方は,このあたりを参考に

基本的な説明が一通り.

同じく基本の解説系.文字化け対策等も色々ありますが,生成されたHTMLに含まれるcharset=iso-8859-1をざっくりとcharset=UTF-8とかに置換するだけでOKっぽい.

公式ドキュメントを見て使いそうなタグの種類を把握するのが一番手っ取り早い感じ.

とりあえず出してみる

なにはともあれ,さっくりと出力してみます.

% sudo phpdoc -d [プロジェクトディレクトリ] -t [出力先ディレクトリ] -o HTML:Smarty:PHP

PHP公式ドキュメント風味の標準テーマを使ってみます.

でた! けどダサい!!

なんだかとっても微妙な感じ.見慣れてる色の安定感はあるんですけどね.


PHP公式っぽい


Ext JSの公式ドキュメントっぽいのがカッコいい

ここで,Ext JSのAPIドキュメントっぽく出力できるテーマが配布されているので導入してみました.(Ext JSの現在のドキュメントは,これまたちょっと新しくなっているようなので,現時点の見た目は少し違います)

% sudo phpdoc -d [プロジェクトディレクトリ] -t [出力先ディレクトリ] -o HTML:frames/Extjs:default

AjaxばりばりのリッチUIなドキュメント

タブとかツリーとか,見違えるようなリッチさのドキュメントが生成されました.


かっこいい


置き場所の注意

環境依存だとは思いますが,ダウンロードしたテーマファイルは,以下のように振り分けてコピーします.

I'm using ubuntu 10.04 the direcotries are

for the HTMLframesExtjsConverter.inc /usr/share/php/PhpDocumentor/phpDocumentor/Converters/HTML/frames/Extjs

for the normal Extjs dir use this dir /usr/share/php/data/PhpDocumentor/phpDocumentor/Converters/HTML/frames

(参照先: 配布元エントリーのコメント欄)

このあたりのパスがうまく通ってないと,実行時に様々なエラーが出て出力されません.

コメント命

Ext JSっぽい出力が,なかなか良い感じなので,しばらく使ってみようと思います.

phpdocを意識してコメントをしっかり書くと,冗長になってしまいがちな気もしますが,イザというときにドキュメントを吐けるメリットのほうが大きそう.コメントがんばります.