良好的文档注释不但能使代码易于维护,而且可以通过phpDocumentor等文档生成工具生成项目手册,以便于查阅。此外PHP的弱类型特征更应该引起我们对文档注释的重视!
本文简单的介绍下PHPDoc文档注释,以及常用的一些标签。
1. 文档注释并不只是用来注释整个文件的,在元素前面声明之后,它可以和该特定的程序元素相关联,例如类、函数、常量、变量、方法等等,以/**开头、*/结束,注意注释与相关联的程序元素间不能有空行;
2. 常用的标签
@author Author Name [<author@email.com>] 代码编写人(负责人)
@version xx.xx 当前版本号
@param datatype $v_name[,...] description 函数相关联的参数,含有,...表示可传入不定数量的其他参数
@return datatype description 函数或方法的返回值类型
@global datatype description 全局变量的说明(仅对phpDocumentor解析器起作用)
@var datatype 在类中说明类变量(属性)的类型
@example [path|url] description 举一个例子,以阐释使用方法
@todo description 待完成的工作信息或待解决的问题信息
更多的标签请参考 http://en.wikipedia.org/wiki/Phpdoc
这里举一个Zend Framework里的一段代码为例: