注释标记是什么?

我们在平常写代码或看别人写的代码时, 在方法的注释中经常会有这样的注释:

/**
* @param $num
* @return array
*/

上面的@param @return 就是注释标记

注释标记用于生成文档, param指明需要接收的参数, return指明返回值

在使用 phpDocumentor 等工具生成文档时, 会识别相关注释, 而且IDE也会识别, 在编码的过程中会给出提示.

PHP注释标记总结

  • @api: 提供给第三方使用的接口
  • @author: 标明作者
  • @param: 参数
  • @return: 返回值
  • @todo: 待办
  • @version: 版本号
  • @inheritdoc: 文档继承
  • @property: 类属性
  • @property-read: 只读属性
  • @property-write: 只写属性
  • @const: 常量
  • @deprecated: 过期方法
  • @example: 示例
  • @final: 标识类是终态, 禁止派生
  • @global: 指明引用的全局变量
  • @static: 标识类、方法、属性是静态的
  • @ignore: 忽略
  • @internal: 限内部使用
  • @license: 协议
  • @link: 链接,引用文档等
  • @see: 与 link 类似, 可以访问内部方法或类
  • @method: 方法
  • @package: 命名空间
  • @since: 从指定版本开始的变动
  • @throws: 抛出异常
  • @uses: 使用
  • @var: 变量
  • @copyright: 版权声明

@author

标明作者

/*
* @author Georgie <227040015@qq.com>
* Georgie: 作者名
* 227040015@qq.com: 邮箱
*/

@copyright

版权声明

@copyright [描述]

@see

此链接不光可以跳转到外部链接, 还可以跳转到内部的指定方法等, 如: class::method

@see [url | 内部方法] [描述]

@deprecated

标明方法是不建议使用的、已过期的或将要删除的

/*
* 语法:
* @deprecated [版本号] [描述]
* 例:
* @see Class::test()
* @deprecated 2.0 将被弃用,请使用test方法
*/

@inheritdoc

会继承父类文档, 且子类出现冲突文档时重写父类文档

@internal

标识此类或方法仅限当前文件使用

@description

标识一般描述

/*
* @description [描述]
*/

@link

指明外部链接, 必须给出完整url

@link [url] [描述]

@var

定义数据的类型

@var [类型] [变量名] [描述]

/**
 * 可以指定变量的类型
 * @var array 名称列表
 * 也可以指定变量名, 指定变量时数组或空
 * @var array|null $nameList 名称列表
 */

类型列表如下:

  • string: 字符串
  • int/integer: 数字
  • boolean/bool: 布尔
  • float/double: 浮点
  • object: 对象实例
  • TestClass: 指定类
  • mixed: 任意类型
  • array: 数组
  • TestClass[]: 指定类型数组
  • resource: 文件资源
  • void: 无
  • null:
  • callable: 回调函数
  • function: 方法
  • self/$this: 当前实例

@throws

抛出异常

@throws [类型] [描述]

@method

类注释, 标明该类可以调用的方法, 可以令IDE自动提示等

/**
* @method string test(int num) 测试方法
*/

@param

标识参数信息, 类型可参考 @var

@param [类型] [名称] [描述]

@property

类属性, 指明可以直接访问与修改的类属性, 私有属性需要通过 __get __set 魔术方法设置与访问, 类型参考 @var

@property [类型] [名称] [描述]

@property-read

类属性, 指明只读的类属性, 私有属性需要通过 __get 魔术方法访问, 类型参考 @var

@property-write

类属性, 指明只写的类属性, 私有属性需要通过 __set 魔术方法设置, 类型参考 @var

@return

标识方法的返回值, 类型参考 @var

@return [类型] [描述]

@global

标明用到的全局变量

@global [类型] [名称] [描述]

@ignore

标明生成文档是忽略的值

@users

标明引入使用到了哪些值

/**
* @users Class::$num 使用此属性计数
*/

GeorgieのBlog,分享生活的点点滴滴,分享代码干货