每一位 JSer 都应当掌握的注释标记

简介

注释标签在代码注释中的做用很是大，可是可能不少同窗在日常开发中会忽略这些标签的做用，因此我这边特意整理一些经常使用的注释标记，经过图文展示形式，但愿能帮助你能更好理解每一个注释标签的做用.

想必掌握这些注释标签以后，不光对您从此的本身代码编写，仍是阅读优秀源码，都会带来必定帮助.

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

项目工程地址 : 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进行阅读,能够能直观体现标签的做用

别名

@var

语法

@member [<type>] [<name>]

type类型

type基础类型

类型	说明
string	字符串
Array or Type[]	数组
number	数字
Object	对象
Class	自定义的类名
Function	方法类型
null	-
*	任意类型

type格式

类型名	语法示例	描述
Symbol name	{boolean} {myNamespace.MyClass}	指定符号的名称。 若是标识符已经被文档化，JSDoc将建立一个连接到该标识符的文档
Multiple types	{number|boolean} 表示数字或布尔	这意味着值多是几种类型中的一种，并用|分隔类型的完整列表。
Arrays	{Array.string} or string[] 表示字符串数组	-
Objects	{name: string, age : number} or Object	-
Nullable type	一个数字或null {?number}	指明类型为指定的类型，或者为null。
Non-nullable type	一个数字，可是绝对不会是null {!number}	指明类型为指定的类型，可是绝对不会是null。
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

@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

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