PHPDoc/PHPDocumentor生成API文档

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"

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

第二种方法：
第一步：下载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速度快了很多。