phpdoc/phpdocumentor注释规范

phpDocumentor通过解析PHP代码逻辑结构（如文件，类，函数，常量，全局变量，类成员/方法等），重新整理后生成普通的可读说明文档。

一、给php代码添加规范的注释
PHPDocument是从源代码的注释中生成文档，因此在给程序做注释时，即编制文档的过程。即，PHPdoc促使你要养成良好的编程习惯，尽量使用规范，清晰文字为程序做注释，同时也避免了事后编制文档和文档的更新不同步的一些问题。在phpdocumentor中，注释分为文档性注释和非文档性注释。所谓文档性注释，是放在特定关键字前面的多行注释，特定关键字是指能够被phpdoc分析的关键字，例如class，var等。没有在关键字前面或者不规范的注释就称作非文档性注释，这些注释将不会被phpdoc所分析，也不会出现在解析的文档中。

所有的文档性注释都是由/**开始的一个多行注释，在phpDocumentor里称为DocBlock，DocBlock是指软件开发人员编写的关于某个关键字的帮助信息，使得其他人能够通过它知道这个关键字的具体用途，如何使用。 PhpDocumentor规定一个DocBlock包含如下信息：
1. 功能简述区
2. 详细说明区
3. 标记tag
文档性注释的第一行是功能描述区，正文一般是简明扼要地说明这个类，方法或者函数的功能，功能简述的正文在生成的文档中将显示在索引区。功能描述区的内容可以通过一个空行或者”. “来结束。在功能描述区后是一个空行，接着是详细说明区，这部分主要是详细说明你的API的功能、用途、如果可能也可以有用法举例等等。在这部分，你应该着重阐明你的API函数或者方法的通常的用途、用法，并且指明是否是跨平台的（如果涉及到），对于和平台相关的信息，你要和那些通用的信息区别对待。通常的做法是另起一行，然后写出在某个特定平台上的注意事项或者是特别的信息，这些信息应该足够，以便你的读者能够编写相应的测试信息，比如边界条件，参数范围，断点等等。之后同样是一个空白行，然后是文档的标记tag，指明一些技术上的信息，主要是调用参数类型、返回值极其类型、继承关系、相关方法/函数等。例如：

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

但是在phpdoc下生成的格式如下：
Add (line 11)
integer Add( int $a, int$b)
函数add,实现两个数的加法
一个简单的加法计算，函数接受两个数a、b，返回他们的和c
Parameters
int $a: 加数 int$b: 被加数
Info

二、文档标记：
文档标记的使用范围是指该标记可以用来修饰的关键字，或其他文档标记。所有的文档标记都是在每一行的 * 后面以@开头。如果在一段话的中间出来@的标记，这个标记将会被当做普通内容而被忽略掉。
@access
使用范围：class,function,var,define,module
该标记用于指明关键字的存取权限：private、public或proteced
@author
使用范围：class，function，var，define，module，use
指明作者
@copyright
使用范围：class，function，var，define，module，use
指明版权信息
@deprecated
使用范围：class，function，var，define，module，constent，global，include
指明不用或者废弃的关键字
@example
该标记用于解析一段文件内容，并将他们高亮显示。PHPDOC 会试图从该标记给的文件路径 中读取文件内容
@const
使用范围：define
用来指明php中define的常量
@final
使用范围：class,function,var
指明关键字是一个最终的类、方法、属性，禁止派生、修改。
@filesource
和example类似，只不过该标记将直接读取当前解析的php文件的内容并显示。
@global
指明在此函数中引用的全局变量
@ingore
用于在文档中忽略指定的关键字
@license
相当于html标签中的,首先是URL，接着是要显示的内容
例如百度
可以写作 @license http://www.baidu.com 百度
@link
类似于license
但还可以通过link指到文档中的任何一个关键字
@name
为关键字指定一个别名。
@package
使用范围：页面级别的 define，function，include
类级别的 class，var，methods
用于逻辑上将一个或几个关键字分到一组。
@abstrcut
说明当前类是一个抽象类
@param
指明一个函数的参数
@return
指明一个方法或函数的返回指
@static
指明关建字是静态的。
@var
指明变量类型
@version
指明版本信息
@todo
指明应该改进或没有实现的地方
@throws
指明此函数可能抛出的错误异常，极其发生的情况
上面提到过，普通的文档标记标记必须在每行的开头以@标记，除此之外，还有一种标记叫做inline tag,用{@}表示，具体包括以下几种：
{@link}
用法同@link
{@source}
显示一段函数或方法的内容

/**
* @name 名字
* @abstract 申明变量/类/方法
* @access 指明这个变量、类、函数/方法的存取权限
* @author 函数作者的名字和邮箱地址
* @category 组织packages
* @copyright 指明版权信息
* @const 指明常量
* @deprecate 指明不推荐或者是废弃的信息
* @example 示例
* @exclude 指明当前的注释将不进行分析，不出现在文挡中
* @final 指明这是一个最终的类、方法、属性，禁止派生、修改。
* @global 指明在此函数中引用的全局变量
* @include 指明包含的文件的信息
* @link 定义在线连接
* @module 定义归属的模块信息
* @modulegroup 定义归属的模块组
* @package 定义归属的包的信息
* @param 定义函数或者方法的参数信息
* @return 定义函数或者方法的返回信息
* @see 定义需要参考的函数、变量，并加入相应的超级连接。
* @since 指明该api函数或者方法是从哪个版本开始引入的
* @static 指明变量、类、函数是静态的。
* @throws 指明此函数可能抛出的错误异常,极其发生的情况
* @todo 指明应该改进或没有实现的地方
* @var 定义说明变量/属性。
* @version 定义版本信息
*/

