PHPDoc/PHPDocumentor生成API文档

时间:2022-04-06 07:18:02

PHPDocumentor是一个用PHP写的强大的文档自动生成工具,对于有规范注释的php程序,能够快速生成具有结构清晰、相互参照、索引等功能的API文档。旧版本是PHPDoc,PHPDoc是PEAR下面的一个非常优秀的模块,类似于javadoc。从1.3.0开始,更名为phpDocumentor,新版本新加了对php5语法的支持,同时,可以通过在客户端浏览器上操作生成文档,文档可以转换为PDF、HTML、CHM等格式的文档,这样非常有利于代码的升级、维护、移交等。

前提:安装的前提是已经安装了php环境,我安装的是xampp集成开发环境。

1.PHPDoc的结构及功能
PHPDoc是全部采用OOP的思想来编写的,这也是PEAR所推荐的方式,PHPDoc的工作原理:PHPDoc扫描指定目录下面的php源代码,扫描其中的关键字,截取需要分析的注释,然后分析注释中的专用的tag,生成xml文件,接着根据已经分析完的类和模块的信息,建立相应的索引,生成xml文件对于生成的xml文件,使用定制的模板输出为html文件。从设计上来说,PHPDoc使用了2个超类:PhpdocObject和PhpdocError。这是整个PHPDoc的基本类,这种方式也是PEAR所推荐的。当你编写应用框架时,最好能够有一个基本的超类,而其他的子类或者是功能类都有一个共同的祖先。在扫描源代码过程中,PHPDoc使用的是类似GREP的形式。PHPDoc令人满意的另一方面是其分析结果是以XML形式保存的,这就意味着其他应用程序可以共享这个数据,同时PHPDoc也提供了相应的接口,你可以实现这个接口,把API文档生成其他的形式,比如PDF,LATEX,WORD等。目前,PHPDoc的分析结果可以以HTML形式表现,由于使用了模板机制,可以很方便地定制风格。

2.安装PHPDoc
安装方式有两种,一是下载源码安装,另一种是通过pear安装。

第一种方法:
第一步:安装pear
使用dos窗口进入php安装目录,有个文件叫go-pear.bat,如果没有,建议到网上下载go-pear.phar,然后在dos窗口下运行 go-pear.phar, 从而安装pear。

php go-pear.phar 

第二步:安装phpdoc

Pear install phpDocumentor 

在phpDocumentor成功安装后,php安装目录下会多出来一个phpdoc.bat。这个文件就是我们用来生成文档的批处理文件。
在phpdoc.bat所在目录下,输入

Phpdoc –h 

会得到一个phpDocumentor的详细参数列表。先看看最重要的几个吧。

-d 
这个目录代表着需要生成文档的原始php文件目录(注意是目录)
-t
这个目录代表着生成的文档存放目录
-o
这个参数代表着生成的文档格式,例如html格式,参数就是
HTML:frames:phpedit

第三步:生成文档
生成文档的命令就是:

phpdoc -d "D:\phpdoc\1" -t "D:\phpdoc\1"  -o "HTML:frames:phpedit"

PHPDoc/PHPDocumentor生成API文档

可以看到,解析完成后,在目标目录下生成很多html文件,打开index.html文件,就是我们需要的文档,如下图所示。

PHPDoc/PHPDocumentor生成API文档

第二种方法:
第一步:下载PHPDoc压缩文件(phpdoc.zip),地址如下:
http://star7th-wordpress.stor.sinaapp.com/uploads/2013/04/phpdoc.zip

第二步:解压到某一个目录
打开phpdoc.bat,编辑第16行:

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

配置phpCli 为自己php.exe文件的路径即可。

第二步:dos窗口,进入文件的解压目录,然后执行解析文档命令即可。

phpdoc -d "D:\phpdoc\1" -t "D:\phpdoc\1"  -o "HTML:frames:phpedit"

以上是安装phpDocumentor1版本,目前已经更新到phpDocumentor2版本了,version2的安装也很简单。

第一步:安装pear(同上)
此处给出下载地址:http://pear.php.net/go-pear.phar
将 go-pear.phar 放到 PHP 目录下执行安装命令:

php go-pear.phar

下面会执行输入 system

然后一路回车安装完毕。

第二步:接下来安装类关系绘图用到的工具

pear install image_graphviz
下载 http://www.graphviz.org/Download_windows.php graphviz-2.38.msi
安装后,注意环境变量 path 添加上该 bin 的路径,重启电脑,否则无法生效

第三步:安装 phpDocumentor

pear channel-discover pear.phpdoc.org 
pear install phpdoc/phpDocumentor

稍等一会,安装步骤完成!
注意:两个软件安装后的目录都在PHP 下的 pear 下面:

php/pear/PhpDocumentor
php/pear/Image

显然:version2 比version1速度快了很多。