phpdocumentor php7,phpDocumentor

最近再总结一些PHP的规范, 想起之前在Y!的时候的API描述自动生成工具, 翻到了phpDocumentor, 用起来感觉还是很方便 , 就安装到使用的过程写下来, 与大家分享

phpDocumentor的安装很简单,

如果通过pear自动安装

在命令行下输入  pear install PhpDocumentor

如果是手动安装

则在http://manual.phpdoc.org/下载最新版本的PhpDocumentor(现在是1.4.2)，把内容解压即可.

phpdocumentor的使用也很简单, 分为命令行模式和web模式:

命令行模式

在phpDocumentor所在目录下，输入

php –h

会得到一个详细的参数表，其中几个重要的参数如下：

-f 要进行分析的文件名，多个文件用逗号隔开

-d 要分析的目录，多个目录用逗号分割

-t 生成的文档的存放路径

-o 输出的文档格式，结构为输出格式：转换器名：模板目录。

例如：phpdoc -o HTML:frames:earthli -f test.php -t docs

Web模式

在新的phpdoc中，除了在命令行下生成文档外，还可以在客户端浏览器上操作生成文档，具体方法是先把PhpDocumentor的内容放在 apache目录下使得通过浏览器可以访问到

点击files按钮，选择要处理的php文件或文件夹，还可以通过该指定该界面下的Files to ignore来忽略对某些文件的处理。

然后点击output按钮来选择生成文档的存放路径和格式.

最后点击create，phpdocumentor就会自动开始生成文档了，最下方会显示生成的进度及状态，如果成功，我们就可以通过查看生成的文档了，如果是pdf格式的，名字默认为documentation.pdf。

来看个例子:

代码加上注释:

/**

* @filename baseTags.php

* @touch date Tue 21 Apr 2009 11:49:12 AM CST

* @package phpDocumentor demo

* @author Laruence

* @license http://www.zend.com/license/3_0.txt PHP License 3.0

* @version 1.0.0

* @copyright (c) 2009, Laruence

*/

/**

* this function is a demo to illustrate how phpdocument tags work

*

* $bool = element(true, "laruence");

*

* @deprecated

* @param bool $bool a flag to decide whether the string should be output

* @param string|int $string sometimes it's a string, sometimes it's a int

* @return bool

*/

function element($bool, $string){

if ($bool){

die("flag off");

}

echo "I love $string";

return true;

}

?>

在命令行模式下输入:

phpdoc -o HTML:frames:default -f baseTags.php -t docs

还有一些其他技巧, 比如, 你可以把phpdoc这个脚本放到/usr/bin目录下, 将phpdoc.ini和phpdocumentor目录放到php设置的include path 下, 就可以把phpdoc当成shell命令来很方便的使用了.

还有, 比如一些文件的描述信息, 完全可以map成vim的一个宏命令, 我自己就把相关的信息都map成了F12,

function MyCopy()

call setline(line("."),"/**")

call append(line(".")+1," * @filename ".expand("%"))

call append(line(".")+2," * @touch date ".strftime("%c"))

call append(line(".")+3," * @author Laruence")

call append(line(".")+4," * @license http://www.zend.com/license/3_0.txt PHP License 3.0")

call append(line(".")+5," * @version 1.0.0 ")

call append(line(".")+6,"*/")

endf

map :call MyCopy()5j$a

等等.

最后, 生成的API文档见这里: 例子

如果有兴趣, 还可以看看phpdoc的代码, 也是很有意思,呵呵

ps: 相关的tags的说明见phpDocumentor官方网站的说明 tags说明手册