JSDoc 中的文档注释

在JavaScript开发中，文档注释是非常重要的一部分，它可以帮助其他开发者更好地了解你的代码，并且提升你代码的可读性和可维护性。而JSDoc则是一种用于JavaScript中生成API文档的标准格式，它可以生成具有良好结构和可读性的文档。

注释的语法

JSDoc中的注释采用/**...*/的格式，和普通注释//...或/*...*/的格式略有不同。在/**后可以添加一些标签和描述符来构成完整的注释，例如：

/**
 * This function returns the sum of two numbers.
 * @param {number} num1 - The first number to be added.
 * @param {number} num2 - The second number to be added.
 * @returns {number} The sum of the two numbers.
 */
function add(num1, num2) {
    return num1 + num2;
}

在注释中，可以使用@xxx的标签来表示一些有特殊意义的信息，比如：

• @param用于声明一个方法的参数；
• @returns用于声明一个方法的返回值；
• @class用于声明一个构造函数的类型；
• @constructor用于声明一个构造函数；
• @type指定变量的类型；
• @throws描述一个方法可能抛出的错误；
• @private表示一个方法或属性只在当前文件或模块中可访问；
• 等等。

常用标签示例

@param

用于声明一个方法的参数，可以指定参数的名称、类型和描述信息。例如：

/**
 * Get the user's full name.
 * @param {string} firstName - The user's first name.
 * @param {string} lastName - The user's last name.
 * @returns {string} The user's full name.
 */
function getFullName(firstName, lastName) {
    return `${firstName} ${lastName}`;
}

@returns

用于声明一个方法的返回值，可以指定返回值的类型和描述信息。例如：

/**
 * Returns a random number between 0 and 1.
 * @returns {number} A random number between 0 and 1.
 */
function getRandomNumber() {
    return Math.random();
}

@type

可以用于指定变量的类型。例如：

/** @type {number} */
var num = 123;

@throws

表示一个方法可能抛出的错误，可以指定错误类型和描述信息。例如：

/**
 * Divide two numbers.
 * @param {number} dividend - The number to be divided.
 * @param {number} divisor - The number to divide by.
 * @throws {Error} If the divisor is 0.
 * @returns {number} The result of the division.
 */
function divide(dividend, divisor) {
    if (divisor === 0) {
        throw new Error("Division by zero");
    }
    return dividend / divisor;
}

@private

表示一个方法或属性只在当前文件或模块中可访问。例如：

/**
 * @private
 */
function secretFunction() {
    // ...
}

JSDoc工具

JSDoc不仅是一种注释格式，而且还是一种用于生成API文档的工具。它可以将你的代码中的注释转化为HTML、Markdown等格式的文档，并且提供了丰富的配置选项，可以生成满足不同需求的文档。目前比较流行的JSDoc工具有：

• jsdoc: 最常用的JSDoc生成工具；
• Esdoc: 能够生成更加美观的文档，并且支持ES6、ES7等新特性；
• documentation.js: 生成文档的同时还可以使用它自带的静态分析功能检查代码质量和风格。

总结

JSDoc是一种用于JavaScript中生成API文档的标准格式，它可以生成具有良好结构和可读性的文档。通过使用JSDoc注释，你可以使你的代码更易于理解和维护。在使用JSDoc时，建议使用一些常用的标签和注释风格，并结合生成工具来生成和发布文档，从而提升你代码的可读性和可维护性。