注释标签在代码注释中的作用非常大,但是可能很多同学在平常开发中会忽略这些标签的作用,所以我这边特地整理一些常用的注释标记,通过图文展现形式,希望能帮助你能更好理解每个注释标签的作用.
想必掌握这些注释标签之后,不光对您今后的自己代码编写,还是阅读优秀源码,都会带来一定帮助.
或许你离漂亮的代码,就差一个标签^_^
项目工程地址
:
github.com/yinggaozhen…
Egg源码中大量注释标记
@abstract
@abstract
: 被此标记标识的成员方法,必须在继承成员的对象中实现。
详细代码演示
:
github.com/yinggaozhen…
此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用
别名 :
@virtual
该成员(一般指父类的方法)必须在继承的子类中实现(或重写)。
@abstract
@constructor
@constructor
: 被
constructor
标记的方法会被视为构造函数.
详细代码演示
:
github.com/yinggaozhen…
此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用
@class [<type> <name>]
@class
@deprecated
@deprecated
: 被此标记的函数或者成员方法表示下个版本将会被废弃,告知适用方不再推荐使用此方法.
详细代码演示
:
github.com/yinggaozhen…
此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用
@deprecated [<some text>]
如果被标记的方法只是因为被其他新方法代替而被废弃,可以结合
@see
来表示被代替的方法
搭配@see
@inheritdoc
@inheritdoc
: 指明这个标识应继承其父类的文档。
详细代码演示
:
github.com/yinggaozhen…
此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用
@inheritdoc
@member
@member
: 可以为某个成员变量定义类型.可以选择性为成员变量指定名称。
详细代码演示
:
github.com/yinggaozhen…
此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用
@member [<type>] [<name>]
type类型
type基础类型
Variable number of that type
此函数接受可变数量的数值参数。
@param {...number} num
表示该函数接受可变数量的参数,并指定一个类型的参数
Optional parameter
一个可选参数
@param {number} [foo]
@param {number} [foo=1] 可选参数,默认值=1
指示参数是可选的。当使用JSDoc的语法表示可选参数时,你还可以指明参数的默认值。
@param
@param
: 标签提供了对某个函数的参数的各项说明,包括参数名、参数数据类型、描述等。
详细代码演示
:
github.com/yinggaozhen…
此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用
@param {type} {name} {desc}
@param
标签要求您指定要描述参数的名称。您还可以包含参数的数据类型,使用大括号括起来,和参数的描述。
类型表达式可以有以下几种表达形式
标识符的namepath(例如,myNamespace.MyClass)
一个内置的javascript类型(如string, number)
以上两种的组合
函数入参定义类型
函数的入参是一个对象,可以定义入参对象属性类型
@see
: 此标签表示可以参考另一个标识符的说明文档,或者一个外部资源。
详细代码演示
:
github.com/yinggaozhen…
此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用
@see <namepath>
@see <url>
动图演示内容
通过@see标记的{Foo#bar},可以进行跳转到Foo类中的bar成员属性中
通过点击@see标记的外部链接
www.baidu.com
,可跳转到浏览器中查看
@throws
@throws
: 说明可能会被抛出什么样的错误。
详细代码演示
:
github.com/yinggaozhen…
此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用
@throws free-form description
@throws {<type>}
@throws {<type>} free-form description
@throws
标签可以让你描述函数可能会抛出的错误。一个注释块中您可以包含多个@throws标签。
Example
* @description 抛出指定错误类型的错误
* @throws {SQLException}
function
tagThrows1
(
)
{
* @throws SQL Execute failed
function
tagThrows2
(
)
{
* @throws {SQLException} SQL Execute failed.
function
tagThrows3
(
)
{
文章篇幅有限,这里列举了一部分标签,更多标签可以通过以下工程地址
项目工程地址
:
github.com/yinggaozhen…
标签会不定期持续更新,欢迎各位
star & fork
您的支持是我更新的最大动力~~
练习时长两周半的Go练习生 @ DIDI
29.4k
粉丝