转载： 生成 JavaScript 代码文档的 JSDoc 使用指南

生成 JavaScript 代码文档的 JSDoc 使用指南

原创

osc_3abe2e91

2024/11/14 05:15

https://my.oschina.net/emacs_8492370/blog/16511056

 

1. JSDoc 简介

JSDoc 是一个强大的工具，用于为 JavaScript 代码生成 API 文档。它通过注释来提取信息，并生成 HTML 格式的文档，使得开发者能够轻松地理解和使用代码库。JSDoc 注释使用特殊的标记，这些标记提供了关于函数、方法、类、模块等的详细信息，包括它们的参数、返回值和描述。通过遵循一定的注释规范，JSDoc 能够帮助开发者创建清晰、易于维护的文档。

 

2. JSDoc 的基本语法

JSDoc 的基本语法是通过在代码中添加特殊的注释来实现的。这些注释以 /** */ 包裹，并且包含了一系列的标签（Tags），用于描述代码的功能和用法。

 

2.1 注释结构

下面是一个 JSDoc 注释的基本结构：

/**
 * 描述函数或方法的用途
 * @param {类型} 参数名 - 参数描述
 * @return {类型} 返回值描述
 */
function myFunction() {
    // 函数体
}

 

2.2 常用标签

JSDoc 支持许多标签，以下是一些常用的标签：

• @param：描述函数的参数。

• @return或 @returns：描述函数的返回值。

• @example：提供一个代码示例。

• @see：引用其他相关的文档或代码段。

• @todo：标记待办事项。

 

2.3 注释示例

以下是一个使用 JSDoc 注释的示例：

/**
 * 计算两个数字的和
 * @param {number} a - 第一个加数
 * @param {number} b - 第二个加数
 * @return {number} 两个数字的和
 * @example
 * // 返回 3
 * add(1, 2);
 */
function add(a, b) {
    return a + b;
}

通过使用这些基本语法和标签，开发者可以创建出结构化和信息丰富的文档注释，从而使得代码更加易于理解和维护。

 

3. 注解类型和用途

JSDoc 提供了多种注解类型，这些注解可以帮助开发者定义代码的结构和文档，使得生成的文档更加准确和易于理解。下面是一些常用的注解类型及其用途。

 

3.1 函数和方法的注解

函数和方法是 JavaScript 中的核心组成部分，以下是一些用于描述它们的注解：

• @function：明确指出这是一个函数声明。

• @method：用于描述一个对象的某个方法。

/**
 * @function
 * 连接两个字符串
 * @param {string} str1 - 第一个字符串
 * @param {string} str2 - 第二个字符串
 * @return {string} 连接后的字符串
 */
function concatenate(str1, str2) {
    return str1 + str2;
}
​
/**
 * @method
 * @param {object} obj - 被操作的对象
 * @param {string} key - 要删除的键
 */
function removeKey(obj, key) {
    delete obj[key];
}

 

3.2 类和构造函数的注解

在面向对象编程中，类和构造函数的注解也非常重要：

• @class：用于描述一个类。

• @constructor：用于描述一个类的构造函数。

/**
 * @class
 * 表示一个用户
 */
class User {
    /**
     * @constructor
     * 创建一个新的用户实例
     * @param {string} name - 用户的姓名
     * @param {number} age - 用户的年龄
     */
    constructor(name, age) {
        this.name = name;
        this.age = age;
    }
}

 

3.3 模块和命名空间的注解

模块和命名空间用于组织代码，以下注解有助于描述它们：

• @module：用于描述一个模块。

• @namespace：用于描述一个命名空间。

/**
 * @module
 * 提供数学运算功能
 */
const mathOperations = {
    /**
     * 计算两个数字的和
     * @param {number} a - 第一个数字
     * @param {number} b - 第二个数字
     * @return {number} 两个数字的和
     */
    add(a, b) {
        return a + b;
    }
};
​
/**
 * @namespace
 * 用于处理用户相关的操作
 */
