用phpDocumentor自动生成API文档

作者： Builder.com
2004-11-16 02:26 PM

开发人员和文档就像油和水——他们之间不能很好地溶合。很多开发人员发现编写文档非常枯燥，非常浪费时间。所以就不奇怪为什么有很多公司雇请单独的人员来创建技术文档，而不试图劝服开发人员和程序员自己写文档。
但是如果你是用 PHP 进行开发的话，就有一个叫做
phpDocumentor
的方案可以使用。与 Java 的
javadoc
工具类似，phpDocumentor 通过读取内嵌在 PHP 代码中的标识符和特殊注释自动创建 API 文档。因为大多数开发人员无论如何都有在代码中写注释的惯例，所以使用这个工具对他们带来的负担是最小的。而且phpDocumentor 可以以很多种格式输出文档（包括 HTML、XML 和 PDF），这样更进一步减少了浪费在手工编制文档上的时间。当然对于用户手册和处理流程图之类的复杂文档，你依然还需要技术写手。但是，对于简单的类文档和方法原型，phpDocumentor 是一个非常合适的工具。
在本次课程里，我首先向你展示在编写脚本时可以使用的特殊标识符和语法。然后我还会向你展示使用phpDocumentor 读取代码和自动生成类树和方法/属性信息的基础知识。
完整的解决方案
标榜为“用于 PHP 的完整的文档解决方案”，phpDocumentor 能够读取源代码中的注释，然后使用这些注释创建专业的、格式整洁的 API 文档。它支持很多种输出格式，包括 HTML、PDF、Windows HLP 和 XML。每种输出格式提供了不同的模板和设计。甚至你还可以创建自己的模板——phpDocumentor 使用著名的
Smarty
模板引擎呈现数据。
phpDocumentor 是
通过 PEAR 提供
的，所谓 PEAR 是指 PHP 扩展和应用程序知识库（PHP Extension and Application Repository），可以在
Phpdoc.org
下载这个工具。安装过程很简单，只要将下载的压缩文件解压到你的 PEAR 本地安装并把浏览器指向安装目录中的phpdoc.php脚本即可。你应该可以看到类似图A的画面。

这个表单（form）是phpDocumentor 的基本 Web 界面（另外还有一个命令行界面，但是我们这里只讲 GUI），你将使用这个界面告诉应用程序读取哪些 PHP 类并为它们生成文档。后面我们会详细讲到——首先，我将展示如何使用phpDocumentor 语法标记代码。
考虑
列表A
中简单的函数定义。


  




      


这段代码是一个 PHP 函数定义，包括两个参数和一个返回值。要让phpDocumentor 从这个函数定义生成文档，需要用更多的信息标记它，如
列表B
所示。
当然，它看起来给人的印象很深刻……但是它到底表示什么意思呢？
phpDocumentor 标记的基本元素是所谓的DocBlock（一个多行注释块），它可以出现在任何 PHP 结构、类和函数之前，其基本样式如下：
/**
* text here
*
*/
有了这个DocBlock，phpDocumentor 就允许出现三类项目：一个简短的描述；一个较长的描述；和一系列特殊的标签，每个标签之前有一个 @ 符号，在
列表C
的例子中可以看到。这些标签是可选的；然而，最好还是把它们都包含进来，这样可以使最后的文档更加精确。下面是一些phpDocumentor 支持的相比之下用得更多的标签，其中每个表示：
@access：函数是公有的（public）还是私有的（private）
@author：函数作者的名称和电子邮件地址
@version：函数的版本号
@copyright：函数的版本信息，如果需要
@package：函数隶属的包，如果可用
@param：函数的参数，包括它的类型和描述
@return：函数的返回值，包括它的类型和描述
@var：函数内部的类变量或局部变量的变量类型和描述
@global：函数内部全局变量的变量类型和描述
@see：另外一个相关元素的名字
@todo：还没有完成的项
标签出现在什么地方没有硬规则，但是一个凭经验得来的规则是只使用相关的标签，以避免使最后生成的文档很散乱。例如，对函数和方法使用 @param和 @return 是有意义的，但是对变量定义使用这两个标签就不合适。phpDocumentor 的 Web 站点提供了
更详细的指导原则
。
使用phpDocumentor 生成文档
现在你已经使用phpDocumentor 语法标记了所有的代码，是该使用它的时候了。打开浏览器，进入你开始看到的phpdoc.php页面。这回你要把表单填写完——必须输入目标目录（即文档被保存的位置）的值，（需要被编制文档的）源目录或源文件，以及输出格式或打算使用的“converter”（我通常选择HTML:Smarty:PHP）。在填写完这些信息之后提交表单，phpDocumentor 将为你生成文档。
在出现了几百个状态信息之后，文档就会生成并放在目标目录下了。进入目标目录，然后在浏览器中打开 index 页面，你会看到类似图B的内容。

