phpdoc注释规范 - 介绍 ¶

• 作者：KK

• 发表日期：2016.9.16

相信大家都使用过网上的开源框架，以及下载过一些注释的类库代码（比如Smarty、PHPExcel、PHPMailer等）

咱们可以看到这些代码里是有这样的注释的：

主要是以这样的格式包起来：

/**
 * 注释内容。。。
 * 注释内容。。。。。。
 */

这种注释风格叫PHPDoc，可以参考维基百科 - PHPDoc

我这里主要拿常见的注释来讲，不常见的就算了，需要用的朋友可以多找教程资料

其中这种注释之所以要这样写是有它的原因的，你有没有发现它里面有@param、@return和@author什么的，不好好学习一遍都不知道怎么书写这些内容（什么时候要空开，什么时候要换行是有讲究的哦！）

而且这种注释写法是可以用工具转换成API文档的

比如下面这样一个方法的注释内容（摘自 yii2\db\Query 类的having方法并作了个人的翻译）：

/**
 * 设置查询的having部分
 * @param string|array $condition 条件
 * 请参考where方法的参数书写方式
 * @param array $params 参数绑定说明(name => value)
 * @return $this 查询对象自身
 * @see andHaving()
 * @see orHaving()
 */
public function having($condition, $params = [])
{
	$this->having = $condition;
	$this->addParams($params);
	return $this;
}

则使用特定的工具读取这些注释进行转换后，会生成这样的文档界面：

（点击查看在线网页版 Yii2框架通过工具将注释生成的API文档）

这些网页上的各个类的方法和属性介绍文档可不是人家一个个填写上去的，程序员遇到这种事的第一想法肯定就是“我得开发个工具快速填写”

相信你也能从代码和上图的内容中找到各个内容的一丝丝关系，比如有两个@see后面的andHaving()和orHaving()，在工具生成文档后被生成到“相关参考”的列表中，并且这些是超级链接，点击这些链接还真会跳到相关方法的介绍文档里

好了就介绍到这里，后面就写几篇文章把我常用的、觉得比较实用的注释格式介绍一下，并且会教大家用一些简单的工具进行API文档的转换生成；其实在这之前在Java语言里就已经有了JavaDoc注释规范了，我认为PHPDoc是参考了JavaDoc的风格来设计的