const userOperations = {
    // ... 用户操作相关的方法和属性
};

通过使用这些注解类型，开发者可以清晰地描述代码中的不同元素，使得生成的文档更加详细和有助于其他开发者理解和使用代码库。

 

4. 函数文档编写

编写函数文档是确保代码可读性和可维护性的关键步骤。JSDoc 提供了一套完整的标签，使得为 JavaScript 函数编写文档变得简单而直观。

 

4.1 函数描述

每个函数都应该有一个清晰的描述，说明它的功能和用途。这个描述应该放在 JSDoc 注释的第一行。

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

 

4.2 参数文档

对于函数的每个参数，都应该使用 @param 标签来描述它的类型、名称和作用。

/**
 * 对数组中的每个元素执行一个回调函数
 * @param {Array} array - 要处理的数组
 * @param {Function} callback - 对每个元素执行的回调函数
 * @param {Object} [context] - 回调函数的上下文（可选）
 */
function forEach(array, callback, context) {
    for (let i = 0; i < array.length; i++) {
        callback.call(context, array[i], i, array);
    }
}

 

4.3 返回值文档

使用 @returns 或 @return 标签来描述函数的返回值类型和预期结果。

/**
 * 查找数组中第一个大于给定值的元素
 * @param {Array} array - 要搜索的数组
 * @param {number} value - 比较的值
 * @returns {number|null} 找到的元素，或者如果没有找到符合条件的元素则返回 null
 */
function findGreaterThan(array, value) {
    for (let i = 0; i < array.length; i++) {
        if (array[i] > value) {
            return array[i];
        }
    }
    return null;
}

 

4.4 异常处理文档

如果函数可能抛出异常，应该使用 @throws 或 @exception 标签来描述可能抛出的错误类型。

/*** 解析 JSON 字符串* @param {string} jsonString - 要解析的 JSON 字符串* @returns {Object} 解析后的对象* @throws {SyntaxError} 如果 JSON 字符串格式不正确*/
function parseJson(jsonString) {try {return JSON.parse(jsonString);} catch (error) {throw new SyntaxError('Invalid JSON string');}
}

 

4.5 示例代码

使用 @example 标签提供函数用法的示例代码，这有助于其他开发者更快地理解函数的使用方式。

/*** 将字符串转换为大写* @param {string} str - 要转换的字符串* @returns {string} 转换为大写的字符串* @example* // 返回 'HELLO WORLD'* toUpperCase('Hello World');*/
function toUpperCase(str) {return str.toUpperCase();
}

通过遵循这些指南，开发者可以编写出清晰、完整的函数文档，使得代码库更加易于使用和维护。

 

5. 类和模块的文档编写

在 JavaScript 中，类和模块是组织代码的重要结构。使用 JSDoc 对类和模块进行文档编写，可以帮助开发者更好地理解和使用这些结构。

 

5.1 类的文档编写

类是 JavaScript ES6 引入的一个特性，它提供了一种更清晰和更简洁的构造对象的方式。下面是如何使用 JSDoc 为类编写文档。

 

5.1.1 类描述

在类注释的第一行，应该提供一个简短的描述，说明类的作用。

/*** 表示一个具有位置和速度的物体*/
class PhysicalObject {// ...
}

 

5.1.2 构造函数

类的构造函数通常使用 @constructor 标签进行文档编写。

