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的完整文档位于。以下内容由我个人理解、提炼而来，而且我也还在学习中，如有失误还请各位多多指教

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

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

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

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

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

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

忽略格式@ignore [<描述>] 例如你在if和else的语句块中定义分别同一个变量但值不同时，可以通过此标记让PHPDocumentor忽略其中一个，以免生成重复的文档。例如

PHP;"> if ($ostest) { /** * This define will either be 'Unix' or 'Windows' */ define("OS","Unix"); } else { /** * @ignore */ define("OS","Windows"); }

仅限内部使用的格式@internal [描述] 例如@internal 仅限内部测试使用

协议，很常见的啦格式@license [] [名称] 例如@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] [] 例如@param string title 文章 标题

类属性，与@method类似，可以告诉IDE我这类里有哪些属性格式@property [Type] [name] [] 例如@property int id 用户id

只读的属性。例如get魔术方法能够取到的属性格式@property-read [Type] [name] [] 例如@property-read int id 用户id

只可写的属性。例如set魔术方法能够设置的属性格式@property-write [Type] [name] [] 例如@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参数

没看懂，如果你们看懂了请告诉我。PHPdoc.org/docs/latest/references/PHPdoc/tags/source.html">传送门

可能会抛出的错误类型格式@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

php 注释规范

PHPDOC

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

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

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

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

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

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

仅限内部使用的格式@internal [描述] 例如@internal 仅限内部测试使用

协议，很常见的啦格式@license [] [名称] 例如@license GPL

链接，可用于辅助说明、引用文档等格式@link [url] [<描述>] 例如@link http://g.cn 不懂滚去问谷歌，别来烦我

包。但PHP没有包，所以就用来表示命名空间例如@package yii\base\db

参数，用于函数和方法注释里的标记格式@param [Type] [name] [] 例如@param string title 文章 标题

类属性，与@method类似，可以告诉IDE我这类里有哪些属性格式@property [Type] [name] [] 例如@property int id 用户id

只读的属性。例如__get魔术方法能够取到的属性格式@property-read [Type] [name] [] 例如@property-read int id 用户id

只可写的属性。例如__set魔术方法能够设置的属性格式@property-write [Type] [name] [] 例如@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参数

没看懂，如果你们看懂了请告诉我。PHPdoc.org/docs/latest/references/PHPdoc/tags/source.html">传送门

可能会抛出的错误类型格式@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

猜你在找的PHP相关文章

php 注释规范

PHPDOC

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

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

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

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

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

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

仅限内部使用的 格式@internal [描述] 例如@internal 仅限内部测试使用

协议，很常见的啦 格式@license [] [名称] 例如@license GPL

链接，可用于辅助说明、引用文档等 格式@link [url] [<描述>] 例如@link http://g.cn 不懂滚去问谷歌，别来烦我

包。但PHP没有包，所以就用来表示命名空间 例如@package yii\base\db

参数，用于函数和方法注释里的标记 格式@param [Type] [name] [] 例如@param string title 文章标题

类属性，与@method类似，可以告诉IDE我这类里有哪些属性 格式@property [Type] [name] [] 例如@property int id 用户id

只读的属性。例如__get魔术方法能够取到的属性 格式@property-read [Type] [name] [] 例如@property-read int id 用户id

只可写的属性。例如__set魔术方法能够设置的属性 格式@property-write [Type] [name] [] 例如@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参数

没看懂，如果你们看懂了请告诉我。PHPdoc.org/docs/latest/references/PHPdoc/tags/source.html">传送门

可能会抛出的错误类型 格式@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

猜你在找的PHP相关文章

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

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

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

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

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

仅限内部使用的格式@internal [描述] 例如@internal 仅限内部测试使用

协议，很常见的啦格式@license [] [名称] 例如@license GPL

链接，可用于辅助说明、引用文档等格式@link [url] [<描述>] 例如@link http://g.cn 不懂滚去问谷歌，别来烦我

包。但PHP没有包，所以就用来表示命名空间例如@package yii\base\db

参数，用于函数和方法注释里的标记格式@param [Type] [name] [] 例如@param string title 文章标题

类属性，与@method类似，可以告诉IDE我这类里有哪些属性格式@property [Type] [name] [] 例如@property int id 用户id

只读的属性。例如__get魔术方法能够取到的属性格式@property-read [Type] [name] [] 例如@property-read int id 用户id

只可写的属性。例如__set魔术方法能够设置的属性格式@property-write [Type] [name] [] 例如@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