SuperAPI AI 工具集

jsdoc-tsdoc

编程与开发

查看项目

更新于 11-12 10:09

技能介绍

jsdoc-tsdoc 是一个用于 JavaScript 与 TypeScript 文档生成和校验的技能,遵循业界通用的 JSDoc 与 TSDoc 注释规范,并集成 TypeDoc 输出 API 文档。

一、主要能力

  • 解析 JavaScript 源码中的 JSDoc 注释,解析 TypeScript 源码中的 TSDoc 注释。
  • 使用 TypeDoc 生成 API 文档,支持 HTML、Markdown、JSON 多种输出格式。
  • 校验文档覆盖率与完整性,可设置最低覆盖率阈值。
  • 通过 ESLint 插件执行文档规范检查,支持自定义 JSDoc/TSDoc 标签。
  • 支持类型推断与文档对齐校验,检查注释是否与实现一致。
  • 输出目录结构包含首页、模块索引、类、接口、函数、类型别名页面及覆盖率报告文件。

二、使用方式 该技能提供以下输入参数:

  • projectPath(必填):JS/TS 项目根路径。
  • entryPoints(可选):需要生成文档的特定文件或目录。
  • outputDir(可选):文档输出目录,默认 docs。
  • outputFormat(可选):html、markdown、json,默认 html。
  • includePrivate(可选):是否包含私有成员,默认 false。
  • coverageThreshold(可选):最低文档覆盖率百分比。
  • customTags(可选):需额外识别的 JSDoc/TSDoc 标签。

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

典型流程为:扫描项目中的 TypeScript/JavaScript 文件,提取 JSDoc/TSDoc 注释,按阈值校验覆盖率,验证文档与类型是否对齐,运行 TypeDoc 或 JSDoc 生成文档,输出覆盖率报告,并执行 ESLint 文档规则检查。

三、注释规范示例 JSDoc 支持为函数标注 @param、@returns、@throws、@example、@since、@see 等标签,为类标注 @class、@extends、@implements 等,并在构造函数中说明参数。TSDoc 支持 @remarks、@packageDocumentation、@public、@defaultValue、@beta 等标签,可用于包级文档、函数重载、接口字段说明等场景。文档中给出了上述各场景的完整代码示例。

四、配置与依赖 可通过 typedoc.json 配置入口、输出目录、名称、排除私有/受保护/内部/外部项、分类顺序、导航、插件、主题及校验规则。ESLint 配置可启用 jsdoc 插件与 recommended-typescript 规则集,并设置 require-jsdoc、require-description、require-param-description、require-returns-description、check-tag-names、check-types、no-undefined-types、valid-types 等规则。

开发依赖包括: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。

五、覆盖率分析 覆盖率报告包含汇总信息(已文档化数、未文档化数、总数、百分比)、按类型统计、未文档化条目列表,以及注释不完整条目及其问题说明(如缺少 @returns、缺少某参数说明)。

六、最佳实践与参考 该技能列出多项最佳实践:TypeScript 用 TSDoc、JavaScript 用 JSDoc;始终为公共 API 编写文档;复杂函数附 @example;用 @remarks 记录实现说明;用 @see 关联符号;用 @alpha/@beta 标记实验性功能;校验类型与文档一致。参考资料包括 TypeDoc、TSDoc、JSDoc 与 eslint-plugin-jsdoc 的官方站点与仓库。目标流程包括 api-doc-generation.js、sdk-doc-generation.js、docs-audit.js、docs-testing.js。

七、限制 资料未说明该技能的收费方式、具体支持平台与运行环境的版本要求,也未提供安装命令。