纯粹空间 - 韩国欧美酷站教程设计素材美女壁纸下载论坛免费博客

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

类别: PHP教程

对于一个开发人员，文档总是最感到头疼的事情之一。而且，很可能你对待文档会采取截然不同的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节的说明）前面。下面是一个文档注释的例子：

/** * 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 {    .....}

上一篇: 用封装类来合理的设计PHP项目--谈PHP项目中类的封装
下一篇: PEAR:常用模块

-= 资源教程 =-

文章搜索