js - js 注释 - 《public》

单行注释和多行注释
文档注释

源码中被 JS 引擎忽略的部分就叫做注释，它的作用是对代码进行解释
单行注释：**// ...**、 ...
多行注释：**/* ... */**
文档注释：以 **/**** 开头，然后每行都以 ***** 开始，最后以 ***/** 结束
在某个函数声明的前一行，输入 **/**** 后按下回车就会自动生成文档注释
文档注释的目的：为了让函数调用者更直观地了解到该函数的相关功能，以及调用该函数所需要传入的相关参数

单行注释和多行注释

源码中被 JS 引擎忽略的部分就叫做注释，它的作用是对代码进行解释。JS 提供两种注释的写法：一种是单行注释，用//起头；另一种是多行注释，放在/*和*/之间。

// 这是单行注释
/*
 这是
 多行
 注释
*/

此外，由于历史上 JS 可以兼容 HTML 代码的注释，所以也被视为合法的单行注释。

x = 1; <!-- x = 2;
--> x = 3;

上面代码中，只有x = 1会执行，其他的部分都被注释掉了。

需要注意的是，-->只有在行首，才会被当成单行注释，否则会当作正常的运算。

function countdown(n) {
  while (n --> 0) console.log(n);
}
countdown(3)
// 2
// 1
// 0

上面代码中，n --> 0实际上会当作n-- > 0，因此输出2、1、0。

文档注释

在某个函数声明的前一行，输入 /** 后按下回车就会自动生成文档注释。

文档注释是一种特殊类型的注释，它的目的不仅仅是为了在代码中添加简单的注解或描述。它通常用于描述代码的结构、功能、参数和返回值等，以方便其他开发者理解和使用该代码。此外，很多工具可以解析这些注释来自动生成 API 文档。

在多数编程语言中，文档注释有特定的格式，使得工具能够轻松识别和解析它们。

在 JS 中，JSDoc 是一个流行的工具，用于从注释中生成文档。JSDoc 的注释以 /** 开头，然后每行都以 * 开始，最后以 */ 结束。

以下是 JS 中使用 JSDoc 格式的示例：

/**
 * 计算两个数字的和。
 *
 * @param {number} a - 第一个数。
 * @param {number} b - 第二个数。
 * @returns {number} 两个数的和。
 */
function add(a, b) {
    return a + b;
}

在上面的示例中：

@param 标签描述了函数的参数，包括其类型和名称。
@returns（或 @return）标签描述了函数的返回值。

JSDoc 提供了许多其他标签，如 @class, @constructor, @deprecated, @throws 等，用于描述各种代码特性和行为。

使用文档注释的优点：

提高代码的可读性和可维护性。
使其他开发者更容易理解和使用你的代码。
允许自动生成详细和格式化的 API 文档。