JSDoc

发表于

JSDoc

JSDoc 是一种用于 JavaScript 代码注释的标记语言，它允许您为函数、变量、类等添加详细的文档注释，并提供有关代码结构、类型和用法的信息。JSDoc 的注释可以通过工具生成文档，以便开发人员可以更好地理解和使用代码。

常见场景

JSDoc 最简单的使用方式就是让编辑器自动生成。触发方式很简单：输入/** ，按下 Tab即可自动生成 JSDoc 风格的注释代码。

使用示例

以下是 JSDoc 的一些常见用法和示例：

  1. 原始值注释：

    /**
 * @description 最小值。数字
 * @type {number}
 */
const MIN_VALUE = 1;

// MIN_VALUE

/**
 * @description 临时名称。字符串
 * @type {string}
 */
let tempName = "joe";

// tempName

/**
 * @description 是否显示。布尔
 * @type {boolean}
 */
let isShow = false;

// isShow

/**
 * @description 空对象
 * @type {null}
 */
let hello = null;

// hello

/**
 * @description 未定义
 * @type {undefined}
 */
const last = undefined;

  2. 函数注释：

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

  3. 类注释：

    /**
 * 表示一个图形对象
 * @class
 */
class Shape {
  /**
   * 创建一个图形对象
   * @param {number} width - 图形的宽度
   * @param {number} height - 图形的高度
   */
  constructor(width, height) {
    this.width = width;
    this.height = height;
  }

  /**
   * 计算图形的面积
   * @returns {number} 图形的面积
   */
  getArea() {
    return this.width * this.height;
  }
}

  4. 变量注释：

    @typedef 标签在描述自定义类型时是很有用的，特别是如果你要反复引用它们的时候。这些类型可以在其它标签内使用，如 @type 和 @param。使用 @callback 标签表明回调函数的类型。

    /**
 * 用户信息对象
 * @typedef {object} User
 * @property {string} name - 用户名
 * @property {number} age - 用户年龄
 * @property {string} email - 用户电子邮件
 */

/**
 * 当前登录用户
 * @type {User}
 */
const currentUser = {
  name: "John",
  age: 30,
  email: "john@example.com"
};

  5. 参数注释：

    /**
 * 计算圆的面积
 * @param {number} radius - 圆的半径
 * @param {string} [unit='cm'] - 面积的单位
 * @returns {number} 圆的面积
 */
function calculateCircleArea(radius, unit = "cm") {
  // ...
}

    生成文档

JSDoc 除了规范注释书写规范，还可以一键生成对应的代码文档。其中将注释生成文档贯彻最彻底的就有lodash。

Example

/**
 * Recursively flattens `array`.
 *
 * @static
 * @memberOf _
 * @since 3.0.0
 * @category Array
 * @param {Array} array The array to flatten.
 * @returns {Array} Returns the new flattened array.
 * @example
 *
 * _.flattenDeep([1, [2, [3, [4]], 5]]);
 * // => [1, 2, 3, 4, 5]
 */
function flattenDeep(array) {
  var length = array == null ? 0 : array.length;
  return length ? baseFlatten(array, INFINITY) : [];
}

image-20230625105104415

可以看到文档中所有的内容与注释中的每一条都是一一对应。lodash在打包的时候，使用了docdown将注释转成了markdown文件，然后用这些markdown文件生成了html。

推荐 VSCode 插件

参考网站