前言
注释标签在代码注释中的作用非常大，好的找注释标签可以让你在编程过程中有更好、更舒适的体验，所以我今天准备整理一下这些标记，通过图文的形式展示出来，一方面是为了自己对这些注释标签有一个汇总整理，另一方面也希望大家能够更好对理解注释标签
每个人都希望写出漂亮的代码，或许你离漂亮的代码，就差一个标签
常用标签
| 标记 | 用途 | 描述 |
|---|---|---|
| @abstract | 抽象类的变量和方法 | |
| @access | public, private or protected | 文档的访问、使用权限. @access private 表明这个文档是被保护的。 |
| @author | 张三 zhangsan@163.com | 文档作者 |
| @copyright | 名称 时间 | 文档版权信息 |
| @deprecated | version | 文档中被废除的方法 |
| @deprec | 同 @deprecated | |
| @example | /path/to/example | 文档的外部保存的示例文件的位置。 |
| @exception | 文档中方法抛出的异常，也可参照 @throws. | |
| @global | 类型：$globalvarname | 文档中的全局变量及有关的方法和函数 |
| @ignore | 忽略文档中指定的关键字 | |
| @internal | 开发团队内部信息 | |
| @link | URL | 类似于 license 但还可以通过 link 找到文档中的更多个详细的信息 |
| @name | 变量别名 | 为某个变量指定别名 |
| @magic | phpdoc.de compatibility | |
| @package | 封装包的名称 | 一组相关类、函数封装的包名称 |
| @param | 如 $username 用户名 | 变量含义注释 |
| @return | 如 返回 bool | 函数返回结果描述，一般不用在 void（空返回结果的）的函数中 |
| @see | 如 Class Login () | 文件关联的任何元素（全局变量，包括，页面，类，函数，定义，方法，变量）。 |
| @since | version | 记录什么时候对文档的哪些部分进行了更改 |
| @static | 记录静态类、方法 | |
| @staticvar | 在类、函数中使用的静态变量 | |
| @subpackage | 子版本 | |
| @throws | 某一方法抛出的异常 | |
| @todo | 表示文件未完成或者要完善的地方 | |
| @var | type | 文档中的变量及其类型 |
| @version | 文档、类、函数的版本信息 |
上面这么多其实很大一部分都是创建文件、创建类的时候需要添加的。今天主要讲解一下常用的标签。
@param
说明
参数，用于函数和方法注释里的标记 \
格式 @param [Type] [name] [<description>]\
例如 @param string title 文章标题
代码举例
@return
说明
返回值
格式 @return [类型] [< 描述 >]]
例如 @return array 结果数组
代码举例
@deprecated
说明
不建议使用的、已过期的、将被删除的 \
格式 @deprecated [<版本号>] [<描述>]\
例如 @deprecated 1.0.0 新版本将不再包含此函数 \
如果它是被其他方法所取代了，建议添加 @see 标记
代码举例
@see
说明
参考，类似 @link，可与 @deprecated 联动
格式 @see [url 或完整方法名] [< 描述 >]
例如 @see \yii\base\db::tableName () 旧方法 table_name 已弃用，请使用此方法替代
代码举例
@link
说明
链接，可用于辅助说明、引用文档等 \
格式 @link [url] [<描述>]\
例如 @link http://g.cn 不懂滚去问谷歌，别来烦我
代码举例
@link&@see 区别
| - | @see | @link |
|---|---|---|
| 外部链接 | √ | √ |
| 内部程序 | √ | X |
@var
说明
变量 \
格式 @var [类型] [变量名] [<描述>]\
例如 @var int id 用户id
变量列表
| 变量类型 | 说明 |
|---|---|
| string | 字符串 |
| integer/int | number/int 类型 |
| boolean/bool | false/true |
| float/double | number / 浮点数 |
| object | 对象实例 |
| specifiedType | 指定类 |
| mixed | 任意类型 |
| array/specifiedType[] | 数组，可以指定成指定类型的数组 |
| resource | 文件资源类型 |
| void | 无返回值 |
| null | - |
| callable | 可执行的回调函数 |
| function | 不一定能执行的方法 |
| self/$this | 当前实例 |
代码举例
2、在方法内的变量定义
@throws
说明
可能会抛出的错误类型 \
格式 @throws [类型] [<描述>]\
例如 @throws Exception
