用过ide或看过其他源码的小伙伴们应该都见过类似下面这样的注释
/** * 递归获取所有游戏分类 * @param int $id * @return array */
看得多了就大概知道了一些规律。为了使自己的代码更加规zhuang范bi，也开始有样学样地写着这些注释
其实这种注释格式是有自己的名字的，它就叫——
phpdoc 是一个 php 版的 javadoc。它是一种注释 php 代码的正式标准。它支持通过类似 phpdocumentor 这样的外部文档生成器生成 api 文档，也可以帮助一些例如 zend studio, netbeans, activestate komodo edit and ide 和 aptana studio 之类的 集成开发环境 理解变量类型和弱类型语言中的其他歧义并提供改进的代码完成，类型提示和除错功能。
phpdoc 可同时支持 面向对象 的和 面向过程的 代码。
以上摘自维基百科
简单来说phpdoc可以用来自动生成api文档。主流的ide都会识别它，并在你coding中给予你相应的智能提示。使用phpdoc有以下好处
让你的代码更加规zhuang范bi，更易于理解
让你的ide更懂你的代码，更加智能的提示和自动完成
如需api手册，可使用phpdocumentor来自动生成
还等什么？快跟我一起来学习又好用又有逼格的phpdoc吧！
有关phpdoc的完整文档位于phpdocumentor官网。以下内容由我个人理解、提炼而来，而且我也还在学习中，如有失误还请各位多多指教
表示这是一个提供给第三方使用的api接口
作者
格式@author [名称] [<邮箱>]
例如@author mokeyjay <i@mokeyjay.com>
版权声明。例如很多网站底部都有
格式@copyright [描述]
例如@copyright 1949-2016 china
不建议使用的、已过期的、将被删除的
格式@deprecated [<版本号>] [<描述>]
例如@deprecated 1.0.0 新版本将不再包含此函数
如果它是被其他方法所取代了，建议添加@see标记
例子、示例、用例。也可表示方法返回值的例子
格式@example [位置] [<起始行号> [<行数>] ] [<描述>]
例如@example demo.php 10 3 使用示例
没看懂，如果你们看懂了请告诉我。
全局变量
格式@global [类型][名称] @global [类型][描述]
我怀疑这里是打错了，大概应该是
格式@global [类型][名称][描述]
类型@global string name 用户名
忽略
格式@ignore [<描述>]
例如你在if和else的语句块中定义分别同一个变量但值不同时，可以通过此标记让phpdocumentor忽略其中一个，以免生成重复的文档。例如
我要评论
if ($ostest) {
/**
* this define will either be 'unix' or 'windows'
*/
define("os","unix");
} else {
/**
* @ignore
*/
define("os","windows");
}
仅限内部使用的
格式@internal [描述]
例如@internal 仅限内部测试使用
协议，很常见的啦
格式@license [<url>] [名称]
例如@license gpl
链接，可用于辅助说明、引用文档等
格式@link [url] [<描述>]
例如@link http://g.cn 不懂滚去问谷歌，别来烦我
方法。这是用在类注释里的标记。特别适合一些动态加载的类，ide无法自动提示出来，这时就可以通过写@method标记来告诉ide我这类里有哪些方法
格式@method [返回值类型] [名称]([[类型] [参数]<, ...>]) [<描述>]
例如@method string google(string $question) 向谷歌提问，返回答案内容
包。但php没有包，所以就用来表示命名空间
例如@package yii\base\db
参数，用于函数和方法注释里的标记
格式@param [type] [name] [<description>]
例如@param string title 文章标题
类属性，与@method类似，可以告诉ide我这类里有哪些属性
格式@property [type] [name] [<description>]
例如@property int id 用户id
只读的属性。例如__get魔术方法能够取到的属性
格式@property-read [type] [name] [<description>]
例如@property-read int id 用户id
只可写的属性。例如__set魔术方法能够设置的属性
格式@property-write [type] [name] [<description>]
例如@property-write string name 用户名
返回值
格式@return [类型] [<描述>]]
例如@return array 结果数组
参考，类似@link，可与@deprecated联动
格式@see [url或完整方法名] [<描述>]
例如@see \yii\base\db::tablename() 旧方法table_name已弃用，请使用此方法替代
从xx版本开始。例如从1.0之后添加了xx功能、删除了xx参数等
格式@since [1.0.0] [<描述>]
例如@since 1.0.2 添加了$b参数
没看懂，如果你们看懂了请告诉我。
可能会抛出的错误类型
格式@throws [类型] [<描述>]
例如@throws lifeexception 没钱了，好想死啊
待办。提示自己或他人还需要做些什么
格式@todo [描述]
例如@todo 这个类还没做异常处理
使用
格式@uses [完整方法名] [<描述>]
例如@uses \yii\base\db::$count 使用此属性计数
变量
格式@var [类型] [变量名] [<描述>]
例如@var int id 用户id
版本号
格式@version [<载体>] [<描述>]
例如@version 1.0.1 2016-07-03更新
或者@version git:1f3197d01 来自git分支1f3197d01
如对本文有疑问，请在下面进行留言讨论，广大热心网友会与你互动！！ 点击进行留言回复
YII2框架中使用RBAC对模块，控制器，方法的权限控制及规则的使用示例
YII2框架中ActiveDataProvider与GridView的配合使用操作示例
PhpStorm的使用教程(本地运行PHP+远程开发+快捷键)
网友评论