Document TypeScript APIs with JSDoc — TypeScript JSDoc 文档化技能

技能简介

AdamManuel-dev/typescript-jsdoc 是面向 TypeScript 项目的高质量 JSDoc 注释编写技能。它解决了 TypeScript 团队最常见的痛点——注释与类型重复、缺失行为说明、文档与实现脱节。该技能让 Claude、Codex、Claude Code 等 AI 助手能够针对导出 API、复杂行为、内部辅助函数等不同场景生成准确、简洁、聚焦意图的 JSDoc，覆盖 @param、@throws、@example、@deprecated、@template 等核心标签，让文档真正成为开发者理解代码意图的第一入口。

核心能力

• 解释 TypeScript 函数、类、服务的核心 JSDoc 语法与最佳实践。
• 明确指出何时应当为公共 API、内部辅助函数、复杂行为撰写注释。
• 提供 @param、@returns、@throws、@example、@deprecated、@template 等标签的实战示例。
• 指导嵌套对象参数与泛型函数的注释写法，避免签名过于冗长。
• 识别与 TypeScript 类型重复的冗余注释，自动建议删除或精简。
• 设计符合项目风格的 JSDoc 规范，支持团队级文档标准落地。

安装配置

1. 通过 npx 一键安装：npx skillstore add adammanuel-dev/typescript-jsdoc。
2. 启用后，Claude / Codex / Claude Code 在处理 TypeScript 文件时即可自动应用。
3. 项目需启用 TypeScript ≥4.x，建议配置 tsconfig.json 的 noImplicitAny 与 strict 选项以最大化技能价值。
4. 可选：配合 typedoc 或 api-extractor 自动生成渲染文档，效果更佳。

使用步骤

1. 确定注释对象：先判断目标代码是公共 API、内部辅助还是复杂行为，决定注释详细程度。
2. 撰写基础 JSDoc：包含目的说明、参数含义、返回值、关键边界条件与错误抛出场景。
3. 补充示例代码：在 @example 中给出最小可运行调用，覆盖成功路径与典型异常。
4. 标注废弃与模板：对旧 API 用 @deprecated 提示替代方案，对泛型函数补充 @template。
5. 审查冗余内容：删除单纯重复 TypeScript 类型、未补充上下文的注释。
6. 建立团队规范：依据项目特点制定必备标签、可选标签、反模式与评审标准。

适用场景

• 为即将发布的 TypeScript 公共库撰写完整 JSDoc，提升 SDK 可用性。
• 为大型应用中的复杂模块（重试、缓存、副作用）补充行为说明。
• 在 Code Review 中统一团队的注释风格与详细度。
• 评审并清理历史代码中重复类型、无效信息的冗余注释。
• 设计 TypeScript 项目的 JSDoc 编写规范，纳入工程流程。

适用人群

• 维护 TypeScript 公共库与 SDK 的开源贡献者。
• 中大型前端 / 后端团队的 Tech Lead，希望统一注释风格。
• 正在构建类型安全 API 的全栈工程师。
• 关注代码可维护性、需要降低新成员上手成本的项目负责人。
• 准备将 TypeScript 项目文档化的技术作者与 DevRel。

工作原理

该技能以 JSDoc 标准与 TypeScript 类型系统为蓝本，内置大量"何时该写 / 何时不该写"的判断规则。AI 助手在生成注释时会先分析符号的导出级别、调用复杂度、潜在副作用，再决定 JSDoc 的详细程度与必选标签。技能不直接修改文件，所有改动由 AI 在用户确认后落到工程目录，保证开发流程的可控性。技能同时支持自定义项目规范，用户可以在 prompt 中指定必备标签与反模式约束。

官方链接

• Skillstore 主页：https://skillstore.io/skills/adammanuel-dev-typescript-jsdoc
• 仓库地址：https://github.com/AdamManuel-dev/claude-code-ext/tree/main/skills/jsdoc
• Manifest 接口：https://skillstore.io/api/skills/adammanuel-dev-typescript-jsdoc/manifest