每一位JSer都应当掌握的注释标记
简介
注释标签在代码注释中的作用非常大，但是可能很多同学在平常开发中会忽略这些标签的作用，所以我这边特地整理一些常用的注释标记，通过图文展现形式，希望能帮助你能更好理解每个注释标签的作用.
想必掌握这些注释标签之后，不光对您今后的自己代码编写，还是阅读优秀源码，都会带来一定帮助.
或许你离漂亮的代码，就差一个标签^_^
项目工程地址 : 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
您的支持是我更新的最大动力~~