PHP_DocBlockGenerator使える！
つい先日1.0.0RC1がリリースされたPHP_DocBlockGeneratorを使ってみました。
PEARのページのDescriptionを見るだけで、かなり期待できそうです。以下、PHP5.2.3 on CentOS4.5で確認しています。
Creates the file Page block and the DocBlocks for includes, global variables, functions, parameters, classes, constants, properties and methods.
Accepts parameters to set the category name, the package name, the author's name and email, the license, the package link, etc...
まずはインストール。
# pear install -a php_docblockgenerator
以上。
続いて動作確認ですが、[PEARDIR]/binにインストールされたdocblockgenコマンド（単なるshスクリプト）で、
#!"/usr/local/lib/php5/bin/php" <?php /** * DocBlock Generator Shell script ：
とダブルクオーテーションで括られているため、
$ docblockgen --help -bash: /usr/local/lib/php5/bin/docblockgen: "/usr/local/lib/php5/bin/php": bad interpreter: No such file or directory $
となってしまいます。とりあえず、ダブルクオーテーションを外して再度実行。
$ docblockgen --help Usage: docblockgen [options] [infile] [,outfile] docblockgen -A [infile] [,outfile] Options: -a --author <name> The author's name, e.g. "John Foo". -c --category <name> The category name, e.g. PHP. See http://pear.php.net/packages.php. -e --email <name@example.com> The author's email address. -i --infile <name> The input PHP file to process. Default: STDIN. -l --license <apache20|bsd|lgpl21|mit|php301|*> The license. Default: bsd. -o --outfile <name> The output file. Default: infile or STDOUT if infile is STDIN. -p --package <name> The package name. Default: the first 2 words of the class name. -u --link <http://...> The package link. Default: http://pear.php.net/package/name. -v --version <cvs|svn|*> The file version. Default: CVS keyword. -y --year <yyyy> The copyright year. Default: the current year. -A --align Aligns existing DocBlock tags. Other options are ignored. -h --help This help. Parameters: [infile] [,outfile] The input and output files. See the -i and -o options. Note: Option values requiring space separated words, for example the author's
オプションでほとんど指定できそうです。ということで、以下のようなサンプル（test.php）
<?php class ClassA { private $private_prop; protected $protected_prop; const CLASS_CONST = 'class const'; private static $private_static_prop; public function __construct() { } private function privateMethod($param1, &$param2, $param3 = 123) { return array(); } protected function protectedMethod() { return 1.0; } } function functionA() { return new stdClass(); } function functionB() { if (isset($a)) { return null; } return "abc"; }
を作って、早速実行。
$ docblockgen \ > --author="Hideyuki Shimooka" \ > --category="Dummy" \ > --email=shimooka@doyouphp.jp \ > --infile=test.php \ > --license=php301 \ > --outfile=test_commented.php \ > --package="Dummy_Package" \ > --link="http://www.example.com/" \ > --version=0.0.1 \ > --year=2007
作成されたtest_commented.phpは以下のようになります。
<?php /** * Short description for file * * Long description (if any) ... * * PHP version 5 * * LICENSE: This source file is subject to version 3.01 of the PHP license * that is available through the world-wide-web at the following URI: * http://www.php.net/license/3_01.txt. If you did not receive a copy * the PHP License and are unable to obtain it through the web, * send a note to license@php.net so we can mail you a copy immediately. * * @category Dummy * @package Dummy_Package * @author Hideyuki Shimooka <shimooka@doyouphp.jp> * @copyright 2007 Hideyuki Shimooka * @license http://www.php.net/license/3_01.txt The PHP License, version 3.01 * @version 0.0.1 * @link http://www.example.com/ * @see References to other sections (if any)... */ /** * Short description for class * * Long description (if any) ... * * @category Dummy * @package Dummy_Package * @author Hideyuki Shimooka <shimooka@doyouphp.jp> * @copyright 2007 Hideyuki Shimooka * @license http://www.php.net/license/3_01.txt The PHP License, version 3.01 * @version 0.0.1 * @link http://www.example.com/ * @see References to other sections (if any)... */ class ClassA { /** * Description for private * @var unknown * @access private */ private $private_prop; /** * Description for protected * @var unknown * @access protected */ protected $protected_prop; /** * Description for const */ const CLASS_CONST = 'class const'; /** * Description for private * @var unknown * @access private * @static */ private static $private_static_prop; /** * Short description for public * * Long description (if any) ... * * @return void * @access public */ public function __construct() { } /** * Short description for private * * Long description (if any) ... * * @param unknown $param1 Parameter description (if any) ... * @param unknown &$param2 Parameter description (if any) ... * @param integer $param3 Parameter description (if any) ... * @return array Return description (if any) ... * @access private */ private function privateMethod($param1, &$param2, $param3 = 123) { return array(); } /** * Short description for protected * * Long description (if any) ... * * @return float Return description (if any) ... * @access protected */ protected function protectedMethod() { return 1.0; } } /** * Short description for function * * Long description (if any) ... * * @return object Return description (if any) ... */ function functionA() { return new stdClass(); } /** * Short description for function * * Long description (if any) ... * * @return string Return description (if any) ... */ function functionB() { if (isset($a)) { return null; } return "abc"; }
うーん。これはすごい。。。というか、もうこの結果を見るだけでいろいろ妄想が（当然いい意味で）(^^;
PEAR::PHP_DocBlockGeneratorのソースを斜め読みした限り、そんなに小難しいことはしてなさそう（やたら「or」を使ってるのが気になる程度）なので、独自改修なり拡張なりするといろいろ使えそうです。
