JSDoc #

什么是 JSDoc？ #

JSDoc 是一种用于 JavaScript 的文档注释标准，通过特殊的注释格式为代码添加类型信息和文档说明。它可以帮助开发者生成 API 文档、提供更好的 IDE 支持，并在不使用 TypeScript 的情况下获得类型检查能力。

核心定位 #

text

┌─────────────────────────────────────────────────────────────┐
│                         JSDoc                                │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  文档生成    │  │  类型注解    │  │  IDE 支持   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  代码提示    │  │  类型检查    │  │  标准规范   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

为什么使用 JSDoc？ #

优势 #

text

✅ 零成本类型支持
   - 无需编译步骤
   - 纯 JavaScript 项目可用
   - 渐进式类型化

✅ 文档即代码
   - 文档与代码同步
   - 自动生成 API 文档
   - 易于维护

✅ IDE 智能提示
   - VS Code 原生支持
   - 参数提示
   - 自动补全

✅ 类型安全
   - 配合 TypeScript 检查
   - 早期错误发现
   - 重构支持

快速开始 #

基本语法 #

javascript

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

常用标签 #

标签	用途	示例
@param	参数说明	@param {string} name - 用户名
@returns	返回值说明	@returns {boolean} 是否成功
@type	类型定义	@type
@typedef	自定义类型	@typedef {Object} User
@callback	回调类型	@callback EventHandler
@example	使用示例	@example func()

文档结构 #

text

JSDoc 文档
├── 基础入门
│   ├── JSDoc 简介
│   ├── 基础语法
│   └── 配置文件
│
├── 标签详解
│   ├── 常用标签
│   └── 类型定义
│
└── 高级用法
    ├── 复杂类型
    └── 模块文档

与 TypeScript 配合 #

JSDoc 可以与 TypeScript 完美配合，在 JavaScript 文件中获得类型检查：

javascript

// @ts-check

/**
 * @typedef {Object} User
 * @property {number} id - 用户ID
 * @property {string} name - 用户名
 * @property {string} [email] - 邮箱（可选）
 */

/**
 * 创建用户
 * @param {string} name - 用户名
 * @returns {User} 用户对象
 */
function createUser(name) {
  return { id: Date.now(), name };
}

学习路径 #

text

入门阶段
├── JSDoc 简介
├── 基础语法
└── 配置文件

进阶阶段
├── 常用标签
└── 类型定义

高级阶段
├── 复杂类型
└── 与 TypeScript 配合

下一步 #

现在你已经了解了 JSDoc 的基本概念，接下来学习 JSDoc 简介，深入了解 JSDoc 的详细用法！