PHP文档工具
2024-05-04 22:58:09
供稿：网友
写文档是一项乏味却不得不做的工作，而编写api级的文档更是意味着大量的重复劳动和难以保持的一致性。这里我们要推荐给大家的，是支持php5语法分析的文档工具——phpdocumentor。
使用phpdocumentor不仅可以自动从代码中提取出函数和方法定义，还可以自动处理各个class之间的关系，并据此生成class tree。你还可以选择将文档生成html、chm或者pdf。有了phpdocumentor，文档工作变得轻松了很多。
安装phpdocumentor
在pear下安装phpdocumentor是一件极其简单的事情，只需要在cmd窗口中cd 到php安装目录下，然后输入
pear install phpdocumentor
pear就会自己下载并完成phpdocumentor的安装。
在phpdocumentor成功安装后，php安装目录下会多出来一个phpdoc.bat。这个文件就是我们用来生成文档的批处理文件了。
<? 相关知识 ?>
phpdocumentor是phpdoc的升级版本，是专门为支持php5语法而重写的文档工具，当你的php版本为5时，运行phpdoc.bat，它会自动去调用phpdocumentor。所以文章中的提到的phpdoc和phpdocumentor实际上是相同的。
在phpdoc.bat所在目录下，输入
phpdoc –h
会得到一个phpdocumentor的详细参数列表。
我们从其中选出几个常用的来看看：
<? 命令解释 ?>
-f
要进行分析的文件名，多个文件用逗号分割
-d
要分析的目录，多个目录用逗号分割
-t
生成的文档的存放路径
-o
输出的文档格式，结构为输出格式:转换器名:模版目录，例如：html:frames:phpedit
我们会用到的就这几个了，其他的命令请大家阅读help的提示信息。
试用phpdocumentor
下面我们就以pear中的phpunit2为例，演示一下如何使用phpdocumentor来生成文档。
首先，把我们需要的参数确定下来：
<? 命令参数 ?>
-d
c:/program files/easyphp5/php/pear/phpunit2
-t
c:/program files/easyphp5/php/phpunit2doc
-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可以访问的目录就可以运行了。
<? 环境要求 ?>
php：5.0.0
os: 平台独立，本文演示os为windows
