Javascript 文档注释

OrzMiku / 2023-08-23 / 原文

在JavaScript中，通常使用JSDoc格式的注释，以/**开始，以*/结束。

/**
 * 加法函数
 * @param {Number} a
 * @param {Number} b
 * @returns Number
 */
function add(a, b) {
  return a + b;
}

使用文档注释的好处就是，提高代码的可读性，更重要的是IDE可以识别这种注释，会有提示。

下面来介绍具体的一些使用方法。

可选参数

/**
 * @param {Number?} index 
 */

/**
 * @param {?Number} index 
 */

/**
 * @param {Number=} index 
 */

任意参数类型

/**
 * @param {*} index 
 */

/**
 * @param {Any} index 
 */

多种参数类型

/**
 * @param {Number|String} index 
 */

描述函数的参数和返回值：

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

描述函数的副作用和异常

/**
 * 向控制台输出一条消息。
 *
 * @param {string} message - 要输出的消息
 * @throws {Error} 如果消息为空则抛出错误
 */
function logMessage(message) {
    if (!message) {
        throw new Error("消息不能为空");
    }
    console.log(message);
}

描述对象的属性

/**
 * 表示一个人的对象。
 *
 * @typedef {Object} Person
 * @property {string} name - 姓名
 * @property {number} age - 年龄
 */

/**
 * @type {Person}
 */
const person = {
    name: "Alice",
    age: 30
};

描述类及其成员

/**
 * 表示一个汽车类。
 *
 * @class
 */
class Car {
    /**
     * 创建一个汽车实例。
     *
     * @constructor
     * @param {string} make - 制造商
     * @param {string} model - 型号
     */
    constructor(make, model) {
        this.make = make;
        this.model = model;
    }
    
    /**
     * 获取完整的车辆信息。
     *
     * @returns {string} 车辆信息字符串
     */
    getFullInfo() {
        return `${this.make} ${this.model}`;
    }
}

描述命名空间或模块

/**
 * 一个用于数学计算的工具模块。
 *
 * @namespace
 */
const MathUtils = {
    /**
     * 计算两个数字的乘积。
     *
     * @memberof MathUtils
     * @param {number} a - 第一个数字
     * @param {number} b - 第二个数字
     * @returns {number} 两个数字的乘积
     */
    multiply(a, b) {
        return a * b;
    }
};

描述回调函数

/**
 * 从数组中过滤出满足条件的元素。
 *
 * @param {Array} array - 待过滤的数组
 * @param {function(element: *, index: number): boolean} callback - 过滤条件回调
 * @returns {Array} 过滤后的数组
 */
function filterArray(array, callback) {
    return array.filter(callback);
}

常用标签

标签	用法与示例	含义和说明
`@param`	`@param {类型} 参数名 - 参数说明`	描述函数参数的类型和含义。
`@returns`	`@returns {类型} 返回值说明`	描述函数的返回值类型和含义。
`@throws`	`@throws {类型} 错误说明`	描述函数可能抛出的异常类型和含义。
`@typedef`	`@typedef {类型} 别名`	定义一个类型别名，通常用于描述对象、类或函数的返回类型。
`@class`	`@class`	标识一个类的开始。
`@constructor`	`@constructor`	描述类的构造函数。
`@property`	`@property {类型} 属性名 - 属性说明`	描述对象或类的属性，包括类型和含义。
`@namespace`	`@namespace`	标识一个命名空间或模块的开始。
`@enum`	`@enum {类型} 枚举名 - 枚举说明`	描述一个枚举类型，包括枚举值和含义。
`@callback`	`@callback {类型} 回调名 - 回调说明`	描述一个回调函数类型。
`@private`	`@private`	标识注释的内容为私有成员，通常用于指定只在内部使用的部分。
`@public`	`@public`	标识注释的内容为公共成员，通常用于指定可以从外部访问的部分。
`@protected`	`@protected`	标识注释的内容为受保护成员，通常用于指定只允许派生类或子类访问的部分。
`@inheritdoc`	`@inheritdoc`	表示继承自父类或接口的文档注释，用于减少重复注释。
`@example`	`@example 代码示例`	提供一个代码示例，说明如何使用函数或方法。
`@description`	`@description 描述内容`	提供更详细的描述文本，用于补充其他标签无法涵盖的内容。
`@deprecated`	`@deprecated 原因`	标识被弃用的函数、属性或类，同时提供弃用的原因。
`@ignore`	`@ignore`	忽略注释的内容，使其不会被文档生成工具处理。