PHP注释规范（PHPDOC）总结
针对PHP开发规范，有必要总结⼀下，与各位分享
⽤过IDE或看过其他源码的⼩伙伴们应该都见过类似下⾯这样的注释
/**
* 递归获取所有游戏分类
* @param int $id
* @return array
*/
看得多了就⼤概知道了⼀些规律。为了使⾃⼰的代码更加规zhuang范bi，也开始有样学样地写着这些注释。其实这种注释格式是有⾃⼰的名字的，它就叫——PHPDOC。
1、介绍
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 来⾃动⽣成
2、常规使⽤
有关phpDoc的完整⽂档位于官⽹。以下仅为整理的常⽤规范。
@api
表⽰这是⼀个提供给第三⽅使⽤的API接⼝
@author
php手册官方中文版
作者
格式@author [名称] [<；邮箱>]
例如@author Leroi <leroiliu@163>
@copyright
版权声明。例如很多⽹站底部都有
格式@copyright [描述]
例如@copyright 1949-2019 China
@deprecated
不建议使⽤的、已过期的、将被删除的
格式@deprecated [<；版本号>] [<；描述>]
例如@deprecated 1.0.0 新版本将不再包含此函数
如果它是被其他⽅法所取代了，建议添加@see标记
@example
例⼦、⽰例、⽤例。也可表⽰⽅法返回值的例⼦
格式@example [位置] [<；起始⾏号> [<⾏数>] ] [<；描述>]
例如@example demo.php 10 3 使⽤⽰例
@global
全局变量
格式@global [类型][名称][描述]
类型@global string name ⽤户名
@ignore
忽略
格式@ignore [<；描述>]
例如你在if和else的语句块中定义分别同⼀个变量但值不同时，可以通过此标记让phpDocumentor忽略其中⼀个，以免⽣成重复的⽂档。例如
if ($ostest) {
/**
* This define will either be 'Unix' or 'Windows'
*/
define("OS","Unix");
} else {
/**
* @ignore
*/
define("OS","Windows");
}
@internal
仅限内部使⽤的
格式@internal [描述]
例如@internal 仅限内部测试使⽤
@license
协议，很常见的啦
格式@license [<url>] [名称]
例如@license GPL
@method
⽅法。这是⽤在类注释⾥的标记。特别适合⼀些动态加载的类，IDE⽆法⾃动提⽰出来，这时就可以通过写@method标记来告诉IDE我这类⾥有哪些⽅法
格式@method [返回值类型] [名称]([[类型] [参数]<, ...>]) [<；描述>]
静态⽅法格式@method static [返回值类型] [名称]([[类型] [参数]<, ...>]) [<；描述>]
例如@method string google(string $question) 向⾕歌提问，返回答案内容
@package
包。但php没有包，所以就⽤来表⽰命名空间
例如@package yii\base\db
@param
参数，⽤于函数和⽅法注释⾥的标记
格式@param [Type] [name] [<description>]
例如@param string title ⽂章标题
@property
类属性，与@method类似，可以告诉IDE我这类⾥有哪些属性
格式@property [Type] [name] [<description>]
例如@property int id ⽤户id
@property-read
只读的属性。例如__get魔术⽅法能够取到的属性
格式@property-read [Type] [name] [<description>]
例如@property-read int id ⽤户id
@property-write
只可写的属性。例如__set魔术⽅法能够设置的属性
格式@property-write [Type] [name] [<description>]
例如@property-write string name ⽤户名
@return
返回值
格式@return [类型] [<；描述>]]
例如@return array 结果数组
@see
参考，类似@link，可与@deprecated联动
格式@see [url或完整⽅法名] [<；描述>]
例如@see \yii\base\db::tableName() 旧⽅法table_name已弃⽤，请使⽤此⽅法替代
@since
从xx版本开始。例如从1.0之后添加了xx功能、删除了xx参数等
格式@since [1.0.0] [<；描述>]
例如@since 1.0.2 添加了$b参数
@throws
可能会抛出的错误类型
格式@throws [类型] [<；描述>]
例如@throws LifeException 没钱了，好想死啊
@todo
待办。提⽰⾃⼰或他⼈还需要做些什么
格式@todo [描述]
例如@todo 这个类还没做异常处理
@uses
使⽤
格式@uses [完整⽅法名] [<；描述>]
例如@uses \yii\base\db::$count 使⽤此属性计数
@var
变量
格式@var [类型] [变量名] [<；描述>]
例如@var int id ⽤户id
@version
版本号
格式@version [<；载体>] [<；描述>]
例如@version 1.0.1 2016-07-03更新
或者@version GIT:1f3197d01 来⾃GIT分⽀1f3197d01

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。