PhpDocumentor初体验(安装、使用、效果截图)

 

在多人项目时，文档是件重要工作，API文档写起来也相当的繁琐。还好可以用PhpDoc/PhpDocumentor帮我们搞定。
PHPDocumentor（以前叫PhpDoc，1.3版本起改名为PHPDocumentor并支持PHP5）是用PHP写的一个小工具，可以根据代码注释生成API文档。可输出为PDF/HTML/CHM等格式，并且有多种输出模版可选。

PHPDocumentor安装方法

按主流的安装方法，是先安装PEAR，然后在命令提示行里切换到PHP所在目录：

pear inatall phpdoc

此时PEAR会自动查找PHPDOC安装文件并下载，如果你已经下载了TGZ的安装包，可以直接

pear install PhpDocumentor-1.4.3.tgz

指定包位置来安装。

我的机器使用的是XAMPP集成PHP+MYSQL环境，默认是安装了这玩意的，当我用 PEAR uninstall phpdoc把它删除后却安装不上了，提示不能解压缩文件：

F:\xampp\php>pear install PhpDocumentor-1.4.3.tgz
ERROR: unable to unpack PhpDocumentor-1.4.3.tgz

于是我直接把phpDoc解压到F:\xamp\php\PhpDocumentor目录下，然后修改该目录里的 phpdoc.bat 这个批处理文件，将16行 “SET phpCli=”改成我的PHP路径：

  SET phpCli=F:\xampp\php\php.exe

就可以使用了。

PHPDocumentor注释规则

针对文件的注释：

/**
 * 权限判断类，处理权限相关操作
 * @version 1.0
 * @copyright [版权所有者]
 * @author JetKing
 * @var $groupTab array 这是group表的缓存(对变量的注释这样貌似是不对的，还在摸索中)
 */

针对函数的注释示例：

	/**
	 * 检测访问控制权限
	 * @param bool $autoKill [可选]无权限时,是否自动终止程序执行.默认true
	 * @param array $groupInfo [可选]用户分组信息.默认尝试读取当前用户session中的groupInfo值
	 * @param array $uri [可选]含2个元素的数组,$uri[1]=控制器名,$uri[2]=方法名.默认为当前控制器和方法
	 * @author JetKing 
	 * @return bool 是否有操作权限
	 * @todo 该检测使用的用户session，可改为服务器端更改权限后更新时间戳与session时间戳对比实现实时权限
	 */

利用phpDocumentor根据注释生成API文档

phpDocumentor支持两种方式使用：WEB页方式和命令提示行方式。我测试时是用的命令提示行方式。

1. 切换到phpdoc.bat所在目录（我这里的是 F:\xampp\php\PhpDocumentor>）
2. 输入：phpdoc -o HTML:smarty:php -d _s -t _t
   参数说明：
   参数 -D 后面的值 “_s”是要文件的PHP源文件目录，如果你只想分析单个文件，可以将-D改为-F并指定PHP文件，
   参数 -O 表示要输出的模板风格。
   参数 -T 表示要输出的目标目录，如果不存在程序会自动创建
   注：所以参数位置默认相对于当前目录。
3. 按下回车后耐心等待吧，分析的效率略微有些慢。

中文乱码问题

我使用的PHPDoc版本(1.4.3)可以直接处理中文，不需要转码。
需要注意的是：有的输出模板使用的是ISO-8859-1编码，批量把 \PhpDocumentor\phpDocumentor\Converters\HTML 目录的替换为 （改为UTF8编码）即可。