JavaScript-你了解文档注释吗？

前言

我们打代码的时候，都知道写注释是一个很好的习惯，可提高代码的可读性，大大减少了项目的维护难度。那么，你了解注释嘛?了解文档注释嘛？

注释的类型

单行注释

这是最常见的注释方式，可以用于解释某段代码的功能或用途。在这种注释中，注释内容在双斜杠（//）后面，直到这行结束。例如：

// 这是一个单行注释
for(let i=0;i<5;i++){
    console.log(i)
}

快捷键 Ctrl+/

多行注释

这种注释用于解释一段代码或者阻止一段代码运行 。在JavaScript中，多行注释以/*开始，以*/结束。例如：

/*
这是一个多行注释，可以用于解释一段复杂的代码
*/
let x = 5;
let y = 6;
let z = x + y;

快捷键 Alt+shift+A

文件注释

通常放在文件的开头，用于解释整个文件的目的和功能，以及作者和创建日期等信息。这种注释通常也是多行注释。

/*
* 文件名: example.js
* 作者: your name
* 创建日期: 2023/8/1
* 描述: 这是一个示例JavaScript文件
*/

文档注释

在JavaScript中，通常使用JSDoc格式的注释，以/**开始，以*/结束。例如：

/**
 * 这是一个文档注释的例子
 * @param {number} a - 第一个数字
 * @param {number} b - 第二个数字
 * @returns {number} 两个数字的和
 */
function add(a, b) {
    return a + b;
}


/** 这是a */
const a = 6,
  /** 这是b */
  b = 7;

const c = add(a, b);

个人觉得文档注释的最大好处在于IDE识别，可以给提示

当你在声明变量或者方法时，通过文档注释，你可以在其他地方使用的时候获取到注释 ，提高代码的可读性，对开发效率也有提高！试想，当你写了一个公共方法，在业务页面中引用，突然对传参或者这个方法怎么用想不起来了，这时候文档注释就可以给你很好的提示！

对象参数属性描述

描述一个对象参数的属性

/**
 * @param {Object} person - 人对象
 * @param {string} person.name - The name of the person.
 * @param {string} person.age - The person's age.
 */

如果person 是一个数组

/**
 * @param {Object[]} person - 人对象数组
 * @param {string} person[].name - The name of an person.
 * @param {string} person[].age - The person's age.
 */

可选参数

使用？或者=

同时，当你给参数添加默认值时，会自动变成可选参数

/**
 * @param {Number?} index 
 */

/**
 * @param {?Number} index 
 */
/**
 * @param {Number=} index 
 */

多种类型参数

使用|

/**
 * @param {Number|String} index 
 */

任何类型

使用* 或者Any

/**
 * @param {*} index 
 */
/**
 * @param {Any} index 
 */

常用标签

标签	描述
@module	标明当前文件模块，在这个文件中的所有成员将被默认为属于此模块，除非另外标明
@submodule	针对模块的划分，处于@module之下
@class	标示一个类或者一个函数
@constructor	当使用对象字面量形式定义类时，可使用此标签标明其构造函数
@callback	标明此方法是一个回调函数
@event	标明一个可触发的事件函数，一个典型的事件是由对象定义的一组属性来表示。
@constant	常量标识
@member/@var	记录一个基本数据类型的成员变量
@method	标记一个方法或函数
@param	标记方法参数及参数类型
@property	标明一个对象的属性
@readonly	只读
@return	标明返回值、类型及描述
@type	描述代码变量的类型
@description	如果在注释开始描述可省略此标签
@enum	一个类中属性的类型相同时，使用此标签标明
@example	示例，代码可自动高亮
@exports	标识此对象将会被导出到外部调用
@ignore	忽略此注释块
@link	内联标签，创建一个链接，如 {@link http://github.com Github}
@name	指定一段代码的名称，强制 JSDoc 使用此名称，而不是代码里的名称
@namespace	指定一个变量为命名空间变量
@static	描述一个不需实例即可使用的变量
@summary	对描述信息的短的概述
@throws	描述方法将会出现的错误和异常
@todo	描述函数的功能或任务
@tutorial	插入一个指向向导教程的链接

VSCode快捷键设置

但如果每次都输入 /** */ 这样就很麻烦了，这时候我们可以借助VSCode的快捷键设置。帮助我们快速输入

设置-Preference-Config User Snippets

输入

{"快速注释": {
"scope": "",
"prefix": "xs",
"body": [" /** $1 */ "],
"description": "快速注释"
}}

注释插件

1. JavaScript Comment Snippet

   可以快速生成代码注释。

   输入/// 即可快速生成，并有常用标签的快捷输入键

总结

对一些方法和变量，相对于单行或多行注释，优势在于：

1. 易于维护：文档注释可以提供更详细、更完整的信息，使得其他开发者更容易理解代码的功能和用法，从而更容易进行维护和更新。
2. 自动生成文档：一些编程语言（如Java和Python）具有生成文档的工具，它们可以自动从源代码中的文档注释生成HTML或其他格式的文档，大大提高了文档生成和维护的效率。
3. 提高代码可读性：文档注释通常包含函数或类的详细描述，包括参数、返回值、异常等信息，这可以大大提高代码的可读性。
4. 支持开发工具：许多IDE（如Eclipse和IntelliJ IDEA）可以识别文档注释，并在代码提示、错误检查等功能中使用这些信息。
5. 便于代码审查：在进行代码审查时，文档注释可以帮助审查者更快地理解代码的功能和设计，从而提高审查的效率。

参考

1. JavaScript代码注释范例 - 知乎 (zhihu.com)
2. Js注释 - S&L·chuck - 博客园 (cnblogs.com)