三、简单注释规范
1.注释必须是
/**
* XXXXXXX
*/
的形式
2.对于引用了全局变量的函数，必须使用glboal标记。
3.对于变量，必须用var标记其类型（int,string,bool…）
4.函数必须通过param和return标记指明其参数和返回值
5.对于出现两次或两次以上的关键字，要通过ingore忽略掉多余的，只保留一个即可
6.调用了其他函数或类的地方，要使用link或其他标记链接到相应的部分，便于文档的阅读。
7.必要的地方使用非文档性注释，提高代码易读性。
8.描述性内容尽量简明扼要，尽可能使用短语而非句子。
9全局变量，静态变量和常量必须用相应标记说明

四、输出格式
-o, –output
设置输出文件的格式
HTML:frames:* - 包含iframe的HTML格式
HTML:frames:default – Javadoc风格的文档模板，很少有格式
HTML:frames:earthli – 漂亮的模板（作者：Marco von Ballmoos）
HTML:frames:l0l33t – 流行模板
HTML:frames:phpdoc.de – 类似于phpdoc.de的PHPDoc输出
HTML:frames:phphtmllib – 非常棒的用户贡献模板
HTML:frames:phpedit – 基于PHPEdit Help Generator的文档
HTML:Smarty:* - 不使用iframe的HTML格式
HTML:Smarty:default – 使用css控制的黑体模板
HTML:Smarty:HandS – 基于PHP的格式，但是经过优化，带有logo图片
HTML:Smarty:PHP – 风格接近PHP官网
CHM:default:* - 输出CHM帮助文档
CHM:default:default – windows帮助文档，基于HTML:frames:l0l33t
PDF:default:* - PDF格式
PDF:default:default – 标准纯文本PDF格式
XML:DocBook:* - 以DocBook格式输出的XML
XML:DocBook/peardoc2:default – 可以被编译成peardoc的文档

五、将phpdoc集成到phpstorm中
在phpstorm的settings，搜索extend tools, 然后添加phpdoc即可，简单配置一下。

主要包括name，program，parameters以及working directory。
name不用多说。
program是php.exe文件的路径
parameters是phpdoc的执行命令，包括原文件夹，解析后的文件输出文件夹，以及可以设置忽略的文件夹。
working directory，当填写好php.exe的路径后会自动填充。

最后在phpstorm的tools—>extend tools->phpdoc（在图中填写的name）。点击就会执行解析任务。