/*** 创建一个新的 PhysicalObject 实例* @constructor* @param {number} x - 物体的初始 x 坐标* @param {number} y - 物体的初始 y 坐标* @param {number} speed - 物体的速度*/
class PhysicalObject {constructor(x, y, speed) {// ...}// ...
}

 

5.1.3 方法

类的方法应该使用 @method 标签，并且可以包含参数和返回值的描述。

/*** 更新物体的位置* @method* @param {number} deltaX - x 坐标的变化量* @param {number} deltaY - y 坐标的变化量*/
updatePosition(deltaX, deltaY) {// ...
}

 

5.1.4 静态方法

静态方法属于类本身，而不是类的实例。它们同样可以使用 @method 标签，并加上 @static 标签。

/*** 计算两个物体之间的距离* @method* @static* @param {PhysicalObject} obj1 - 第一个物体* @param {PhysicalObject} obj2 - 第二个物体* @returns {number} 两个物体之间的距离*/
static calculateDistance(obj1, obj2) {// ...
}

 

5.2 模块的文档编写

模块是 JavaScript 中用于封装和组织代码的另一个重要概念。在 ES6 中，模块通过 import 和 export 语句来实现。

 

5.2.1 模块描述

使用 @module 标签为模块提供一个描述。

/*** @module physics* 提供物理计算相关的功能*/

 

5.2.2 导出成员

模块中的每个导出成员都应该使用 @export 标签进行标记。

/*** @module physics* @export*/
class PhysicalObject {// ...
}/*** @module physics* @export*/
function calculateDistance(obj1, obj2) {// ...
}

 

5.2.3 导入成员

如果模块需要导入其他模块的成员，可以使用 @import 标签来描述。

/*** @module physics* @import {PhysicalObject} from './PhysicalObject'*/

通过为类和模块编写详细的文档，开发者可以确保代码的可读性和可维护性，同时也使得其他开发者更容易理解和使用这些代码结构。

 

6. JSDoc 标签的高级用法

JSDoc 不仅支持基本的注释和标签，还提供了一系列高级特性，这些特性可以帮助开发者创建更加详细和专业的文档。以下是一些 JSDoc 高级用法的介绍。

 

6.1 类型定义

在 JavaScript 中，类型定义是可选的，但使用 JSDoc 可以明确指定变量、函数参数和返回值的类型，从而提供更强的类型检查和更好的文档。

 

6.1.1 使用 @typedef 定义类型

@typedef 标签允许开发者定义自定义类型，以便在文档中使用。

/*** @typedef {Object} Point* @property {number} x - x 坐标* @property {number} y - y 坐标*//*** @typedef {Object} Size* @property {number} width - 宽度* @property {number} height - 高度*/

 

6.1.2 使用类型定义

定义类型后，可以在注释中使用这些类型。

/*** 计算两点之间的距离* @param {Point} pointA - 第一个点* @param {Point} pointB - 第二个点* @returns {number} 两点之间的距离*/
function calculateDistance(pointA, pointB) {// ...
}

 

6.2 重写和继承

在面向对象编程中，继承和多态是常见的概念。JSDoc 提供了标签来描述这些关系。

 

6.2.1 使用 @augments 或 @extends 标记继承

如果类继承自另一个类，可以使用 @augments 或 @extends 标签。

/*** @class* @augments Animal*/
class Dog extends Animal {// ...
}

 

6.2.2 使用 @inheritdoc 重写父类注释

如果子类的方法重写了父类的方法，并且大部分描述相同，可以使用 @inheritdoc 标签。

/*** @method* @inheritdoc*/
makeSound() {// ...
}

 

6.3 模块化和命名空间

在大型项目中，模块化和命名空间的使用是必不可少的。JSDoc 提供了相应的标签来描述它们。

 

6.3.1 使用 @module 和 @namespace

前面已经介绍了 @module 标签，@namespace 标签用于描述命名空间。

/*** @namespace*/
const mathUtils = {// ...
};

 

6.4 装饰器和元数据

JSDoc 支持装饰器（Decorators）和元数据（Metadata），这些是 TypeScript 等静态类型检查工具中的高级特性。

 

6.4.1 使用 @decorator 标记装饰器

如果函数或类使用了装饰器，可以使用 @decorator 标签。

/*** @decorator*/
function log(target, propertyKey, descriptor) {// ...
}/*** @class* @decorator @log*/
class MyClass {// ...
}

 

6.4.2 使用 @metadata 标记元数据

元数据提供了关于代码的额外信息，可以使用 @metadata 标签。

/*** @class* @metadata {number} 42*/
class MyClass {// ...
}

通过使用这些高级 JSDoc 标签，开发者可以创建出更加精确和详细的代码文档，有助于提高代码的可维护性和可读性。同时，这些信息也可以被一些工具和框架用来进行类型检查、代码分析和生成额外的文档。

 

7. 生成文档的工具和配置

生成 JavaScript 代码文档的工具和配置可以帮助开发者自动化文档的创建过程，确保文档的准确性和一致性。以下是一些常用的工具和配置方法。

 

7.1 JSDoc 工具

JSDoc 是最流行的 JavaScript 文档生成工具之一。它通过分析代码中的注释来生成 HTML 格式的文档。

 

7.1.1 安装 JSDoc

JSDoc 可以通过 npm（Node Package Manager）进行安装：

npm install -g jsdoc

 

7.1.2 基本使用

使用 JSDoc 生成文档的基本命令如下：

jsdoc . -d output

这条命令会处理当前目录下的所有 .js 文件，并将生成的文档输出到 output 目录。

 

7.2 配置文件

JSDoc 支持通过配置文件来定制文档的生成过程。配置文件通常是 JSON 格式，名为 jsdoc.json。

{"source": {"include": ["./src"],"includePattern": ".+\\.js(doc|x)?$","excludePattern": "(^|\\/|\\\\)_"},"opts": {"recurse": true,"destination": "./docs"},"plugins": ["plugins/markdown"],"templates": {"cleverLinks": false,"monospaceLinks": false}
}

这个配置文件指定了源代码的路径、包含和排除的模式、文档的输出目录、插件以及模板的设置。

 

7.3 JSDoc 标签

在代码注释中使用 JSDoc 标签可以定义函数、类、模块等的文档。以下是一些常用的 JSDoc 标签：

• @file：描述整个文件的用途。

• @module：描述一个模块。

• @class：描述一个类。

• @method：描述一个类或对象的方法。

• @param：描述一个函数或方法的参数。

• @return 或 @returns：描述一个函数或方法的返回值。

 

7.4 使用模板

JSDoc 允许使用自定义模板来控制文档的布局和样式。可以通过 templates 配置项来指定自定义模板的路径。

{"templates": {"template": "path/to/custom/template.ejs"}
}

 

7.5 使用插件

JSDoc 支持插件来扩展其功能。插件可以通过 plugins 配置项添加。

{"plugins": ["plugins/markdown"]
}

例如，plugins/markdown 插件允许在文档中使用 Markdown 格式。

通过使用这些工具和配置，开发者可以自动化文档的生成过程，确保文档的及时更新和准确性，同时提高开发效率。

 

8. 总结

通过本文的介绍，我们了解了 JSDoc 的基本概念、语法和高级用法。JSDoc 是一个强大的工具，它不仅能够帮助开发者生成结构化和信息丰富的 API 文档，还能够通过类型定义、装饰器和元数据等高级特性，提供代码的额外信息和增强代码的可读性。以下是本文的要点总结：

• JSDoc 使用特殊的注释标记来提取代码中的信息，并生成 HTML 格式的文档。

• 基本的 JSDoc 注释结构包括描述、参数、返回值等部分。

• JSDoc 支持多种注解类型，包括函数、方法、类、模块等。

• 函数文档编写应包括清晰的描述、参数文档、返回值文档以及示例代码。

• 类和模块的文档编写应描述其用途、构造函数、方法和静态方法等。

• JSDoc 的高级用法包括类型定义、重写和继承、模块化和命名空间、装饰器和元数据等。

• 使用 JSDoc 工具可以自动化文档的生成过程，并通过配置文件进行定制。

• 通过插件和自定义模板，可以进一步扩展 JSDoc 的功能，满足不同项目的文档需求。

总之，JSDoc 是一个不可或缺的工具，它不仅有助于提高代码的可维护性和可读性，还能够提升开发者的工作效率。通过学习和应用 JSDoc，开发者可以更好地管理和分享他们的代码知识。