PHP文档工具-phpDocumentor

PHP 文档工具

—— phpDocumentor

 

写文档是一项乏味却不得不做的工作，而编写 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 可以访问的目录就可以运行了。

 

来源：http://blog.csdn.net/shimizu/archive/2004/08/06/66980.aspx