你会写注释么?从我写代码开始,这个问题就一直困扰着我,相信也同样困扰着其他同学。以前的写注释总是没有一套行之有效的标准,给维护和协同开发带了许多麻烦,直到最近读到了phpdocumentor的注释标准。
下面对phpdocumentor的注释标准进行总结:
Type(数据类型):
- string 字符串类型
- integer or int 整型
- boolean or bool 布尔类型 true or false
- float or double 浮点类型
- object 对象
- mixed 混合类型 没有指定类型或不确定类型时使用
- array 数组
- resource 资源类型 (如数据库查询返回)
- void 空值(控制器返回值经常使用)
- null null类型
- callable 回调函数
- false or true 只返回true or fasle 时使用
- self 自身
Tags(标签):
Tag | Element | Description |
api | Methods | 声明接口 |
author | Any | 作者信息 |
category | File, Class | 将一系列的元素分类在一起 |
copyright | Any | 版权信息 |
deprecated | Any | 声明元素已被弃用,可以在将来的版本中删除 |
example | Any | 示例 |
filesource | File | 文件资源 |
global | Variable | 声明一个全集变量 |
ignore | Any | 忽略当前元素 (phpdocumentor 生成文档时) |
internal | Any | 声明一个值为整形,或者设置一个应用的默认值为整型 |
license | File, Class | 声明许可类型 |
link | Any | 声明一个和当前元素有关的链接 |
method | Class | 声明当前类那些魔术方法可以被调用 |
package | File, Class | 声明当前元素所属的包 |
param | Method, Function | 声明当前元素的一个参数 |
property | Class | 声明当前类有那些魔术方法可以被调用属性 |
property-read | Class | 声明当前类有那些魔术方法可以读取属性 |
property-write | Class | 声明当前类有那些魔术方法可以设置属性 |
return | Method, Function | 返回值 |
see | Any | 说明当前元素参数引用于其他站点或元素 |
since | Any | 声明当前元素始于于哪个版本 |
source | Any, except File | 展示当前元素的源码 |
subpackage | File, Class | 将当期元素分类 |
throws | Method, Function | 说明当前元素抛出的异常 |
todo | Any | 说明当前元素的开发活动 |
uses | Any | 引用一个关联元素 |
var | Properties | 声明属性 |
version | Any | 版本 |
Example(示例):
// =============================
@api
// =============================
@author
// =============================
@category
// =============================
@copyright
// =============================
@deprecated
// =============================
@example
// =============================
@filesource
// =============================
@global phpdocumentor2.0不支持
// =============================
@ignore
// =============================
@internal
// =============================
@license
// =============================
@link
// =============================
@method
// =============================
@package
// =============================
@param
// =============================
@property
// =============================
@property-read
// =============================
@property-write
// =============================
@return
// =============================
@see
// =============================
@since
// =============================
@source
// =============================
@subpackage
// =============================
@throws
// =============================
@todo
// =============================
@uses
// =============================
@var
// =============================
@version
// =============================
phpdocumentor手册:http://www.phpdoc.org/docs/latest/index.html