简介

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

想必掌握这些注释标签之后，不光对您今后的自己代码编写，还是阅读优秀源码，都会带来一定帮助.

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

项目工程地址 : https://github.com/yinggaozhen/doc-demo/tree/master/javascript

Egg源码中大量注释标记

常用标签

@abstract

@abstract : 被此标记标识的成员方法，必须在继承成员的对象中实现。

详细代码演示 : https://github.com/yinggaozhen/doc-demo/tree/master/javascript/abstract

此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用

别名 : @virtual

概述

该成员（一般指父类的方法）必须在继承的子类中实现（或重写）。

语法

@abstract

标签效果

@constructor

@constructor : 被constructor标记的方法会被视为构造函数.

详细代码演示 : https://github.com/yinggaozhen/doc-demo/tree/master/javascript/constructor

此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用

语法

@class [<type> <name>]

别名

@class

标签效果

@deprecated

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

详细代码演示 : https://github.com/yinggaozhen/doc-demo/tree/master/javascript/deprecated

此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用

语法

@deprecated [<some text>]

描述

如果被标记的方法只是因为被其他新方法代替而被废弃，可以结合@see来表示被代替的方法

标签效果

废弃标签

搭配@see

@inheritdoc

@inheritdoc : 指明这个标识应继承其父类的文档。

详细代码演示 : https://github.com/yinggaozhen/doc-demo/tree/master/javascript/inheritdoc

此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用

语法

@inheritdoc

标签效果

@member

@member : 可以为某个成员变量定义类型.可以选择性为成员变量指定名称。

详细代码演示 : https://github.com/yinggaozhen/doc-demo/tree/master/javascript/member

此标签推荐使用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 : 标签提供了对某个函数的参数的各项说明，包括参数名、参数数据类型、描述等。

详细代码演示 : https://github.com/yinggaozhen/doc-demo/tree/master/javascript/param

此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用

语法

@param {type} {name} {desc}

概述

@param标签要求您指定要描述参数的名称。您还可以包含参数的数据类型，使用大括号括起来，和参数的描述。

类型表达式可以有以下几种表达形式

标识符的namepath(例如，myNamespace.MyClass)
一个内置的javascript类型(如string, number)
以上两种的组合

标签效果

函数入参定义类型

函数的入参是一个对象，可以定义入参对象属性类型

@see

@see : 此标签表示可以参考另一个标识符的说明文档，或者一个外部资源。

详细代码演示 : https://github.com/yinggaozhen/doc-demo/tree/master/javascript/see

此标签推荐使用PhpStorm/WebStorm进行阅读,可以能直观体现标签的作用

语法

@see <namepath>
@see <url>

标签效果

动图演示内容

通过@see标记的{Foo#bar}，可以进行跳转到Foo类中的bar成员属性中
通过点击@see标记的外部链接http://www.baidu.com，可跳转到浏览器中查看

@throws

@throws : 说明可能会被抛出什么样的错误。

详细代码演示 : https://github.com/yinggaozhen/doc-demo/tree/master/javascript/throws

此标签推荐使用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() {
}

最后

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

项目工程地址 : https://github.com/yinggaozhen/doc-demo/tree/master/javascript

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

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