PHPDocumentor 是一个用PHP写的工具, 对于有规范注释的php程序, 它能够快速生成具有相互参照,索引等功能的API文档.
安装环境:
本机安装的是 EasyPHP-5.3.2i 套件,
1 |
安装目录是 D:\Program Files\EasyPHP-5.3.2i\ |
2 |
php.exe 所在路径是 D:\Program Files\EasyPHP-5.3.2i\php\php.exe |
首先安装 PEAR:
1, 修改 D:\Program Files\EasyPHP-5.3.2i\php\go-pear.bat 内容如下:
1 |
@ECHO OFF |
2 |
set PHP_BIN=%CD%\php.exe |
3 |
"%PHP_BIN%" -d output_buffering=0 -d phar.require_hash=0 PEAR\go-pear.phar |
4 |
pause |
2, 开始->运行->cmd, 执行 go-pear.bat 开始安装 Pear, 一路回车
1 |
Microsoft Windows XP [版本 5.1.2600] |
2 |
(C) 版权所有 1985-2001 Microsoft Corp. |
3 |
4 |
C:\Documents and Settings\kuco>D: |
5 |
6 |
D:\>cd D:\Program Files\EasyPHP-5.3.2i\php |
7 |
8 |
D:\Program Files\EasyPHP-5.3.2i\php>go-pear.bat |
3, 修改 php.ini 中的 include_path
1 |
include_path = ".;${path}\php\includes;${path}\php\PEAR" |
4, EasyPHP 套件中的 php.ini 没有存放在 php.exe 所以目录中,所以要复制一份.
1 |
复制 D:\Program Files\EasyPHP-5.3.2i\apache\php.ini |
2 |
到 D:\Program Files\EasyPHP-5.3.2i\php\ 目录下 |
开始安装 PhpDocumentor:
5, 安装 PhpDocumentor 依赖包 XML_Parser
1 |
D:\Program Files\EasyPHP-5.3.2i\php>pear install XML_Parser |
2 |
downloading XML_Parser-1.3.4.tgz ... |
3 |
Starting to download XML_Parser-1.3.4.tgz (16,040 bytes) |
4 |
......done: 16,040 bytes |
5 |
install ok: |
6, 安装 PhpDocumentor
1 |
D:\Program Files\EasyPHP-5.3.2i\php>pear install PhpDocumentor |
2 |
Did not download optional dependencies: pear/XML_Beautifier, use --alldeps to do |
3 |
wnload automatically |
4 |
pear/PhpDocumentor can optionally use package "pear/XML_Beautifier" (version >= |
5 |
1.1) |
6 |
downloading PhpDocumentor-1.4.3.tgz ... |
7 |
Starting to download PhpDocumentor-1.4.3.tgz (2,423,486 bytes) |
8 |
......done: 2,423,486 bytes |
9 |
install ok: |
使用 PhpDocumentor 生成注释文档
7, 假设我们要给 Smarty 的源码包生成一个注释文档
1 |
Smarty 源码存放目录为: E:\www\IDE\Smarty\libs\ |
2 |
注释文档存放的目录为: E:\www\IDE\doc |
3 |
开始在命令行执行命令: |
4 |
D:\Program Files\EasyPHP-5.3.2i\php>phpdoc.bat -o HTML:Smarty:PHP -d E:\www\IDE\Smarty\libs\ -t E:\www\IDE\doc |
可以通过下面的命令得到更多的帮助说明
1 |
D:\Program Files\EasyPHP-5.3.2i\php>phpdoc -h |
在phpdoc.bat所在目录下，输入
Phpdoc –h
会得到一个phpDocumentor的详细参数列表。
我们从其中选出几个常用的来看看：
〈? 命令解释 ?〉
-f
要进行分析的文件名，多个文件用逗号分割
-d
要分析的目录，多个目录用逗号分割
-t
生成的文档的存放路径
-o
输出的文档格式，结构为输出格式:转换器名:模版目录，例如：HTML:frames:phpedit
我们会用到的就这几个了，其他的命令请大家阅读help的提示信息。
试用phpDocumentor
下面我们就以pear中的phpUnit2为例，演示一下如何使用phpDocumentor来生成文档。
首先，把我们需要的参数确定下来：
〈? 命令参数 ?〉
-d
C:Program FilesEasyPHP5phpPEARPHPUnit2
-t
C:Program FilesEasyPHP5phpphpunit2doc
-o
HTML:frames:phpedit
根据上边的参数，我们组合出下边的命令：
Phpdoc -d “C:\Program Files\EasyPHP5\php\PEAR\PHPUnit2” -t “C:\Program Files\EasyPHP5\php\phpunit2doc” -o “HTML:frames:phpedit”
运行上边的命令后，phpDocumentor开始解析源文件并输出工作信息。
命令运行完成后，我们的文档就已经生成好了。 进入我们指定的目标目录，用浏览器打开index.html就可以看见生成的文档了。 文档界面由frame分成了三个部分，左上是包信息，左下是导航信息，右边则是详细的信息呈现页。
上边的图很清楚地描述出了文档的内容：
索引、函数列表、类列表、文件列表和子包。
点击上边的class(es)链接，我们可以清晰的看见整个包的class tree。
我们点击其中一个class，就进入了class的描述页面。
Class描述页面主要包含以下几方面内容：
l 描述：版权、作者、类层次等
l 类变量
l 类常量
l 方法
l 继承的变量
l 继承的方法：非常有用的一个功能
怎么样，是不是很详细呢？如果要生成chm，可以把前边的-o参数改为”CHM:default: default”，这样phpDocumentor会为你生成好chm项目文件，只要用微软的chm工具进行编译就可以得到可用的chm文件了。
用phpDocumentor为自己的代码生成文档
虽然phpDocumentor可以自动从代码中分析出一些信息，但是，要形成一份详尽的文档还是需要我们在编码中进行配合的。为了让phpDocumentor读懂我们的代码，我们需要注意一些编码规范和在注释中增加一些tag：
〈? Tags ?〉
@author
作者信息
@const
由define定义的常量
@deprecate
不建议使用的API
@global
全局变量
@package
包信息
@param
函数参数
@return
返回值
@see
参考函数
@since
引入时间
@static
静态变量
@var
类成员变量
这里只是简单的列出了常用的一些Tag，大家可以阅读phpDocumentor的文档，里边有非常详细的编码规范。关于phpDocumento就介绍到这里，希望大家都能好好利用这个工具来规范自己的文档。
PS：phpDocumentor也有Web界面的，你可以访问http://phpdoc.org获取Web版本。Web版本的安装很简单，直接放到web可以访问的目录就可以运行了。
〈? 环境要求 ?〉
