阅读数:61 评论数:0

一、概述

JSDoc 是一个标记语言，用于为 JavaScript 代码添加文档注释。通过在源代码中嵌入特定的注释，JSDoc 能够自动生成 HTML 文档或其他格式的文档，帮助开发者理解和维护代码。JSDoc 注释通常放在函数、方法、类和模块的定义之前。

• JSDoc 注释必须以 /** 开始，这与普通的多行注释 /* 不同。
• JSDoc 提供了许多标签来描述不同的代码元素，如 @param, @returns, @class, @module, @typedef 等。
• JSDoc 既可以用来生成文档，也可以用来提供给代码编辑器和 IDE，以增强代码提示和类型检查的功能。

二、基本的JSDoc注释示例

1、函数或方法

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

这个例子中，@param 标签描述了函数的参数，而 @returns 标签描述了函数的返回值。

2、类和构造函数

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

  /**
   * 获取点的 X 坐标。
   * @returns {number} 返回点的 X 坐标。
   */
  getX() {
    return this.x;
  }

  /**
   * 获取点的 Y 坐标。
   * @returns {number} 返回点的 Y 坐标。
   */
  getY() {
    return this.y;
  }
}

在类的示例中，@class 标签表示这是一个类的文档，构造函数和方法也被相应地记录了。

3、模块

/**
 * 提供数学相关的工具函数。
 * @module mathUtils
 */

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

在模块的示例中，@module 标签描述了整个文件提供的功能。

4、类型定义

/**
 * @typedef {Object} User
 * @property {number} id 用户的唯一标识符。
 * @property {string} name 用户的姓名。
 * @property {string} [email] 用户的电子邮件地址，可选。
 */

/**
 * 处理用户信息。
 * @param {User} user 用户对象。
 */
function handleUser(user) {
  // ...
}

在类型定义的例子中，@typedef 标签用于自定义复合类型，然后这个类型可以在其他地方被引用。

三、vue3+vite中使用jsdoc