开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载TypeScript 编译器自身会解释一批 JSDoc 风格标签如type、typedef、satisfies用于在 JavaScript 代码中表达类型信息。TypeDoc 为了与之兼容在默认标签清单中收纳了 8 个此类标签作为 Block 标签它们被正确解析、不会触发未知标签警告但 TypeDoc 不为其附加任何文档行为并会在生成文档时将其移除。本文以 site/tags/typescript.md 为主线结合 TypeDoc 源码解析这 8 个标签的识别与剔除机制并说明typedef/callback在 JS 项目中驱动文档生成的特殊规则与实战写法。为什么需要TypeScript 兼容标签TypeDoc 的标签体系主要继承自 TSDoc 标准中说明任何未被识别的标签都会触发警告TypeDoc 虽然仍会借助上下文线索继续解析注释但会提示用户。问题在于TypeScript 编译器而非 TypeDoc自身就定义了另一批 JSDoc 标签。在开启checkJs的 JavaScript 项目中type、typedef、satisfies等标签承载着真实的类型语义是 TS 类型检查体系的一部分。如果 TypeDoc 不识别它们就会在转换大量 JS 项目时产生成堆警告而如果为它们附加文档行为又可能与 TypeDoc 从代码结构推导出的信息冲突或重复。TypeDoc 的取舍是在默认 Block 标签清单中收录这些标签以保证兼容不报警告但明确不为它们附加任何行为。原文档对此的表述是TypeDoc does not attach any behavior to their presence, and will remove them from the generated documentation.TypeDoc 不为它们的存在附加任何行为并会将其从生成的文档中移除。8 个 TypeScript 兼容 Block 标签总览以下标签均属于Block 标签Block 标签定义即关联整段后续文本、用于划分文档区域的标签标签TypeScript 中的含义TypeDoc 的行为type为 JS 变量/成员标注类型解析后从文档中移除typedef在 JS 注释中定义类型别名解析JS 项目中会被转换为类型别名/接口反射见下文callback在 JS 注释中定义回调函数类型解析同上extends标注继承关系等价于 JSDoc 的extends解析后从文档中移除augmentsextends的别名解析后从文档中移除satisfies对应 TS 4.9 的satisfies运算符在 JS 注释中约束表达式满足某类型解析后从文档中移除yields标注生成器函数yield产出的值类型类似returns之于普通函数解析后从文档中移除jsx标注 JSX 工厂函数对应--jsxFactory解析后从文档中移除需要强调的是不附加行为的准确含义这些标签出现的注释会被 TypeDoc 正常解析注释文本、param等其余内容仍会进入文档只是这几个标签本身不会在生成的文档页面中渲染出来也不会影响反射reflection的归类或排序——与group、category、hidden这类有实际行为的标签形成鲜明对比。逐标签解析它们在 TypeScript 中的真实语义typeJS 中为变量标注类型type是 JSDoc 中最基础的标签在 JS 文件中为变量、属性标注类型例如/** type {string[]} */ const items []; /** type {import(./module).Options} */ const opts loadOptions();类型信息由 TypeScript 编译器消费TypeDoc 无需在文档中重复渲染因此解析后直接剔除。typedef/callbackJS 项目中定义类型与回调typedef在 JS 注释中定义类型别名callback定义回调函数签名。它们不仅是兼容标签在 JS 项目中还承担着 TypeDoc 文档生成的实际输入职责——详见后文实战一节。extends/augments继承标注extendsJSDoc 中写作extends用于在 JS 中标注类继承关系augments是它的别名。在 src/lib/utils/options/tsdoc-defaults.ts 的默认 Block 标签清单中可以看到这一别名关系extends, augments, // Alias for extends继承信息由 TypeScript 编译器直接推导TypeDoc 同样不需要依赖注释中的标注。satisfiessatisfies 运算符的 JSDoc 形态TypeScript 4.9 引入satisfies运算符后其 JSDoc 支持也同步落地在 JS 注释中使用satisfies可约束表达式同时保持推导出的精确类型不同于type的强制断言。例如/** * satisfies {Recordstring, string} */ export const config { port: 8080 };TypeDoc 将其作为兼容标签收纳不附加文档行为。yields生成器函数的产出类型yields之于生成器函数相当于returns之于普通函数。它属于 TSDoc 定义的 Block 标签 之外 TypeDoc 额外收录的兼容项。jsxJSX 工厂标注jsx用于 JS 文件中标注 JSX 工厂对应 TypeScript 的jsxFactory编译选项同样只服务于编译期无需进入文档。底层机制从识别到剔除的源码链路1. 默认标签清单全部 8 个标签收录于 blockTags所有 Block 标签的默认值集中定义在 src/lib/utils/options/tsdoc-defaults.ts。逐一核对可确认 8 个兼容标签全部在列jsx属于 TSDoc 标准 Block 标签L7callbackL20、extendsL25、augmentsL26、yieldsL27、satisfiesL38、typeL43、typedefL44为 TypeDoc 额外收录。这份清单经由 options/sources/typedoc.ts 注册为--blockTags选项的默认值因此这些标签在解析时天然被认识不会触发未识别标签警告。2. NEVER_RENDERED真正剔除的执行者标签的移除逻辑位于 src/lib/converter/plugins/CommentPlugin.ts。源码中定义了一个NEVER_RENDERED常量其注释解释了设计意图These tags are not useful to display in the generated documentation. They should be ignored when parsing comments. Any relevant type information (for JS users) will be consumed by TypeScript and need not be preserved in the comment.这些标签对展示在生成的文档中没有用处。解析注释时应忽略它们。对 JS 用户而言任何相关的类型信息都会被 TypeScript 消费无需保留在注释中。该列表包含augments、callback、extends、type、typedef、jsx以及class、constructor、enum。随后在removeExcludedTags方法L547-L556中对注释执行comment.removeTags(tag)与comment.removeModifier(tag)将标签连同其修饰器标记一并从注释对象中移除最终不再进入渲染管线。从源码结构看satisfies与yields虽不在NEVER_RENDERED列表中但同样位列默认 Block 标签清单且 TypeDoc 源码中不存在针对二者的任何行为处理分支——这与文档所述不附加任何行为一致它们至多作为普通 Block 标签文本存在不会产生语义影响。3. 解析器侧callback / typedef 的专门识别注释解析器 src/lib/converter/comments/parser.ts 对callback、typedef做了专门识别。这是因为二者的注释结构特殊TypeScript 允许在同一个注释块内声明多个typedef/callback编译器返回的注释内容会因此剔除所有非花括号包裹的标签。TypeDoc 的解析器必须针对这种结构做特判才能正确提取注释内容。typedef / callback 注释中的特殊规则内联语法充当修饰器在 site/tags.md 的 TypeScript in JavaScript 一节 中TypeDoc 文档特别说明了一个易踩坑的规则如果项目用 TypeScript 对 JavaScript 做类型检查TypeDoc 会收录typedef和callback定义的类型别名与接口但由于 TS 允许一个注释块内含多个typedef声明这类注释中无法再直接使用 Block/Modifier 标签作为特例TypeDoc 允许使用内联标签语法且无内容的修饰器标签将其识别为修饰器。例如下面的注释会被解析为Foo 带有一个interface修饰器/** * typedef {{ x: string }} Foo Foo docs * {interface} */这种写法在 src/lib/converter/jsdoc.ts 中得到了印证convertJsDocAlias会检查comment?.hasModifier(interface)若命中则走convertJsDocAliasAsInterface分支把该typedef生成为Interface 反射而非 TypeAlias 反射。实战在 JS 项目中用 typedef / callback 驱动文档虽然这 8 个标签对 TS 项目无附加行为但在 JavaScript 项目中typedef与callback恰恰是 TypeDoc 生成类型文档的主要来源。TypeDoc 为此提供了专门的 JSDoc 转换器 src/lib/converter/jsdoc.ts其中convertJsDocAliasL64-L119与convertJsDocCallbackL121-L139会把注释中的类型定义转换为 TypeAlias/Interface 反射。TypeDoc 自带的测试用例 src/test/converter/js/index.js 完整展示了各类写法及其预期输出见同目录 specs.json/** typedef {Object} AlsoInterfaceIsh docs for interface * property {string} foo docs for property */带property的typedef会被生成为接口interface不带属性声明的typedef如typedef {string | number} UnionType则生成类型别名callback结合param、returns生成回调签名类型/** * template T * callback IdentityFn * param {T} data * return {T} the data */要点归纳让 TS 检查 JS需在tsconfig.json中开启checkJs或allowJscheckJsTypeDoc 才会沿 TypeScript 的类型系统拾取这些 JSDoc 类型对象形态用propertytypedef {object} X配合property/prop会被转为接口反射适合文档化对象结构纯类型别名不加属性typedef {string | number} T直接生成类型别名泛型用template在注释内通过template T声明类型参数修饰器走内联语法在typedef/callback注释块内如需interface等修饰器使用{interface}这种无内容内联写法。与自定义标签、--blockTags 选项的关系这 8 个标签的兼容身份来自它们是--blockTags的默认值而该选项本身是可配置的。在 标签总览 中 TypeDoc 说明了两种扩展标签的方式tsdoc.json在tsconfig.json同级放置tsdoc.json通过tagDefinitions声明自定义标签本仓库根目录即提供了 tsdoc.json 作为 TypeDoc 自身的 TSDoc 配置参考--blockTags / --inlineTags / --modifierTags 选项推荐使用 JS 配置如typedoc.config.mjs导入OptionDefaults.blockTags后展开追加避免手写覆盖丢失默认清单。需要警惕的是默认清单中包含这 8 个兼容标签正是因为多收一个兼容标签、少一次警告的容错策略。若在自定义配置中直接覆盖blockTags而非展开追加这些标签将不再被识别注释中出现时又会回到未知标签警告的老路。因此除非刻意收紧标签体系否则应始终基于OptionDefaults扩展。总结TypeDoc 为兼容 TypeScript 编译器自有的 JSDoc 标签体系将type、typedef、callback、extends、augments、satisfies、yields、jsx共 8 个标签收录为默认 Block 标签解析时不附加任何文档行为多数标签在渲染前被NEVER_RENDERED机制从注释中移除类型信息由 TypeScript 编译器消费TypeDoc 只负责让注释解析安静地通过这一设计在 src/lib/converter/plugins/CommentPlugin.ts 的源码注释中有明确表述唯一的例外是typedef/callback在开启类型检查的 JS 项目中它们会通过 src/lib/converter/jsdoc.ts 被转换为真实的类型反射成为 JS 项目文档的重要组成部分且其注释块内需使用内联修饰器语法自定义blockTags时应基于OptionDefaults.blockTags扩展避免误删这些兼容标签而重新引入警告。如需进一步了解 TypeDoc 标签体系的整体设计可继续阅读标签总览、Block 标签示例如 remarks以及文档注释Doc Comments概览。赞分享开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载相关推荐TypeDoc override 标签TSDoc 兼容标签的解析机制与排除控制TypeDoc override 标签TSDoc 兼容标签的解析机制与排除控制 本篇技术指南聚焦 TypeDoc 的 override 文档标签说明它作开发工具文档TypeDoc 标签体系详解TypeScript 项目文档注释中的 Block、Modifier 与 Inline 标签TypeDoc 标签体系详解TypeScript 项目文档注释中的 Block、Modifier 与 Inline 标签 TypeDoc 允许开发者在 JSD开发工具文档TypeDoc example 标签详解JSDoc 与 TSDoc 双兼容的代码示例写法TypeDoc example 标签详解JSDoc 与 TSDoc 双兼容的代码示例写法 TypeDoc 的 example 块标签用于在 API 文档中开发工具文档上一篇Windows风扇控制终极指南Fan Control完全配置与使用教程下一篇CANN ops-nn 张量列表标量幂运算算子aclnnForeachPowScalarAndTensor 接口解析与实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考