php 注释规范

用过IDE或看过其他源码的小伙伴们应该都见过类似下面这样的注释

/** * 递归获取所有游戏分类 * @param int $id * @return array */

看得多了就大概知道了一些规律。为了使自己的代码更加规zhuang范bi，也开始有样学样地写着这些注释

其实这种注释格式是有自己的名字的，它就叫——

PHPDOC

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

表示这是一个提供给第三方使用的API接口

@author

作者
格式@author [名称] [<邮箱>]
例如@author mokeyjay <i@mokeyjay.com>

@copyright

版权声明。例如很多网站底部都有
格式@copyright [描述]
例如@copyright 1949-2016 China

@deprecated

不建议使用的、已过期的、将被删除的
格式@deprecated [<版本号>] [<描述>]
例如@deprecated 1.0.0 新版本将不再包含此函数
如果它是被其他方法所取代了，建议添加@see标记

@example

例子、示例、用例。也可表示方法返回值的例子
格式@example [位置] [<起始行号> [<行数>] ] [<描述>]
例如@example demo.php 10 3 使用示例

@filesource

没看懂，如果你们看懂了请告诉我。传送门

@global

全局变量
格式@global [类型][名称] @global [类型][描述]
我怀疑这里是源文档打错了，大概应该是
格式@global [类型][名称][描述]
类型@global string name 用户名

@ignore

忽略
格式@ignore [<描述>]