点击左边框架中的文件名可以查看其内容，如图C所示。

注意你在插入了标签的源代码中提供的所有信息是如何被转换成一个格式整洁的 API 定义的。现在让我们看一下它如何为类和类阶层生成文档。
生成类的文档
前面你已经看到了使用phpDocumentor 为用户定义的函数生成文档的例子。现在，让我们看一下它如何为类生成文档，就像
列表D
中的这个例子。


  




      


类的源代码所需的文档量要比简单的函数所需的文档量要大的多。一般你都会把类级的信息放在类定义之前，并且这些信息包括作者、版本以及外部DocBlock中的版权信息；如果这个类属于更大的一个包的一部分，那么你还可以包含 @package 标签。类变量通常使用 @var标签标记数据类型，用 @access 标签标记其可见性为公有还是私有，而类方法使用 @param、@return 和 @access 标签相应地表示方法参数、返回值和可见性。
在对类的定义运行phpDocumentor 时，你会看到类似图D的一个画面。

这个类的源代码已经被整洁地分割。有一个部分用于类的概述，一个列表列出了公有变量和私有变量，方法和方法原型，以及其它的信息。像这样的文档就能够让其他程序员很容易地快速理解你的类是用来做什么的，是如何工作的——以及如何在不深究实际源代码的情况下使用它。
面向对象编程
如果你是一位 OOP 程序员，那么你不大可能会使用独立运行的类。你更可能会组织一个类阶层，在这个阶层中一些对象作为新的子对象的基础，这些子对象具有新的属性和方法以及继承的属性和方法。phpDocumentor 在为这种类型的类树构建文档时表现很优秀——它提供了对以下两个功能的内建支持，一是识别类间的依赖性，二是在一个类 API 的不同阶层之间创建链接。
要更好地理解这一功能，考虑
列表E
中给出的AddingMachine() 类的扩展，然后看一下生成的 API 的画面（图E和图F）。



请注意，phpDocumentor 聪明地指出了Calculator() 对象是通过“extends”从AddingMachine() 对象得来的一个子对象，并且已经将AddingMachine() 方法和属性导入和链接到了Calculator() 的命名空间中。
链接出去
phpDocumentor 还具有很多标签可以用来把读者指引到更多的参数资料，或者指引到相关的类和函数。其中最简单的是 @see 标签，它告诉读者“see(参阅)”相关的变量、函数或类。
列表F
演示了 @see 标签的用法。
debit() 和credit() 方法将会在最后的链接中相互链接到对方，从而使读者从一个函数跳转到另一个函数更加容易。你可以创建任意多的 @see 链接——phpDocumentor 会自动尝试跟踪到目标变量或目标函数并创建一个到它的链接。


  




      


如果你想要链接到一个 Web 页面或者教程，更加详细地描述你的元素，那么可以使用 @link 标签，phpDocumentor 会自动将其转换成一个超链接。
列表G
展示了如何这个标签的用法。
在phpDocumentor 遇到列表G中的 @link 标签之后，它将创建一个指向 URL 参数的超链接。对于链接到其它地方更详细的文档，以及放置一些说明和提示到以后可以详细解释的类中，这个标签都非常有用。
我希望这篇文章能够为你提供足够的信息，使你开始使用这个自动文档编制系统。但是这只是冰山一角。phpDocumentor 还可以完成很多很多事情，你可以在它的
很精彩的在线教程
中查看其具体用法。我希望你能够使用phpDocumentor 强大的特性来节省一些时间，使你下次能够坐下来编写 PHP 应用程序。
                     ------------------------------------
                             
原文地址