それマグで!

知識はカップより、マグでゆっくり頂きます。 takuya_1stのブログ

習慣に早くから配慮した者は、 おそらく人生の実りも大きい。

PHPのソースコードからドキュメント作成できるようになる!

Phpdocumentator は、PearAPIドキュメント風味のドキュメントを生成してくれるツール
コレがあるとソースコード読むのが楽になるはず。

phpdocumentator のインストール

pear install --alldeps phpdocumentor

phpのインストールパスに、コマンドがインストールされる

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(){}