⚡

JSDoc/TSDoc文档生成器 jsdoc-tsdoc

JSDoc/TSDoc文档生成器是一个用于自动化生成、验证和管理JavaScript与TypeScript代码API文档的工具。它通过解析源代码中的JSDoc和TSDoc注释，结合TypeDoc生成结构化的HTML、Markdown或JSON格式的API参考文档。该工具支持文档覆盖率分析、类型对齐验证、自定义标签扩展，并能集成ESLint插件强制执行文档规范，是提升代码可维护性、促进团队协作和保障API文档质量的关键开发辅助技能。关键词：JSDoc文档生成，TypeScript API文档，代码文档自动化，文档覆盖率检查，TypeDoc集成，前端开发工具。

前端开发 0 次安装 0 次浏览 更新于 2/26/2026

name: jsdoc-tsdoc description: 使用JSDoc和TSDoc生成JavaScript和TypeScript文档。解析源代码，生成API文档，验证覆盖率，并与TypeDoc集成以提供全面的开发者文档。 allowed-tools: Read, Write, Edit, Bash, Glob, Grep backlog-id: SK-014 metadata: author: babysitter-sdk version: “1.0.0”

JSDoc/TSDoc 技能

使用行业标准的JSDoc和TSDoc规范，结合TypeDoc集成，生成和验证JavaScript与TypeScript文档。

能力

  • 从JavaScript源代码解析JSDoc注释
  • 从TypeScript源代码解析TSDoc注释
  • 使用TypeDoc生成API文档
  • 验证文档覆盖率和完整性
  • 使用ESLint插件强制执行文档标准
  • 支持自定义JSDoc/TSDoc标签
  • 类型推断和文档对齐
  • 生成多种输出格式（HTML、Markdown、JSON）

使用场景

在以下情况调用此技能：

  • 为JavaScript/TypeScript库和API编写文档
  • 生成API参考文档
  • 审计文档覆盖率
  • 设置自动化文档流水线
  • 验证文档注释是否与实现匹配

输入参数

参数 类型 必填 描述
projectPath string 是 JS/TS项目的根路径
entryPoints array 否 要生成文档的特定文件/目录
outputDir string 否 文档输出目录（默认：docs）
outputFormat string 否 html、markdown、json（默认：html）
includePrivate boolean 否 包含私有成员（默认：false）
coverageThreshold number 否 最低文档覆盖率百分比
customTags array 否 要识别的额外JSDoc/TSDoc标签

输入示例

{
  "projectPath": "./packages/sdk",
  "entryPoints": ["src/index.ts", "src/client.ts"],
  "outputDir": "docs/api",
  "outputFormat": "html",
  "coverageThreshold": 80,
  "customTags": ["@alpha", "@beta", "@experimental"]
}

输出结构

docs/api/
├── index.html           # 文档首页
├── modules.html         # 模块索引
├── classes/
│   ├── Client.html      # 类文档
│   └── Config.html
├── interfaces/
│   ├── Options.html     # 接口文档
│   └── Response.html
├── functions/
│   └── helpers.html     # 函数文档
├── types/
│   └── aliases.html     # 类型别名文档
├── assets/
│   ├── main.js
│   └── style.css
└── coverage.json        # 文档覆盖率报告

JSDoc 注释模式

函数文档

/**
 * 使用API对用户进行身份验证。
 *
 * @param {string} username - 用户名
 * @param {string} password - 密码
 * @returns {Promise<AuthResult>} 包含令牌的身份验证结果
 * @throws {AuthError} 当凭据无效时
 * @example
 * const result = await authenticate('user@example.com', 'password');
 * console.log(result.token);
 *
 * @since 1.0.0
 * @see {@link logout} 用于结束会话
 */
async function authenticate(username, password) {
  // 实现
}

类文档

/**
 * 用于API通信的HTTP客户端。
 *
 * @class
 * @extends EventEmitter
 * @implements {Disposable}
 *
 * @example
 * const client = new ApiClient({ baseUrl: 'https://api.example.com' });
 * const response = await client.get('/users');
 */
class ApiClient extends EventEmitter {
  /**
   * 创建新的API客户端实例。
   *
   * @param {ClientOptions} options - 客户端配置
   * @param {string} options.baseUrl - API请求的基础URL
   * @param {number} [options.timeout=30000] - 请求超时时间（毫秒）
   */
  constructor(options) {
    // 实现
  }

  /**
   * 执行GET请求。
   *
   * @param {string} path - 请求路径
   * @param {RequestOptions} [options] - 附加选项
   * @returns {Promise<Response>} 响应
   */
  async get(path, options) {
    // 实现
  }
}

TSDoc 注释模式

包文档

/**
 * 用于与Example API交互的SDK。
 *
 * @remarks
 * 此包为Example API提供了一个类型安全的客户端。
 * 它支持浏览器和Node.js环境。
 *
 * @packageDocumentation
 */

带重载的函数

