Javascript——JSDoc 风格的注释语法 为参数添加说明

使用 JSDoc 为 JavaScript 代码编写文档

JavaScript 由于其动态性和灵活性，有时会让代码难以理解，特别是在团队协作或者项目规模增大的情况下。
这就是为什么使用一种称为 JSDoc 的标记语言来撰写可读的文档变得至关重要。

什么是 JSDoc？

JSDoc 是一种用于 JavaScript 的注释语法，它可以让开发者在源码旁添加信息性注释。
这些注释之后可以被转换成漂亮的 HTML 文档页面，或者直接在支持 JSDoc 的编辑器（如 Visual Studio Code）中显示以帮助代码解析。

JSDoc 注释的基本格式

JSDoc 注释以 /** 开始，并在每一行前加上 *，以 */ 结束。在这些注释块内，您可以使用一系列的标签（tags）来提供不同类型的信息。

/**
 * 这里是对函数或方法的简短描述。
 *
 * @param {参数类型} 参数名 - 参数的描述。
 * @returns {返回值类型} 对返回值的描述。
 */

何时使用 JSDoc？

JSDoc 应当用于以下情况：

• 在定义函数或方法时，描述它们的用途、参数和返回值。
• 在创建类或构造函数时，解释其职责和如何使用。
• 在定义变量（特别是全局变量或复杂对象）时，说明它们的目的和期望的结构。

如何使用 JSDoc？

让我们看一个具体的例子，来了解如何使用 JSDoc 来描述一个简单的函数：

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

在这个例子中，我们使用了 @param 标签来描述函数的参数以及 @returns（或 @return）标签来描述函数的返回值。

创建类的文档

当使用 JSDoc 来描述一个类时，您可以提供关于构造函数以及类的公共方法和属性的信息。

/**
 * 表示一个点的类。
 * 
 * @class
 */
class Point {
  /**
   * 创建一个点实例。
   *
   * @param {number} x - 点的 X 坐标。
   * @param {number} y - 点的 Y 坐标。
   */
  constructor(x, y) {
    this.x = x;
    this.y = y;
  }

  /**
   * 获取点的坐标。
   *
   * @returns {Object} 包含 X 和 Y 坐标的对象。
   */
  getCoordinates() {
    return { x: this.x, y: this.y };
  }
}

在这个例子中，除了函数和参数的描述外，我们还使用了 @class 标签来明确表示这是一个类的定义。

生成文档网页

要从 JSDoc 注释生成文档网页，您需要安装 JSDoc 工具。通常，这可以通过 npm 安装：

npm install -g jsdoc

然后，您可以运行 jsdoc 命令并指定包含 JSDoc 注释的文件或目录：

jsdoc yourJavaScriptFile.js

JSDoc 将会为您的代码生成一个 HTML 文档，通常在 out 文件夹中。

结论

JSDoc 是 JavaScript 开发人员的宝贵工具，它不仅能帮助其他开发人员快速理解您的代码，还能生成易于浏览的 API 文档。通过在编写代码的同时积极地使用 JSDoc，您可以提高代码的可维护性和可读性。