TypeScript 的 tsc 配合 JSDoc 可同时生成 .d.ts 和文档，关键需配置 "declaration": true 和 "allowJs": true；JSDoc 类型注释必须用 {} 包裹，如 @param {string} name；typedoc 是首选文档工具，需指向 .d.ts 或 .ts 入口并显式指定 tsconfig。
直接用 TypeScript 的 tsc 配合 JSDoc 注释，就能同时产出类型声明文件（.d.ts）和可读文档，但前提是配置必须对齐——否则要么文档空、要么类型丢失、要么生成失败。
tsconfig.json 必须启用 declaration + allowJs
很多项目卡在这一步：JSDoc 注释写得再全，tsc 不生成声明文件，后续工具（比如 typedoc 或 apidoc）就无从解析类型。关键配置项只有两个：
-
"declaration": true—— 启用 .d.ts 生成 -
"allowJs": true—— 让 tsc 能扫描 .js 文件里的 JSDoc
如果项目混用 .ts 和 .js（比如渐进式迁移），还要加 "checkJs": false（只生成不校验 JS），否则 JSDoc 类型写错会直接报编译错误，阻断文档流程。
JSDoc 类型注释必须带 { } 包裹
TypeScript 只识别标准 JSDoc 类型语法，常见错误是漏掉花括号或写错格式：
- ✅ 正确：
@param {string} name、@returns {Promise} - ❌ 错误：
@param string name（缺{}）、@returns User（没包裹）、@returns {User | null}（TS 不支持管道符，得写{User | null}但需确保User已定义）
特别注意泛型和联合类型：用 {Array，不用 {string[]}；用 {(id: number) => void}，不能省略参数名和类型。
typedoc 是首选，不是 jsdoc
jsdoc 本身不理解 TypeScript 类型系统，它只能把 JSDoc 文本原样搬进 HTML；而 typedoc 直接调用 TS 编译器 API，能真正解析接口、类型别名、泛型约束，并自动生成属性表格、继承关系图、模块依赖树。
- 安装：
npm install --save-dev typedoc - 入口配置：
"entryPoints": ["src/index.ts"]，不要指向 .js 文件（即使有 JSDoc） - 关键开关：
"tsconfig": "./tsconfig.json"必须显式指定，否则 typedoc 会 fallback 到默认配置，导致类型丢失
如果你的项目里 src/ 下全是 .js + JSDoc，那就先用 tsc --allowJs --declaration --emitDeclarationOnly --outDir types 生成 .d.ts，再让 typedoc 读取 types/ 目录。
apidoc 需要额外开启 TypeScript 支持
apidoc 默认只认 @api 系列标签，对 @param {User} 这类类型注释视而不见。想让它把 JSDoc 类型也塞进文档，必须在 apidoc.json 里打开 TS 解析开关：
"typescript": { "enabled": true, "tsconfig": "./tsconfig.json" }-
"input"路径必须包含 .ts 文件（哪怕只是空壳），否则 apidoc 不触发 TS 模式 - 它不会自动提取
interface User { name: string }定义，但能识别@param {User} user并把User当作文本链接——前提是User在当前作用域里被import过
容易被忽略的是：apidoc 的 TS 支持只解析类型引用，不校验类型是否存在。如果写了个不存在的 {FooBar}，它照样生成文档，但链接点不开。
