对于一个开发人员，文档总是最感到头疼的事情之一。而且，很可能你对待文档会采取截然不同的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形式，由于使用了模板机制（
相关文章
 我来说两句 |
对此文章发表了评论 |
评论列表 （最新 评论仅限网友观点！）
推荐文章
热门文章
