PEAR：使用PHPDoc简单创建你的PEAR文档

type 定义你的变量的类型，同@param一样
$varname 该变量的名字，你可以从其他地方使用@see来引用这个名字
description 对变量的描述

@version label 使用范围：class, function, module, use
定义版本信息.
你当然可以自己手工写这些版本信息，不过PEAR推荐你使用CVS的$Id标记来自动标示你的版本信息。形式如下：

@version $Id
这样，当你checkout的时候，CVS自动会扩展成： @version $Id: PhpdocParserCore.php,v 1.4 2001/02/18 14:45:27 uw Exp

5. 生成文档
5.1 安装PHPDOC
安装PHPDOC很简单,实际上因为它已经随同PHP 4.05一同发布了,所以如果你的PHP是4.05,那么在PEAR目录下面会发现PHPDOC这个模块.如果你没有发现,你可以从PHPDOC的CVS获得一份最新的源码.

5.2 运行PHPDOC
运行PHPDOC需要做一些准备工作,首先要调整你的PHP.INI的参数，

因为PHPDOC运行的时间比一般的PHP应用要长，很可能会超过你在PHP.INI中定义的最大运行时间（缺省是30秒），根据作者的建议：PIII，60秒，120秒PII，240秒MMX200，480秒如果配置更低的话。如果出现超时，你可以自己适当延长这些数值。

在php.ini中修改：
;;;;;;;;;;;;;;;;;;;
; Resource Limits ;
;;;;;;;;;;;;;;;;;;;

max_execution_time = 480
memory_limit = 8388608




如果你不愿意或者没有修改php.ini的权限，那么你可以使用set_time_limit（）函数来设置这个时间，使用方法： set_time_limit(480); 设置从此点开始，运行480秒后才超时。将这个函数加在index.php中，就可以和修改php.ini达到同样的效果。

其次，你要修改phpdoc目录下面的index.php文件：
// Directory with include files
define("PHPDOC_INCLUDE_DIR", "c:/www/apache/doc/");


将"c:/www/apache/doc/修改成你的phpdoc的目录
// Important: set this to the Linebreak sign of your system!
define("LINEBREAK", "\r\n");
这是定义换行的标志，DOS下面是换行+回车，UNIX下面只是回车就可以。

下面，为你的要生成文档的应用程序做一些定制工作：
// Sets the name of your application.
// The name of the application is used e.g. as a page title
$doc->setApplication("PHPDoc");

setApplication（）用来设置你的应用程序的名称，将PHPDOC替换成你应用程序的名字。

// directory where your source files reside:
$doc->setSourceDirectory(PHPDOC_INCLUDE_DIR);

setSourceDirectory（）设置你的应用程序的PHP源文件所在的目录，将PHPDOC_INCLUDE_DIR替换成你实际的目录。

// save the generated docs here:
$doc->setTarget(PHPDOC_INCLUDE_DIR."apidoc/");

setTarget（）设置你的API文档存放的目录，PHPDOC将在这个目录下面生成XML及HTML文件。将PHPDOC_INCLUDE_DIR."apidoc/"替换成你自己的目录。

// use these templates:
$doc->setTemplateDirectory(PHPDOC_INCLUDE_DIR."renderer/html/templates/");

setTemplateDirectory（）设置HTML所使用的模板的目录。如果你需要使用定制的模板，可以使用这个函数设置你自己的模板文件所在的目录。

// source files have one of these suffixes:
$doc->setSourceFileSuffix( array ("php", "inc") );

setSourceFileSuffix（）用来设置需要分析的PHP源文件的扩展名，如果你使用了别的扩展名，需要在这里添加，比如如果你有以前的php3文件，需要添加：
$doc->setSourceFileSuffix( array ("php", "inc"，"php3") );


这样，基本的定制工作就完成了，现在你可以在浏览器中运行index.php,出现了欢迎信息后,就是开始分析文档了.根据机器的状况和所分析的源代码文件的数量不同,文档分析过程所需的时间也不会相同.文档分析结束后,浏览器会显示FINISH的字样,表明分析完成,你可以在刚才指定的目录下面找到分析结果,包括HTML和XML文件.

5.3 实用工具
通过PHPDOC的INDEX.PHP虽然可以产生文档,但是毕竟不是那么方便,这里我给出了一个自己写的shell程序 makeapidoc ,你可以用它来方便的产生你的API文档,无须每次都要修改，也不用非要启动浏览器来执行。

用法如下:makeapidoc -t 你的应用程序的标题 -s 源程序目录 -d 生成文档存放目录

在使用之前，先修改下面2行：
PHPDOC_DIR="/usr/local/lib/php/pear/PHPDoc" # windows: c:/php/pear/PHPDoc
PHPBIN="/usr/local/bin/php" #windows: c:/php/php.exe
PHPDOC_DIR是PHPDOC的目录，PHPBIN是PHP可执行文件的路径。


这个程序实际上是把PHP作为一个SHELLSCRIPT来使用了，不过是嵌在BASH中使用，实际上PHP完全可以做为普通的SHELL脚本一样运行，只需加上 -q 参数，这样就不打印HTTP HEADER了。


6. 进阶：定制输出的文档
如果你认为缺省的PHPDOC产生的HTML文档不够美观,你想做进一步的改进,比如你想把一些注释换成中文或者是其他的文字,你想加入你的LOGO,或者是你的联系方式,换成一个漂亮的背景图案,有没有方法可以作到?答案是当然可以,并且非常简单.

PHPDOC在输出HTML格式的API文档的时候,使用的是PEAR的IT,ITX模块,这是类似PHPLIB的TEMPLETE.CLASS的PEAR模块,因此,你可以方便地定制和修改缺省的模板来为你所用.

我们先看看PHPDOC/renderer/html/templates: class.html classtree.html elementlist.html frame_packageelementlist.html
frame_packagelist.html module.html modulegroup.html packagelist.html phpdoc.css warnings.html xmlfiles.html

你会看到上面的这些文件,没错,这些就是PHPDOC用来产生API HTML的模板,现在你可以用你的编辑器来修改这些模板了,这里给出基本的修改原则:

对于用{}圈起来的标记,这些是一些变量的标记,在运行时刻,PHPDOC将会用实际的变量值替换到相应的位置.因此,你务必要保留全部的变量标记,否则运行时将会出错.
你要注意<!--Begin Xxx-loop --><!--End Xxx -loop-->之类带LOOP的注释,在这2个标记中间的部分,将会用于循环输出,所以,你在设计模板时要考虑到循环使用,是否会破坏你页面的美观,最简单的比如:如果循环的部分是在一个表格内,你要用<tr>用来分隔各循环调用的部分,同时应该保证各个<TD></TD>是匹配关闭的.
当你修改的地方不大,你也可以直接修改样式表phpdoc.css的内容,这样也可以达到你要求的效果
你可以把模板存放在不同的目录，通过setTemplateDirectory（）设置不同的模板路径，就可以生成不同格式的API文档

7. 参考资源

PHPDOC HOME
PHPDOC CVS

关键词：PEAR：运用PHPDoc简单创建你的PEAR文档