jsdoc-tsdoc

JSDoc 和 TSDoc 文档

完整参考：有关 JavaScript 中的 JSDoc 类型注解、TypeDoc/API Extractor 配置、ESLint 插件设置和 README 模板，请参阅 advanced.md。

深入了解：使用 mcp__documentation__fetch_docs，并指定技术：jsdoc，获取全面的标签参考。

何时不应使用此技能

• 纯 JavaScript 项目 - 使用 jsdoc 技能了解 JavaScript 专用的 JSDoc 模式
• 代码注释（非 API） - TSDoc 用于公共 API 文档，而非内联代码注释
• 从代码自动生成文档 - 直接使用 TypeDoc 或 API Extractor 工具

TSDoc 与 JSDoc

特性	JSDoc	TSDoc
用途	JS 文档和类型	仅 TS 文档
类型注解	@type、@param {Type}	不需要（使用 TS 类型）
标准化	事实标准	正式标准

TypeScript 项目请使用 TSDoc - 类型来自 TypeScript，注释用于描述行为。

函数文档

/**
 * Calculates the total price including tax.
 *
 * @remarks
 * This method uses the default tax rate unless overridden.
 * For international orders, use {@link calculateInternationalPrice} instead.
 *
 * @param basePrice - The pre-tax price in cents
 * @param taxRate - Tax rate as decimal (default: 0.1 for 10%)
 * @returns The total price including tax in cents
 *
 * @throws {@link InvalidPriceError}
 * Thrown if basePrice is negative
 *
 * @example
 * ```typescript
 * const total = calculateTotalPrice(1000, 0.08);
 * console.log(total); // 1080
 * ```
 *
 * @beta
 */
function calculateTotalPrice(basePrice: number, taxRate = 0.1): number {
  if (basePrice < 0) {
    throw new InvalidPriceError('Price cannot be negative');
  }
  return Math.round(basePrice * (1 + taxRate));
}

接口文档

/**
 * Configuration options for the HTTP client.
 *
 * @remarks
 * All timeouts are in milliseconds.
 *
 * @public
 */
interface HttpClientOptions {
  /**
   * Base URL for all requests.
   * @example 'https://api.example.com/v1'
   */
  baseUrl: string;

  /**
   * Request timeout in milliseconds.
   * @defaultValue 30000
   */
  timeout?: number;

  /**
   * Maximum number of retry attempts for failed requests.
   * @defaultValue 3
   */
  maxRetries?: number;
}

所有 TSDoc 标签

块标签

标签	用法
@param name - description	参数说明
@returns description	返回值说明
@throws {Type} description	抛出的异常
@example	使用示例（代码块）
@remarks	扩展说明
@see	相关参考
@deprecated reason	标记为已弃用
@defaultValue value	默认值
@typeParam T - description	泛型类型参数

修饰符标签

标签	含义
@public	属于公共 API
@internal	内部实现
@alpha	早期预览，可能会更改
@beta	正在完善，API 可能会更改
@readonly	只读属性
@override	重写父级

内联标签

标签	用法
{@link Target}	链接到符号
{@link Target | text}	使用自定义文本的链接
{@inheritDoc Parent.method}	继承文档

反模式

反模式	错误原因	正确做法
在 TypeScript 中说明类型	多余，类型已在签名中	描述行为，而非类型
复制粘贴函数签名	没有价值，且会导致不同步	说明用途、边界情况和示例
复杂 API 缺少 @example	用户不知道如何使用	始终包含使用示例
使用 @deprecated 却不说明迁移方式	用户不知道应改用什么	@deprecated Use {@link newFunction} instead
没有 @throws 文档	用户不知道应捕获哪些异常	记录所有抛出的异常

快速故障排除

问题	诊断	解决方案
VS Code 悬停时不显示文档	JSDoc 注释格式错误	确保以 /** 开头，并使用正确的标签语法
eslint-plugin-tsdoc 报错	TSDoc 语法无效	按照 TSDoc 规范修正标签格式
TypeDoc 忽略注释	注释位置错误	将 JSDoc 放在声明正上方
{@link} 无法解析	符号引用不正确	使用完全限定名称或导入路径

官方参考

资源	URL
TSDoc	https://tsdoc.org/
JSDoc	https://jsdoc.app/
TypeDoc	https://typedoc.org/
API Extractor	https://api-extractor.com/