jsdoc

JSDoc - 快速参考

何时不使用此技能

• TypeScript 项目 - 使用 jsdoc-tsdoc 技能了解 TSDoc 和 TypeScript 专用模式
• JSDoc 生成配置 - 此技能用于编写 JSDoc 注释，而非配置工具
• 复杂类型系统 - TypeScript 的类型检查能力优于 JSDoc 注解
• API 文档托管 - 使用文档平台（TypeDoc、Docusaurus 等）

深入了解：使用 mcp__documentation__fetch_docs，并将 technology 设为 jsdoc，获取完整的标签参考、类型表达式和生成选项。

核心模式

函数文档

/**
 * Calculates the sum of two numbers.
 * @param {number} a - The first number
 * @param {number} b - The second number
 * @returns {number} The sum of a and b
 * @example
 * const result = add(2, 3); // 5
 */
function add(a, b) {
  return a + b;
}

对象类型

/**
 * @typedef {Object} User
 * @property {string} id - Unique identifier
 * @property {string} name - Full name
 * @property {string} email - Email address
 * @property {boolean} [active=true] - Optional, defaults to true
 */

/**
 * Creates a new user.
 * @param {User} userData - The user data
 * @returns {Promise<User>} The created user
 */
async function createUser(userData) {
  // ...
}

类文档

/**
 * Represents a user in the system.
 * @class
 */
class User {
  /**
   * Creates a User instance.
   * @param {string} name - User's name
   * @param {string} email - User's email
   */
  constructor(name, email) {
    /** @type {string} */
    this.name = name;
    /** @type {string} */
    this.email = email;
  }

  /**
   * Gets the user's display name.
   * @returns {string} Display name
   */
  getDisplayName() {
    return this.name;
  }
}

回调类型

/**
 * @callback FetchCallback
 * @param {Error|null} error - Error if failed
 * @param {Object} data - Response data
 */

/**
 * Fetches data from the API.
 * @param {string} url - The URL to fetch
 * @param {FetchCallback} callback - Called with the result
 */
function fetchData(url, callback) {
  // ...
}

泛型类型

/**
 * @template T
 * @param {T[]} array - Array of items
 * @returns {T|undefined} First item or undefined
 */
function first(array) {
  return array[0];
}

模块文档

/**
 * @module utils/string
 * @description String utility functions
 */

/**
 * Capitalizes the first letter.
 * @param {string} str - Input string
 * @returns {string} Capitalized string
 */
export function capitalize(str) {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

反模式

反模式	错误原因	正确做法
完全没有文档	没有 IDE 提示，API 难以使用	至少为公共函数和复杂逻辑编写文档
将实现代码复制为注释	没有帮助，还会过时	描述行为，而非实现
缺少 @param 类型	无法进行类型检查或自动补全	始终指定参数类型
文档过时	会造成误导，比没有文档更糟	修改代码时同步更新文档
为显而易见的代码过度编写文档	使代码杂乱，增加维护负担	为复杂逻辑编写文档，略过简单的 getter/setter
用错标签	使工具产生混淆，导致类型错误	类型使用 @typedef，函数使用 @callback
未导入类型	类型引用失效	使用 @typedef {import('./types').Type}
在 TypeScript 中重复提供类型信息	内容冗余，容易失去同步	让 TypeScript 类型自行说明

快速故障排除

问题	诊断	解决方案
IDE 不显示类型提示	JSDoc 注释格式错误或不完整	确保存在 @param {Type} 和 @returns {Type}
VS Code 中出现类型错误	JSDoc 类型语法不正确	使用 TypeScript 风格的类型：{string|null}，而非 {?string}
类型导入失效	@typedef 中的导入路径错误	使用 @typedef {import('./file').TypeName} 并确保路径正确
泛型类型无法使用	@template 用法不当	在参数中使用前先声明 @template T
未生成文档	未配置 JSDoc 工具	使用正确的配置运行 jsdoc -c jsdoc.json
可选参数显示为必填参数	参数名缺少 []	使用 @param {string} [optional] 或 {string=}
类型无法识别	拼写错误或未声明 typedef	使用前通过 @typedef 定义类型
返回类型被忽略	缺少 @returns 标签	始终使用 @returns {Type} 为返回值编写文档

相关技能

• TSDoc/JSDoc
• TypeScript