上次给大家介绍了一下迭代开发，这次先不”向下兼容“，插播点别的。

今天咱们就来说说PhpDocumentory。

PHPDocumentor是一个用PHP写的工具，对于有规范注释的php程序，它能够快速生成具有相互参照,索引等功能的API文档。可以通过在客户端浏览器上操作生成文档，文档可以转换为PDF,HTML,CHM几种形式，非常的方便。

1、 安装PEAR

PEAR：是PHP扩展与应用库的缩写(the PHP Extension andApplication Respository)的缩写。它是一个扩展及应用的一个代码仓库。

A）、进入到PHP安装目录，并且查看PEAR文件夹是否为空（为空的话代表你没装过PEAR）。

B）、在dos命令行下进入到PHP的根目录，并执行go-pear.bat。

2、 使用pear中的install命令安装PHPDocumentor

PHPDocumentor：PHPDocumentor是一个用PHP写的工具，对于有规范注释的php程序，它能够快速生成具有相互参照,索引等功能的API文档。

注：安装成功后会提示install ok: channel://pear.php.net/PhpDocument-1.4.4

3、 生成API文件，使用phpdoc命令加上-f参数（生成的php文件路径）、-t参数（导出API的目录）、-o参数（生成的格式）

4、 附录：

a) 系统提示丢失php_mbstring.dll。尝试安装该程序以解决该问题。

1. 进入到环境变量菜单选中Path点击编辑

2. 将php安装目录中的ext路径复制过来。

3. 重启电脑

b）phpdoc命令的参数

-f

要进行分析的文件名，多个文件用逗号分割

-d

要分析的目录，多个目录用逗号分割

-t

生成的文档的存放路径

-o

输出的文档格式，结构为输出格式:转换器名:模版目录，例如：HTML:frames:phpedit

c）生成API文档的格式：

HTML:Smarty:default,

HTML:frames:earthli,

HTML:frames:l0l33t,

HTML:frames:phpdoc.de,

HTML:frames:phphtmllib,

HTML:frames:phpedit,

HTML:frames:phpedit,

HTML:frames:DOM/default,

HTML:frames:DOM/earthli,

HTML:Smarty:default,

HTML:Smarty:HandS,

HTML:Smarty:PHP,

PDF:default:default,

CHM:default:default,

XML:DocBook/peardoc2:default

d）源php文件的规则

1、首先，第一行是一个注释开始的标志"/**"。

2、然后是回车。

3、从第2行开始就是功能简述区，功能简述区是以缩进的"*"开始的，在简述的正文和这个"*"号 之间用空格分隔（注意，在文档中，都是以*开始，并且这些*保持对齐的缩进格式）。功能简述的正文一般是简明扼要地说明这个类，方法或者函数的功能，功能 简述的正文在生成的文档中将显示在索引区。

4、在功能简述区后面是一个空的注释行，用来分割简述区和详细说明区。功能详细说明区也是以缩进的'*"来引导的，这部分主要是详细说明你的API的功能，用 途，如果可能，也可以有用法举例等等。在这部分，你应该着重阐明你的API函数或者方法的通常的用途，用法，并且指明是否是跨平台的（如果涉及到），对于 和平台相关的信息，你要和那些通用的信息区别对待，通常的做法是另起一行，然后写出在某个特定平台上的注意事项或者是特别的信息。

5、class 、function 、var、include (include_once, require, require_once) 、define在以上这些关键字前面所做的注释，都被认为是文档性注释。

6、常用标识

1）、@abstract 使用范围：class, function, var

说明当前类是一个抽象类。

2）、@access (public|private) 使用范围：class,function, var, define, module

指明这个变量、类、函数/方法的存取权限。

3）、 @author Name [<email>] [, ...] 使用范围：class,function, var, define, module, use指明作者信息,依次是作者姓名，email地址，其他的通讯信息。如果有多个作者，按照其先后次序，使用多个@author依次列出。

4）、@const[ant] label [description] 使用范围：define

指明常量，这个标记实际上是用来说明php的define关键字定义的常量。

5）、@copyright description 使用范围：class, function,var, module, define, use

指明版权信息。

6）、@deprec[ated] label 使用范围：class, function,var, module, define, use

指明不推荐或者是废弃的信息.

7）、@exclude label 使用范围：class, function, var,module, define, use

指明当前的注释将不进行分析，不出现在文挡中

8）、@final 使用范围：class, function, var

指明这是一个最终的类、方法、属性，禁止派生、修改。

9）、@include description 使用范围：use

指明包含的文件的信息。

10）、@param[eter] (object objecttype|type) [$varname] [description] 使用范围：function

定义函数或者方法的参数信息。这是最常使用的文档标记了。

$varname 是形参的名称。

[description]是对于参数的说明。

如果函数接受的是多个参数，那么要按照从左到右，依次用@param对齐列出

ojecttype是对象的类名，type 指出这个参数的类型，它可以是下列类型：

a、 string该参数是一个字符型变量。

b、 array该参数是一个数组。

c、 integer该参数是一个数值型。

d、 integer(octal) 该参数是一个数值型，并且是按照八进制方式存放。

e、 integer(hexadecimal) 该参数是一个数值型，并且是按照十六进制方式存放。

f、 boolean该参数是一个布尔型。

g、 mixed该参数的类型是可变的，可以上面几种类型的组合。不过，在随后的说明中一般要说明可以接受的变量的类型。

11）、@return (object objecttype|type) [$varname] 使用范围：function

定义函数或者方法的返回信息。不同的是@return只有一个，不会出现多个@return

12）、@todo 使用范围：class, function, module, use

指明应该改进或没有实现的地方

13）、@version label 使用范围：class, function, module,use

定义版本信息.

14）、@throws exception [, exception] 使用范围：function

指明此函数可能抛出的错误异常,极其发生的情况

15）、@var[iable] (object objecttype|type) [$varname] [description] 使用范围：var

定义说明变量/属性。

object objecttype|type 定义你的变量的类型，同@param一样

$varname 该变量的名字，你可以从其他地方使用@see来引用这个名字

description 对变量的描述

16）、@copyright

使用范围：class，function，var，define，module，use

指明版权信息

17）、@example

用于解析一段文件内容，并将他们高亮显示。Phpdoc会试图从该标记给的文件路径中读取文件内容