对于一个开发人员，文档总是最感到头疼的事情之一。而且，很可能你对待文档会采取截然不同的2种态度：
当你使用别人的代码库的时候，最希望得到的是它的技术文档，尤其是当时间很紧，而你又不得不硬着头皮去读那些生涩的代码的时候。
当写你自己的程序的时候，最不希望做的事情却是给它编写专门的技术文档，你会以种种理由给自己开脱：我的代码已经足够清楚了，完全不用再为它重新编写文档了……
也许是为了缓解这种矛盾，有很多工具可以帮助你，通过从源代码中抽取相应的注释，可以自动生成相应的api文档。java中的javadoc,perl中的pod2man。相比之下，php以前好像缺乏相应的工具，不过，随着phpdoc的不断完善，这种局面已经大大改观。
在第一篇pear的编码规则中有一条，pear程序中的注释应该能够被phpdoc转变。由此可见，phpdoc在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节的说明）前面。下面是一个文档注释的例子：
首页
