每个PHPer都应当掌握的注释标记

6,271 阅读3分钟

简介

注释标签在代码注释中的作用非常大,但是可能很多同学在平常开发中会忽略这些标签的作用,所以我这边特地整理一些常用的注释标记,通过图文展现形式,希望能帮助你能更好理解每个注释标签的作用.

或许你离漂亮的代码,就差一个标签^_^

项目工程地址 : github.com/yinggaozhen…


@deprecated

@deprecated : 被此标记的函数或者成员方法表示下个版本将会被废弃,告知适用方不再推荐使用此方法.

详细代码演示 : github.com/yinggaozhen…

语法

@deprecated [<version>] [<description>]

描述

  • @deprecated可以填写一个版本号,版本号的规则同@version
  • 如果被标记的方法只是因为被其他新方法代替而被废弃,可以结合@see来表示被代替的方法

标签效果

demo.jpg


@inheritdoc

@inheritdoc : 文档继承,会继承父类的文档注释.

详细代码演示 : github.com/yinggaozhen…

语法

@inheritDoc

描述

  • @inheritDoc会继承父类的所有文档注释.在继承之后可以对指定字段进行重写

标签效果

1.直接继承

demo1.jpg

2.继承重写

demo2.jpg


@internal

@internal : 被此标签标记的内部类/方法,作用范围只能限于当前文件,外部文件不可调用.

详细代码演示 : github.com/yinggaozhen…

语法

@internal [description]

使用场景

此标签通常可使用在单元测试中,比如在单元测试中定义了一个测试用的类,可对此测试类添加@internal标签,这样别人在正常逻辑中万一不小心错误引用了测试类,在IDE的帮助下,可以第一时间得到反馈.

标签效果

demo.jpg


@link

@link : 此标签可以引导你到指定的外部跳转链接.

详细代码演示 : github.com/yinggaozhen…

语法

@link [URI] [<description>]

描述

该标签只有1个跳转选项

和@see的区别

- @see @link
外部链接
内部程序 X

@see

@see : 此标签可以引导你到指定的外部跳转链接/内部程序.

详细代码演示 : github.com/yinggaozhen…

语法

@see [URI | FQSEN] [<description>]

描述

该标签可以有两个跳转选项

  • @外部跳转链接 : 必须是满足RFC2396的跳转链接,例如github.com/yinggaozhen
  • @内部程序链接 : 可以跳转到制定的类/方法/变量,如class::method

和@link的区别

- @see @link
外部链接
内部程序 X

@var

@var : 定义一个数据的类型.

详细代码演示 : github.com/yinggaozhen…

语法

@var [Type] [$element_name] [<description>]

变量列表

变量类型 说明
string 字符串
integer/int number/int类型
boolean/bool false/true
float/double number/浮点数
object 对象实例
specifiedType 指定类
mixed 任意类型
array/specifiedType[] 数组,可以指定成指定类型的数组
resource 文件资源类型
void 无返回值
null -
callable 可执行的回调函数
function 不一定能执行的方法
self/$this 当前实例

标签效果

实现@var可以有两种使用方法

1.在类成员变量中定义,不需要指定变量名称

demo.jpg

2.直接给具体变量定义,需要指定变量名称

demo.jpg


@throws

@throws : 抛出一个异常,告诉调用方需要做好处理异常相关工作.

详细代码演示 : github.com/yinggaozhen…

语法

@throws [Type] [<description>]

标签效果

demo.jpg


最后

文章篇幅有限,这里列举了一部分标签,更多标签可以通过以下工程地址

项目工程地址 : github.com/yinggaozhen…

标签会不定期持续更新,欢迎各位star & fork

您的支持是我更新的最大动力~~