PEAR：使用PHPDoc轻松建立你的PEAR文档

　　1. 什么是phpdoc

　　PHPDoc是PEAR下面的一个非常优秀的模块，它的目标是实现类似javadoc的功能，可以为你的代码快速生成具有相互参照,索引等功能的API文档。如果你使用过javadoc生成的文档(如jdk的文档），你会非常清楚，如果你没有用过，那么下面是一个phpdoc生成它自己的文档页面的截图：

　　从图上可以知道，phpdoc生成的文档和JAVADOC很相似，它有多种的索引方式：

　　Packageindex:这是按照模块来索引 Classtree:这是按照你的php类的继承关系，可以生成一个树状的索引 Modulegroups:这是按照模块划分

　　Elementlist:这是你的所有元素（类，方法，过程/函数，变量）的字母顺序的索引

　　2. phpdoc的结构及功能

　　由于phpdoc本身也是符合pear的应用程序，我们首先了解一下它的结构。phpdoc是全部采用OOP的思想来编写的，这也是PEAR所推荐的方式,phpdoc的工作原理：

　　phpdoc扫描指定目录下面的php源代码，扫描其中的关键字，截取需要分析的注释，然后分析注释中的专用的tag，生成xml文件，接着根据已经分析完的类和模块的信息，建立相应的索引，生成xml文件

　　对于生成的xml文件，使用定制的模板输出为html文件。

　　从设计上来说，phpdoc使用了2个超类：PhpdocObject和PhpdocError。这是整个PHPDOC的基本类，这种方式也是PEAR所推荐的，也就是说当你编写你自己的应用框架的时候，最好能够有一个基本的超类，而其他的子类或者是功能类都有一个共同的祖先。在扫描源代码过程中，PHPDOC使用的是类似GREP的形式，并没有象我们通常想的那样，使用正则表达式来实现，根据作者的解释，他曾经尝试过使用正则表达式，但是资源的占用和处理速度都很难令人满意，因此采用了这种非常规的形式，具体的实现有兴趣的读者可以参看源代码。我认为PHPDOC令人满意的另一方面是其分析结果是以XML形式保存的，这样就意味着其他的应用程序很容易可以共享这个数据，同时PHPDCO也提供了相应的接口，你可以实现这个接口，把API文档生成其他的形式，比如PDF，LATEX，WORD等等。目前，PHPDOC的分析结果可以以HTML形式表现，以后可能会有更多的形式。即使是HTML形式，由于使用了模板机制（他使用了PEAR的IT和ITX模块来实现），你可以很方便地定制成你自己需要的风格，

　　3. PHPDoc基础

　　PHPDoc是从你的源代码的注释中生成文档，因此在给你的程序做注释的过程，也就是你编制文档的过程。

　　从这一点上讲，PHPdoc促使你要养成良好的编程习惯，尽量使用规范，清晰文字为你的程序做注释，同时多多少少也避免了事后编制文档和文档的更新不同步的一些问题。

　　编制符合PHPDoc规范的注释是非常重要的，掌握了这一点，基本上就可以利用PHPDoc为你工作了。

　　注释在PHPDoc中分为文档注释和非文档注释

　　3.1 文档注释

　　文档注释实际上是一些特殊形式的多行注释，一般是放在你需要注释的特定的关键字(这些关键字是指将会被phpdoc分析的那些关键字，相关的关键字列表请参看后面第4节的说明）前面。下面是一个文档注释的例子：

　　/**

　　 * Common base class of all phpdoc classes （简述，用在索引列表中）

　　 *

　　 * As a kind of common base class PhpdocObject holds

　　 * configuration values (e.g. error handling) and debugging

　　 * methods (e.g. introspection()). It does not have a constructor,

　　 * so you can always inheritig Phpdoc classes from this

　　 * class without any trouble. （详细的功能描述）

　　 *

　　 * @author　 Ulf Wendel

　　 * @version　$Id: PhpdocObject.php,v 1.3 2001/02/18 15:29:29 uw Exp $

　　 * @package　PHPDoc （文档标记）

　　 */

　　class PhpdocObject {

　　.....

　　}

　　以上的文档注释将会生成如下的文档：

　　PhpdocObject

　　PhpdocObject

　　Common base class of all phpdoc classes

　　private class PhpdocObject

　　Common base class of all phpdoc classes

　　As a kind of common base class PhpdocObject holdsconfiguration values (e.g. error

　　handling) and debuggingmethods (e.g. introspection()). It does not have a

　　constructor,so you can always inheritig Phpdoc classes from thisclass without any trouble.

　　Authors Ulf Wendel

　　Version $Id: PhpdocObject.php,v 1.3 2001/02/18 15:29:29 uw Exp $

　　3.2 非文档性注释

　　如果你的注释没有放在那些phpdoc指定的关键字前面，那么phpdoc认为你所作的这些注释是属于非文档注释，将不会被phpdoc所分析，也不会出现在你产生的api文当中。

　　3.3 如何书写你的文档性注释

　　从3.1 我们可以看到，一个文档性的注释，是由3个部分组成的，分别是：功能简述区，功能详细说明区，文档标记区。

　　首先，第一行是一个注释开始的标志"/**"，然后是回车，从第2行开始就是功能简述区，功能简述区是以缩进的"*"开始的，在简述的正文和这个"*"号之间用空格分隔（注意，在文档中，都是以*开始，并且这些*保持对齐的缩进格式）。功能简述的正文一般是简明扼要地说明这个类，方法或者函数的功能，功能简述的正文在生成的文档中将显示在索引区。

　　在功能简述区后面是一个空的注释行，用来分割简述区和详细说明区。功能详细说明区也是以缩进的'*"来引导的，这部分主要是详细说明你的API的功能，用途，如果可能，也可以有用法举例等等。在这部分，你应该着重阐明你的API函数或者方法的通常的用途，用法，并且指明是否是跨平台的（如果涉及到），对于和平台相关的信息，你要和那些通用的信息区别对待，通常的做法是另起一行，然后写出在某个特定平台上的注意事项或者是特别的信息，这些信息应该足够，以便你的读者能够编写相应的测试信息，比如边界条件，参数范围，断点等等。

　　在功能详细说明区后面，是空白的注释行，然后是文档标记区，你可以在这些书写相关的文档标记（这些文档标记的用法请参考后面的第4节），指明一些技术上的细节信息，最主要的是调用参数类型，返回值极其类型，继承关系，相关方法/函数等等。多个文档标记应该使用相同的缩进，组成一个"标记块"，便于阅读和分析。

　　在文档标记区下面的一行就是注释结束行"*/",注意，在注释结束标记*/后面应该直接跟一个回车，不要另外附加其他的东西，否则可能造成PHPDOC分析出错。

　　以上就是书写一个文档性注释的基本方法，下面我们讨论一下书写文档时的规范和技巧。

　　3.4 文档书写指南

　　在你描述你的代码的用途或者是功能的时候，最好能够遵循大多数人的习惯，通俗地讲就是"你告诉我的信息正是我想要知道的"。为此，这里将介绍一些书写文档注释的技巧和规范，希望能够对你有所帮助：

　　使用 来标志关键字和命名及相关的代码。如果在文档中需要引用一些关键字，变量名，或者是你要给出一些代码的例子，那么你最好使用来将这些关键字，变量名，代码片段和你的文档分隔开，这样，读者阅读的时候，将会知道，这些将是运行的代码，关键字而不是你的描述性的语言。

　　使用简单，明确的语言，避免冗长，复杂，晦涩的长句来描述。尤其是在功能简述，参数说明等索引部分中，尽量使用简单明白的语言揭示主要的信息，把其他的细节放在详细说明部分去阐述。如果你使用英语，建议使用短语而不一定是句子。

　　如果使用英语，建议使用第3人称单数的形式来说明

　　在给方法，函数说明的时候，你需要说明的是这个方法"作了什么"，而不是"怎么做"。因此，建议你的说明是以动词开始，比如"返回记录数"，"删除给定的记录"等等。

　　当你引用的某个对象或者变量是从当前的类中建立的，那么使用 "this" 代替 "the" 来指代那个对象或者是变量

　　避免空话，废话，对于你所要给出的API，在你的API后面要有它的功能描述，是其能够"自成文档"。所谓的空话，废话是指，你的描述不是功能描述，而只是API名称的简单重复和罗列，或者是用另一个API来解释这个API，到头来，你的读者也不知道你所要表达的内容实质。你的描述，应该是那些从你的类名，方法名，或者是函数名看不到的补充的信息，而不是把你的API名称再重复一遍。很多人可能很多人（包括我）不知不觉中就犯了这个错误，下面是一个例子：

　　/**

　　 * 设置用户记录集

　　 *

　　 * @param text　给定的表名

　　 */

　　function set_user_record($table) {

　　你从上面这段注释中能够知道什么？因此，这段注释实际上是废话，因为你从函数名称上是可以看出的，下面是改进后的：

　　/**

　　 * 打开系统用户表并设置为当前用户记录集，此记录集将用于随后相关用户数据更新操作的缺省记录集。如果失败则抛出一个数据库错误。

　　 *

　　 * @param text　要打开的系统用户表的表名。

　　 */

　　function set_user_record($table) {

　　适当地使用链接。为你文档中引用的API名称（包括你的其他类及方法，PHP的函数等）添加适当的链接是很受欢迎的：你可以使用@link标记来添加到相关的API的链接，不过，你没有必要为文档中引用的所有的API都添加连接，这样会很不美观，这里有一个简单的标准：如果用户在这个地方看到某个API