在多人项目时,文档是件重要工作,API文档写起来也相当的繁琐。还好可以用PhpDoc/PhpDocumentor帮我们搞定。
PHPDocumentor(以前叫PhpDoc,1.3版本起改名为PHPDocumentor并支持PHP5)是用PHP写的一个小工具,可以根据代码注释生成API文档。可输出为PDF/HTML/CHM等格式,并且有多种输出模版可选。
PHPDocumentor安装方法
按主流的安装方法,是先安装PEAR,然后在命令提示行里切换到PHP所在目录:
此时PEAR会自动查找PHPDOC安装文件并下载,如果你已经下载了TGZ的安装包,可以直接
指定包位置来安装。
我的机器使用的是XAMPP集成PHP+MYSQL环境,默认是安装了这玩意的,当我用 PEAR uninstall phpdoc把它删除后却安装不上了,提示不能解压缩文件:
于是我直接把phpDoc解压到F:\xamp\php\PhpDocumentor目录下,然后修改该目录里的 phpdoc.bat 这个批处理文件,将16行 “SET phpCli=”改成我的PHP路径:
就可以使用了。
PHPDocumentor注释规则
针对文件的注释:
针对函数的注释示例:
利用phpDocumentor根据注释生成API文档
phpDocumentor支持两种方式使用:WEB页方式和命令提示行方式。我测试时是用的命令提示行方式。
- 切换到phpdoc.bat所在目录(我这里的是 F:\xampp\php\PhpDocumentor>)
- 输入:phpdoc -o HTML:smarty:php -d _s -t _t
参数说明:
参数 -D 后面的值 “_s”是要文件的PHP源文件目录,如果你只想分析单个文件,可以将-D改为-F并指定PHP文件,
参数 -O 表示要输出的模板风格。
参数 -T 表示要输出的目标目录,如果不存在程序会自动创建
注:所以参数位置默认相对于当前目录。 - 按下回车后耐心等待吧,分析的效率略微有些慢。
中文乱码问题
我使用的PHPDoc版本(1.4.3)可以直接处理中文,不需要转码。
需要注意的是:有的输出模板使用的是ISO-8859-1编码,批量把 \PhpDocumentor\phpDocumentor\Converters\HTML 目录的替换为 (改为UTF8编码)即可。