『静哥的项目管理之路』_迭代开发2

最新推荐文章于 2021-05-27 08:05:00 发布

u011886490

最新推荐文章于 2021-05-27 08:05:00 发布

阅读量471

点赞数

分类专栏：系统运维

本文链接：https://blog.csdn.net/lampzdrj/article/details/10599611

版权

系统运维专栏收录该内容

298 篇文章 0 订阅

订阅专栏

上次给大家介绍了一下迭代开发，这次先不”向下兼容“，插播点别的。
今天咱们就来说说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会试图从该标记给的文件路径中读取文件内容