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

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

原创

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，开发者可以更好地管理和分享他们的代码知识。

posted @ 2025-02-21 13:39 高树岭软件实验室阅读(10) 评论(0) 编辑收藏举报

刷新页面返回顶部

登录后才能查看或发表评论，立即登录或者逛逛博客园首页

相关博文：

· 关于YAML的校核 Yamale

· typescript仅仅是为了给javascript增加类型而对java的一个仿制吗

· JSDoc语法规范

· 基于VS Code的JSDoc的使用指南

· JSDoc 讲解

阅读排行：
· 震惊！C++程序真的从main开始吗？99%的程序员都答错了
· 别再用vector＜bool＞了！Google高级工程师：这可能是STL最大的设计失误
· 单元测试从入门到精通
· 【硬核科普】Trae如何「偷看」你的代码？零基础破解AI编程运行原理
· 上周热点回顾（3.3-3.9）

随笔分类

软件分享(2)

高石的编程杂谈

关于编程的一些看法，偶感，希望有益

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