Phpdocumentator は、PearAPIドキュメント風味のドキュメントを生成してくれるツール
コレがあるとソースコード読むのが楽になるはず。
windowsのインストール先
go-pear.bat や pear.bat と同じディレクトリに設置されたよ、
takuya@letsnote:~$ ls -l /home/Public/apps/php | grep bat -rwxr-xr-x 1 takuya None 90 1月 6 17:38 go-pear.bat -rwxr-xr-x 1 takuya None 4742 3月 24 18:07 pear.bat -rwxr-xr-x 1 takuya None 4750 3月 24 18:07 peardev.bat -rwxr-xr-x 1 takuya None 4679 3月 24 18:07 pecl.bat -rwxr-xr-x 1 takuya None 192 4月 6 02:48 php_beautifier.bat -rwxr-xr-x 1 takuya None 5003 6月 21 13:42 phpdoc.bat
サンプルソースコードをドキュメントに起こす
ではドキュメントに変換してみる
サンプルソースコード
./src/test.php <?php class MyTest { public function __construct(){ $this->a = 1; } public function getA(){ return $this->a; } }
変換出力コマンド を実行
phpdoc -t ./src -d ./output
変換実行してみました
takuya@letsnote:~$ phpdoc -t ./phplib -o test PHP Version 5.2.17 phpDocumentor version 1.4.3 Parsing configuration file phpDocumentor.ini... (found in C:\Users\takuya\apps\php\data/PhpDocumentor/)... done Maximum memory usage set at 512M after considering php.ini... using tokenizer Parser
オプションについて
- -d
- 出力したいPHPソースのディレクトリ
- -t
- ドキュメントの出力先 出力ターゲット
- -o
- 出力テンプレートを選ぶのです
- -s
- --sourcecode オプションをつけるとハイライトされるそうだが,使い方がよく分らない
細かいオプションなどはphpdoc -h で参照
phpdocumentor の基本スタイル
コマンドはこれだけ覚えておけばいい。
phpdoc -pp -s -t ./doctest -d ./phplib
PHP基本スタイルのドキュメントスタイル
phpdoc -pp -s -t ./doctest -d ./phplib -o HTML:Smarty:PHP
- t -d は順番変えてもイイ
phpdoc -pp -s -d ./addition -t ./addtion_doc -o HTML:Smarty:PHP
phpdocumentor で出力されるコメント形式
関数(メソッド)のコメントの書き方
最初にメソッドの解説を書くとドキュメントに起こせる
- @access
- ドキュメントに表示するかしないか?の違いっぽい。(public:は表示する; private:は表示されない) 公式ドキュメントより
- @param
- 引数の型やその解説を書く
- @return
- 返却値の型とその解説を書く
他はJavaDoc形式とあまり変わらない。 @param は変数の型を書くことが大事。かもね
/** * (ここにメソッドの解説を書く) * * * @access pulibc * @param 型 $hoge (ここに引数の解説) * @return 型 (ここに返却値の解説) */ public function Foooo(){}