/**
 * 从API获取数据。
 *
 * @param url - 端点URL
 * @returns 响应数据
 *
 * @example
 * ```typescript
 * const users = await fetch<User[]>('/api/users');
 * ```
 *
 * @public
 */
export async function fetch<T>(url: string): Promise<T>;

/**
 * 使用自定义选项获取数据。
 *
 * @param url - 端点URL
 * @param options - 请求选项
 * @returns 响应数据
 *
 * @public
 */
export async function fetch<T>(url: string, options: FetchOptions): Promise<T>;

接口文档

/**
 * API客户端的配置选项。
 *
 * @remarks
 * 所有超时值均以毫秒为单位。
 *
 * @example
 * ```typescript
 * const config: ClientConfig = {
 *   baseUrl: 'https://api.example.com',
 *   timeout: 5000,
 *   retries: 3
 * };
 * ```
 *
 * @public
 */
export interface ClientConfig {
  /**
   * 所有API请求的基础URL。
   * @remarks 必须包含协议（https://）
   */
  baseUrl: string;

  /**
   * 请求超时时间（毫秒）。
   * @defaultValue 30000
   */
  timeout?: number;

  /**
   * 失败请求的重试次数。
   * @defaultValue 0
   */
  retries?: number;

  /**
   * 包含在每个请求中的自定义头部。
   * @beta
   */
  headers?: Record<string, string>;
}

TypeDoc 配置

typedoc.json

{
  "$schema": "https://typedoc.org/schema.json",
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "name": "My SDK",
  "readme": "README.md",
  "includeVersion": true,
  "excludePrivate": true,
  "excludeProtected": false,
  "excludeInternal": true,
  "excludeExternals": true,
  "categorizeByGroup": true,
  "categoryOrder": [
    "Client",
    "Configuration",
    "Types",
    "Utilities",
    "*"
  ],
  "navigation": {
    "includeCategories": true,
    "includeGroups": true
  },
  "plugin": [
    "typedoc-plugin-markdown"
  ],
  "theme": "default",
  "validation": {
    "notExported": true,
    "invalidLink": true,
    "notDocumented": false
  }
}

ESLint 文档规则

{
  "plugins": ["jsdoc"],
  "extends": ["plugin:jsdoc/recommended-typescript"],
  "rules": {
    "jsdoc/require-jsdoc": ["warn", {
      "require": {
        "FunctionDeclaration": true,
        "MethodDefinition": true,
        "ClassDeclaration": true,
        "ArrowFunctionExpression": false
      },
      "publicOnly": true
    }],
    "jsdoc/require-description": "warn",
    "jsdoc/require-param-description": "warn",
    "jsdoc/require-returns-description": "warn",
    "jsdoc/check-tag-names": ["error", {
      "definedTags": ["alpha", "beta", "experimental", "internal"]
    }],
    "jsdoc/check-types": "error",
    "jsdoc/no-undefined-types": "error",
    "jsdoc/valid-types": "error"
  }
}

覆盖率分析

覆盖率报告格式

{
  "summary": {
    "documented": 145,
    "undocumented": 23,
    "total": 168,
    "percentage": 86.31
  },
  "byKind": {
    "class": { "documented": 12, "total": 14 },
    "interface": { "documented": 28, "total": 30 },
    "function": { "documented": 45, "total": 52 },
    "method": { "documented": 60, "total": 72 }
  },
  "undocumented": [
    {
      "name": "internalHelper",
      "kind": "function",
      "file": "src/utils/helpers.ts",
      "line": 42
    }
  ],
  "incomplete": [
    {
      "name": "processData",
      "kind": "function",
      "file": "src/core/processor.ts",
      "issues": ["missing @returns", "missing @param for 'options'"]
    }
  ]
}

工作流程

  1. 分析项目 - 扫描TypeScript/JavaScript文件
  2. 解析文档 - 提取JSDoc/TSDoc注释
  3. 验证覆盖率 - 检查是否达到阈值
  4. 类型对齐 - 验证文档是否匹配TypeScript类型
  5. 生成文档 - 运行TypeDoc或JSDoc
  6. 创建覆盖率报告 - 输出覆盖率分析
  7. Lint验证 - 运行ESLint文档规则

依赖项

{
  "devDependencies": {
    "typedoc": "^0.25.0",
    "typedoc-plugin-markdown": "^4.0.0",
    "eslint-plugin-jsdoc": "^48.0.0",
    "@microsoft/tsdoc": "^0.14.0",
    "@microsoft/tsdoc-config": "^0.16.0"
  }
}

最佳实践

  • TypeScript使用TSDoc，JavaScript使用JSDoc
  • 始终为公共API表面编写文档
  • 为复杂函数包含@example
  • 使用@remarks记录实现说明
  • 使用@see链接相关符号
  • 使用@alpha/@beta标记实验性功能
  • 验证类型是否与文档匹配

参考资料

目标流程

  • api-doc-generation.js
  • sdk-doc-generation.js
  • docs-audit.js
  • docs-testing.js