JavaScript-注释规范：jsdoc / 生成 API 文档或提供代码补全、类型检查

一、理解 JSDoc

JSDoc 是一种基于 JavaScript 的注释规范，它允许开发者为 JavaScript 代码添加文档注释。这些注释可以被解析工具（如 IDE 插件、文档生成器等）读取，以生成 API 文档或提供代码补全、类型检查等功能。在前端开发中，JSDoc 是一种非常有用的工具，可以提高代码的可读性和可维护性。

二、全局安装

npm install -g jsdoc

三、JSDoc 用法示例

3.1、函数注释

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

3.2、类和类成员注释

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

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

    /**
     * 计算矩形的周长
     * @returns {number} - 矩形的周长
     */
    getPerimeter() {
        return 2 * (this.width + this.height);
    }
}

3.3、类型别名和枚举注释

/**
 * 方向枚举
 * @typedef {Object} Direction
 * @property {string} up - 向上
 * @property {string} down - 向下
 * @property {string} left - 向左
 * @property {string} right - 向右
 */

/**
 * 玩家对象
 * @typedef {Object} Player
 * @property {string} name - 玩家名称
 * @property {number} score - 玩家得分
 * @property {Direction} direction - 玩家方向
 */

// 使用类型别名
/**
 * 创建一个玩家对象
 * @param {Player} player - 玩家对象
 * @returns {void}
 */
function createPlayer(player) {
    console.log(`Player ${player.name} is moving ${player.direction.up}`);
}

3.4、使用 @param 和 @returns 注释

@param 用于描述函数的参数，包括参数的类型和描述。

@returns 用于描述函数的返回值，包括返回值的类型和描述。

3.5、使用 @type 注释变量类型

/**
 * 玩家分数
 * @type {number}
 */
let playerScore = 0;

3.6、使用 @callback 注释回调函数

/**
 * 执行异步操作，完成后调用回调函数
 * @param {function(Error, string)} callback - 回调函数，接收错误对象和结果字符串
 * @returns {void}
 */
function fetchData(callback) {
    // 模拟异步操作
    setTimeout(() => {
        callback(null, 'Data fetched successfully');
    }, 1000);
}

3.7、生成文档

JSDoc 注释本身不会改变代码的运行，但你可以使用 JSDoc 工具来解析这些注释并生成 HTML 或 Markdown 格式的 API 文档。例如，你可以通过命令行运行 jsdoc 命令来生成文档：

jsdoc your-file.js
或
jsdoc your_code_file.js -d output_directory

这将读取 your_code_file.js 中的 JSDoc 注释，并将生成的文档输出到 output_directory 目录中。

四、欢迎交流指正

参考链接 

JSDoc 入门 | JSDoc中文文档 | JSDoc中文网