jsDoc 注释规范

二川bro

已于 2025-02-25 11:58:51 修改

阅读量4.6k

点赞数 23

分类专栏：前端文章标签：前端

于 2025-02-20 23:48:56 首次发布

本文链接：https://blog.csdn.net/qq_34419312/article/details/145765550

版权

前端专栏收录该内容

122 篇文章

订阅专栏

jsDoc 注释规范

在这里插入图片描述

定义

jsDoc 是一种用于 JavaScript 代码的注释规范，它通过特定的标签和格式，帮助开发者为代码添加详细的文档说明。这些注释可以被各种工具和编辑器解析，生成 API 文档或提供代码提示，极大地提升了代码的可读性和维护性。接下来，我们将详细介绍 jsDoc 的各种注释类型及其用法。

当然，以下是 jsDoc 注释规范的进阶用法，这些用法可以帮助开发者更精细地描述代码，提高代码的可读性和维护性。

1. 自定义类型定义

使用场景：当代码中存在重复使用的复杂数据结构时，可以使用 @typedef 定义自定义类型，然后在其他地方引用。
示例：

/**
 * 定义一个用户对象类型
 * @typedef {Object} User
 * @property {string} name - 用户名
 * @property {number} age - 用户年龄
 * @property {string} email - 用户邮箱
 */

/**
 * 创建一个新的用户对象
 * @param {User} user - 用户信息
 * @returns {User} 新创建的用户对象
 */
function createUser(user) {
    return {
        ...user,
        createdAt: new Date().toISOString()
    };
}

扩展：自定义类型不仅限于对象，还可以用于函数签名、数组等复杂数据类型。

2. 类型继承

使用场景：当需要描述一个类型继承自另一个类型时，可以使用 @augments 标签。
示例：

/**
 * 定义一个基础对象类型
 * @typedef {Object} BaseObject
 * @property {string} id - 对象ID
 */

/**
 * 定义一个继承自 BaseObject 的扩展对象类型
 * @typedef {Object} ExtendedObject
 * @augments {BaseObject}
 * @property {string} name - 对象名称
 */

/**
 * 创建一个新的扩展对象
 * @param {ExtendedObject} obj - 扩展对象信息
 * @returns {ExtendedObject} 新创建的扩展对象
 */
function createExtendedObject(obj) {
    return {
        ...obj,
        createdAt: new Date().toISOString()
    };
}

扩展：@augments 标签可以用于描述类、接口等复杂类型的继承关系。

3. 回调函数类型定义

使用场景：当需要描述一个回调函数的类型时，可以使用 @callback 标签。
示例：

/**
 * 定义一个处理用户数据的回调函数类型
 * @callback UserDataCallback
 * @param {User} user - 用户对象
 * @param {number} index - 用户索引
 * @param {User[]} users - 用户数组
 */

/**
 * 遍历用户数组并调用回调函数
 * @param {User[]} users - 用户数组
 * @param {UserDataCallback} callback - 回调函数
 */
function processUsers(users, callback) {
    users.forEach(callback);
}

扩展：回调函数类型定义有助于在复杂异步操作中保持代码的清晰和一致性。

4. 枚举类型定义

使用场景：当需要描述一组固定的常量值时，可以使用 @enum 标签。
示例：

/**
 * 定义一个用户状态枚举类型
 * @readonly
 * @enum {string}
 */
const UserStatus = {
    /**
     * 活跃用户
     */
    ACTIVE: 'active',

    /**
     * 禁用用户
     */
    DISABLED: 'disabled',

    /**
     * 删除用户
     */
    DELETED: 'deleted'
};

扩展：@enum 标签可以与 @type 标签结合使用，以描述函数参数或返回值的枚举类型。

5. 泛型类型定义

使用场景：当需要描述一个函数可以处理多种类型的数据时，可以使用 @template 标签。
示例：

/**
 * 创建一个数组的第一个元素
 * @template T
 * @param {T[]} arr - 任意类型的数组
 * @returns {T} 数组的第一个元素
 */
function getFirstElement(arr) {
    return arr[0];
}

扩展：泛型类型定义有助于在 TypeScript 风格的类型系统中提高代码的重用性和灵活性。

6. 使用 Markdown 语法

使用场景：在 jsDoc 注释中使用 Markdown 语法可以增强文档的可读性和格式。
示例：

/**
 * 示例函数，展示 Markdown 语法
 * 
 * 这是一个示例函数的描述。
 * 
 * @param {number} num1 - 第一个加数
 * @param {number} num2 - 第二个加数
 * @returns {number} 两数之和
 * 
 * @example
 * ```javascript
 * console.log(addNumbers(2, 3)); // 输出 5
 * ```
 */
function addNumbers(num1, num2) {
    return num1 + num2;
}

扩展：在 jsDoc 注释中，可以使用标题、列表、代码块等 Markdown 语法元素来增强文档的可读性。

7. 跨文件类型引用

使用场景：当需要在不同文件之间引用自定义类型时，可以使用相对路径或模块名称来引用。
示例：

/**
 * 引用另一个文件中定义的 User 类型
 * @typedef {import('./user.js').User} User
 */

/**
 * 创建一个新的用户对象
 * @param {User} user - 用户信息
 * @returns {User} 新创建的用户对象
 */
function createUser(user) {
    return {
        ...user,
        createdAt: new Date().toISOString()
    };
}

扩展：跨文件类型引用有助于在大型项目中保持类型定义的一致性和可维护性。

8. 使用 JSDoc 插件

使用场景：为了提高代码编写和文档生成的效率，可以使用各种 JSDoc 插件。
示例：
- VS Code 插件：安装 JSDoc 相关的 VS Code 插件，可以提供自动补全、错误提示等功能。
- 文档生成工具：使用如 jsdoc-to-markdown、typedoc 等工具将 JSDoc 注释转换为 Markdown 或 HTML 格式的文档。
扩展：根据项目的具体需求，选择合适的 JSDoc 插件和工具，以提高开发效率。

其他使用介绍

在这里插入图片描述

任务管理与分配：
- 在文档协作的过程中，jocDoc可能提供了任务管理与分配的功能，方便团队成员明确各自的职责和工作进度。
文件版本比较：
- 除了基本的版本控制功能外，jocDoc可能还允许用户比较不同版本的文件，以便快速识别文档内容的变化。
模板库与样式设置：
- 为了提高文档创建的效率，jocDoc可能内置了多种模板库和样式设置选项，用户可以根据需要选择合适的模板或样式来快速创建文档。
搜索与过滤：
- 在文档数量较多时，jocDoc可能提供了搜索与过滤功能，方便用户快速找到所需的文档。
通知与提醒：
- 对于文档的更新、评论或任务分配等关键事件，jocDoc可能通过邮件、短信或应用内通知的方式提醒相关用户。
第三方集成：
- jocDoc可能支持与其他工具或服务的集成，如项目管理软件、云存储服务、即时通讯工具等，以便用户在一个平台上完成更多工作。
数据导出与备份：
- 为了方便数据的迁移和备份，jocDoc可能提供了数据导出功能，允许用户将文档导出为常见的文件格式（如PDF、DOCX等），并可能支持将数据备份到本地或云端存储服务。
权限管理与安全性：
- 在文档协作的过程中，jocDoc可能提供了细粒度的权限管理功能，允许用户设置不同成员的访问和编辑权限。同时，为了保障文档的安全性，jocDoc可能采用了数据加密、访问控制等安全措施。