对于一个开发人员，文档总是最感到头疼的事情之一。而且，很可能你对待文档会采取截然不同的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模块来实现），你可以很方便地定制成你自己需要的风格，

[1] [2] [3] [4] [5] [6] [7] [8] [9] [10]  ... 下一页  >> 

在google里搜索更多使用PHPDoc轻松建立你的PEAR文档

	Web www.51ec.org