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

Salamander 发布于2019-08-23 18:17 / 435人阅读

摘要：表示该函数接受可变数量的参数，并指定一个类型的参数一个可选参数可选参数，默认值指示参数是可选的。一个注释块中您可以包含多个标签。

简介

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

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

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

项目工程地址 : 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 [ ]

别名

@class

标签效果

@deprecated

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

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

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

语法

@deprecated []

描述

如果被标记的方法只是因为被其他新方法代替而被废弃，可以结合@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类型 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

标签效果

动图演示内容

通过@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 {}

@throws {} 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

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

专线服务服务器托管每一位 JSer 大家需要掌握的深度学习需要掌握的

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/104960.html

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

摘要：简介注释标签在代码注释中的作用非常大，但是可能很多同学在平常开发中会忽略这些标签的作用，所以我这边特地整理一些常用的注释标记，通过图文展现形式，希望能帮助你能更好理解每个注释标签的作用或许你离漂亮的代码，就差一个标签项目工程地址被此标记的简介注释标签在代码注释中的作用非常大，但是可能很多同学在平常开发中会忽略这些标签的作用，所以我这边特地整理一些常用的注释标记，通过图文展现形式，希...

quietin 2019-07-01 14:03 评论0 收藏0
通用 CSS 笔记、建议与指导

摘要：如下区块标题前缀可以让我们使用命令查找标题名时将搜索范围限制在区块标题中。在参与规模庞大、历时漫长且参与人数众多的项目时，所有开发者遵守如下规则极为重要：保持 CSS 易于维护保持代码清晰易懂保持 CSS 的可拓展性为了实现这一目标，我们要采用诸多方法。本文档第一部分将探讨语法、格式以及分析 CSS 结构；第二部分将围绕方法论、思维框架以及编写与规划 CSS 的看法...

lushan 2019-08-28 17:58 评论0 收藏0
如何成为一位「不那么差」的程序员

摘要：能理解线程模型多线程优缺点以及如何避免。多线程的出现主要是为了提高的利用率任务的执行效率。所以要考虑清楚是否真的需要多线程。这一块的内容可以然我们知道写大牛处理并发的思路，对我们自己编写高质量的多线程程序也有很多帮助。 showImg(https://segmentfault.com/img/remote/1460000015980196?w=2048&h=1363); 前言已经记不...

caspar 2019-08-19 10:56 评论0 收藏0
几个前端工程师应当掌握的“词语”

摘要：学堂码匠各类前端术语知多少有不少前端开发工程师，可能并不清楚下面的部分词语，但是在实战中其实都在使用着它们。 HTML5学堂-码匠：W3C、BFC、FOUC、Hack、GPU、Sprite、UA……各类前端术语知多少？有不少前端开发工程师，可能并不清楚下面的部分词语，但是在实战中其实都在使用着它们。明确一下这些词语和概念没有什么不好~一方面能够让自己能够更专业的谈论知识，另一方面，在...

shusen 2019-08-01 17:29 评论0 收藏0
几个前端工程师应当掌握的“词语”

摘要：学堂码匠各类前端术语知多少有不少前端开发工程师，可能并不清楚下面的部分词语，但是在实战中其实都在使用着它们。 HTML5学堂-码匠：W3C、BFC、FOUC、Hack、GPU、Sprite、UA……各类前端术语知多少？有不少前端开发工程师，可能并不清楚下面的部分词语，但是在实战中其实都在使用着它们。明确一下这些词语和概念没有什么不好~一方面能够让自己能够更专业的谈论知识，另一方面，在...

Bowman_han 2019-08-20 18:55 评论0 收藏0