基础级-phpDocumentor

设想一下，你自己设计、书写的程序，倘若无需他人参与，你是否就不需要文档？
　时隔一年，你还能记清代码中的细节吗？一个方法的参数是整型，还是字符串类型？亦或是布尔型？
　　编程作为一种兴趣，我对它报以热情、投入成本，自然就不希望：我亲手书写的代码，变成盘根错节的麻绳，绊倒我自己。毕竟，我们很难追踪系统的工作方式和编码目的，对于一个大型项目来说，往往文档会成为致命级的存在。

用法

　　在phpDocumentor中，注释分为文档性注释和非文档性注释。前者会被phpDocumentor解析为文档内容，后者被忽略，故而，我们只讨论文档性注释。
　　安装，PEAR也可以，我是采用官网下载，直接放置于Apache虚拟目录下，访问对应网址即可进入Web端；将目录定位于物理目录上，也可以运行命令行。
　　PEAR命令-升级或安装PhpDocumentor：pear upgrade PhpDocumentor；
　　下载了PhpDocumentor包后，PEAR安装：pear install PhpDocumentor-1.43.tgz；
　　（指南：PhpDocumentor包中INSTALL文件，提供了详细的说明和疑难解答）
　　使用：依然是代码行，Web端只需要翻译器或者英语基础即可。
-d： 代码的存放目录
-t： 文档的存放目录
-ti：项目标题
-dn：默认包名
-pp：是否对 私有元素 生成文档（parseprivate）

phpdoc -d megaquiz/ \
　　　　-t doc/megaquiz/ \
　　　　-ti 'Mega Quiz' \
　　　　-dn 'megaquiz'
        -pp on

格式

/**
* Content...
*/

　　上述格式，在phpDocumentor里称为DocBlock（文档区），DocBlock是指软件开发人员编写的，关于某个关键字的帮助信息，使得其他人能够通过它知道这个关键字的具体用途，如何使用。
　　phpDocumentor规定一个DocBlock包含如下信息：
　　（每个部分，空行隔开）
　　　1. 功能简述区：简明扼要的描述类、方法、函数的功能。
　　　2. 详细说明区：说明API的功能、用途、参数、边界、是否跨系统、注意事项等。
　　　3. 标记Tag：返回值、继承关系、相关方法等。

　　借用参考资料的代码：

/** 
* 函数add,实现两个数的加法 
* 
* 一个简单的加法计算，函数接受两个数a、b，返回他们的和c 
* 
* @param int 加数 
* @param int 被加数 
* @return integer 
*/  
function Add($a, $b) {
return $a+$b;
}

　　如上述。我采用的是Web端测试：Logo同行的就是各种选项，英文基础即可弄懂，右下角是“Create”创建文档——前提是你设置完毕。

特殊关键字

/** 
* @package command //标记该类所属的包
* @author Weall.C.Mark //标记作者
* @copyright 2004 Ambridge Technologies Ltd //标记版权信息
* @license http://www.example.com/lic.html Borsetshire Open License //指向许可的URL，以及介绍
* @var string //标记一个属性
* @return bool执行失败返回False，成功返回True。
* @see Command::$exe; //在文档中，对其他内容的引用，并创建超链接
* @link http://www.baidu.com/index.php //只包含对元素（Command::execute();）的引用，也用于指向URL
* @user CommandContext //可以在本文档中创建一个链接（User:CommandContext），而在CommandContext类文档中，将出现新链接：Command::execute();
*/

Tips：
- 文件的文档，文件描述位于文件中第一个DocBlock。许多开源项目要求含有许可公告或指向许可公告的URL。[@license]
- 类的文档：包含一个摘要、一个可选的描述，以及特殊关键字。用于标示一个类，解释它的用法，增加所属包、作者、版权等信息。[@package、@author、@copyright]
- 属性的文档：PHP的属性类型是混合的，尽管弱类型语言很方便，但大多数时候，属性应该是一个特定的数据类型。[@var]
- 方法的文档：近似类的文档，多了返回值的描述，因为PHP的弱类型，返回值需要更详细的描述。[@return]
- 抽象类、抽象方法的文档：看起来，添加比代码内容还多的文档看起来有点怪异，但抽象类的文档特别重要，因为它为程序员理解如何扩展类提供了方向，当然，理想方式是在安装程序时删除注释（这里需要运用你的构建工具，不赘述）
- 文档中的链接：关联相关类、方法、其他元素或外部站点。[@see]

结语

本篇介绍了PhpDocumentor的核心内容，这对团队协作的意义重大。PhpDocumentor还有更多奇妙的功能，欢迎前往官网了解（网址见参考资料）。

参考资料：
《深入PHP：对象、模式与实践》 - Matt Zandstra
PHP Document 代码注释规范 - leonzhang2008
PhpDocumentor官网