php Documentor 1.2.2 使用说明规范

来源:www.phpres.com 作者：Angelover 出处：www.phpres.com 2007-5-1 10:50:06 进入讨论组

关键词： php Documentor 1.2.2 使用说明规范

php Documentor 1.2.2 使用说明规范
2004-11-2 整理初稿

一、什么是phpDocumentor

phpDocumentor是PEAR下面的一个非常优秀的模块，它的目标是实现类似javadoc的功能，可以为你的代码快速生成具有相互参照,索引等功能的API文档。

phpDocumentor生成的文档和JAVADOC很相似，它有多种的索引方式：
Packageindex:这是按照模块来索引
Classtree:这是按照你的php类的继承关系，可以生成一个树状的索引
Modulegroups:这是按照模块划分
Elementlist:这是你的所有元素（类，方法，过程/函数，变量）的字母顺序的索引

phpDocumentor可以以不同的格式(包括HTML，XML和PDF)输出文档，由此进一步地减少了人工文档化的时间。当然，对于更为专业化的文档，比如用户手册或者程序流框图，你仍然需要懂得技术的人来编写。但是对于比较简单的文档和方法原型，phpDocumentor已经是一款胜任的工具。

二、 phpDocumentor的结构及功能

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

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

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

作为“PHP的完整文档化方案”，phpDocumentor以读取源代码的注解并使用这些注解建立一个专业化的简洁的API文档。这一工具支持不同的输出格式：HTML，PDF，Windows HLP，以及XML。在每一这些输出格式中，可以使用到不同的模板和设计风格。并且你甚至可以建立你自己的模板——phpDocumentor使用这一著名的Smarty template引擎来操作数据。
三、PhpDocumentor基础

PhpDocumentor可以通过PEAR获得，PHP Extension 以及 Application Repository可以从PhpDocumentor.org中下载。

在pear下安装phpDocumentor是一件极其简单的事情，只需要在cmd窗口中cd 到php安装目录下，然后输入Pear install phpDocumentor Pear就会自己下载并完成phpDocumentor的安装。

在phpDocumentor成功安装后，php安装目录下会多出来一个phpDocumentor.bat。这个文件就是我们用来生成文档的批处理文件了。在phpDocumentor.bat所在目录下，输入PhpDocumentor 欢迎进入PHP开发资源论坛讨论。

【收藏此文】【大中小】【打印】【关闭】

上一篇：Adodb 入门教程
下一篇：php 进阶:实现无限分类(1)