开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载本篇技术指南围绕 TypeDoc 文档标签中的author标签展开它属于 TypeDoc 的哪类标签、默认配置中如何声明、解析与渲染的底层链路是怎样的以及如何在生成的 API 文档中正确记录作者信息。读完本文你不仅能在项目注释中规范使用author记录方法作者还能理解 TypeDoc 对“无行为块标签”无副作用标签的解析与渲染机制并知道如何通过blockTags配置扩展类似的自定义标签。1. 标签定位author 是无行为的块标签Block TagTypeDoc 的官方标签文档 site/tags/author.md 对author的定义非常明确Tag KindBlock块标签属于 Tags 总览 中列出的 Block Tags 类别author可用于记录某个方法或任意被文档化的声明的作者TypeDoc 不为该标签附加任何特殊行为attaches no behavior它只是被解析为Comment上的一个块标签并在生成的文档中渲染为注释内的一个段落/小节。这与hidden会移除 Reflection、group会改变文档组织结构等有明确行为的标签形成对比。author属于“纯记录型”标签TypeDoc 只做解析与渲染不改变任何转换逻辑。TypeDoc 标签总览页 site/tags.md 也指出TypeDoc 支持的标签集中包含了不少“无关联行为”的 JSDoc 常用标签目的是减少用户为常见标签单独做自定义配置的负担——author正是这类被内置支持、开箱即用的标签。2. 默认配置author 在哪里被声明为合法标签author被内置为合法块标签的事实可以在源码中得到直接印证。TypeDoc 的默认标签清单定义在 src/lib/utils/options/tsdoc-defaults.tsexport const blockTags [ ...tsdocBlockTags, author, callback, category, // ... 其余块标签 ] as const;其中tsdocBlockTags是 TSDoc 标准定义的部分defaultValue、deprecated、example、param等而author、callback、since、license等则是 TypeDoc 在 TSDoc 标准之外额外内置的 JSDoc 常用标签。这份清单通过 src/lib/utils/options/defaults.ts 导出为blockTags选项的默认值export const blockTags: readonly TagString[] TagDefaults.blockTags;这个默认值会作为blockTags选项TagString[]类型见 src/lib/utils/options/declaration.ts提供给用户也就是说你可以像其他选项一样通过配置文件覆盖或扩展它。3. 解析阶段未识别标签会告警author 不会在 site/tags.md 中有一个重要约定未被识别的标签会产生 warning但 TypeDoc 仍会解析整个注释并依靠上下文线索推断标签类型。解析逻辑位于 src/lib/converter/comments/parser.ts。当解析器遇到一个块标签时会检查它是否在config.blockTags中if (!config.blockTags.has(blockTag.text)) { warning(i18n.unknown_block_tag_0(blockTag.text), blockTag); }也就是说如果你写了一个既不在blockTags、也没在tsdoc.json/ 配置中声明的标签会收到Encountered an unknown block tag ...警告。由于author在默认blockTags清单里第 2 节所以使用它不会触发任何 unknown block tag 警告这是它被内置的直接收益。解析器随后会把标签内容读取为一个CommentTag对于author这类普通标签走通用分支读取其后的文本内容作为该标签的contentMarkdown 显示部分。4. 行为验证单元测试如何确认 author 被正确解析仓库中有一个专门针对author标签的回归测试用例源自 GitHub issue #2603author标签曾被误报为未知标签。测试数据见 src/test/converter2/issues/gh2603.ts/** * author Ian Awesome */ export const x 1;对应的断言在 src/test/issues.c2.test.tsit(#2603 handles author tag, () { const project convert(); const x query(project, x); equal( x.comment?.getTag(author), new CommentTag(author, [{ kind: text, text: Ian Awesome }]), ); logger.expectNoOtherMessages(); });这段测试精确地验证了两点author被解析为Comment上的一个CommentTag标签名为author内容为纯文本Ian Awesome转换全程不产生任何日志告警logger.expectNoOtherMessages()与第 3 节所述的“不会触发 unknown block tag 警告”互相印证。5. 渲染阶段author 如何变成文档中的一个小节author“渲染为注释中的一个段落”这一行为可以在默认主题的渲染器中确认。渲染块标签的函数是 src/lib/output/themes/default/partials/comment.tsx 中的commentTagsconst skippedTags context.options.getValue(notRenderedTags); // ... const tags /* ... 过滤掉 skipRendering 与 notRenderedTags 中标签 */; const tagsContents tags.map((item) { const name item.name ? ${translateTagName(item.tag)}: ${item.name} : translateTagName(item.tag); const anchor context.slugger.slug(name); return ( div class{tsd-tag-${item.tag.substring(1)}} h4 classtsd-anchor-link id{anchor} {name} {anchorIcon(context, anchor)} /h4 {/* item.typeAnnotation 若存在则渲染 */} JSX.Raw html{context.markdown(item.content)} / /div / ); });从源码结构看author标签在默认主题下会被渲染为一个带tsd-tag-author类名的容器div一个h4标题经translateTagName翻译标签名即显示为本地化后的 “Author”标题带锚点方便外部链接直接定位到该小节标签内容经context.markdown(...)渲染为 Markdown 后以原始 HTML 插入因此author内容中可以使用 Markdown 语法。另外注意author不在notRenderedTags默认清单中见 src/lib/utils/options/defaults.ts其中只包含group、category、summary等组织型标签因此它会实际出现在生成的 HTML 里。同时它也支持skipRendering标志——其他标签如remarks、returns的后续重复出现在特定处理流程中会把skipRendering置为 true 从而不出现在页面上但对于author而言不存在这类特殊流程。6. 用法示例官方文档给出的最小示例见 site/tags/author.md/** * author John Smith */ export function rand(min: number, max: number): number;扩展写法内容部分按 Markdown 渲染可写多行、链接、代码等/** * 生成 [min, max) 区间内的随机整数。 * * author John Smith、Jane Doe * * since 1.0.0 */ export function randInt(min: number, max: number): number { return Math.floor(min Math.random() * (max - min)); }使用建议author属于块标签应放在注释的块级位置与remarks、since同层不要嵌入段落中间由于内容会经 Markdown 渲染作者名后可附邮箱、社交主页等纯文本信息不要依赖外部链接仓库文档规范要求避免外链若项目希望统一在“作者”小节之外补充其他信息如license、since它们与author一样都是无行为块标签可自由组合。7. 延伸如何扩展类似的自定义块标签author这类“无行为块标签”的机制对自定义标签同样适用。按 site/tags.md 的说明TypeDoc 支持两种方式扩展标签清单使新标签不再产生 unknown block tag 警告方式一tsdoc.json必须与tsconfig.json放在同一目录{ $schema: https://developer.microsoft.com/en-us/json-schemas/tsdoc/v0/tsdoc.schema.json, extends: [typedoc/tsdoc.json], noStandardTags: false, tagDefinitions: [ { tagName: maintainer, syntaxKind: block } ] }方式二在 JS 配置文件中基于OptionDefaults扩展现有清单官方推荐便于保留全部默认标签// typedoc.config.mjs import { OptionDefaults } from typedoc; export default { blockTags: [ ...OptionDefaults.blockTags, maintainer, ], };配置生效后可直接验证运行pnpm exec typedoc或你项目中对应的npx typedoc/ 脚本入口对使用了新标签的声明确认控制台不再输出Encountered an unknown block tag maintainer警告生成的页面中会像author一样出现tsd-tag-maintainer小节渲染逻辑与第 5 节所示commentTags完全一致。仓库根目录的 tsdoc.json 是本项目自身的 TSDoc 配置实例可参考其写法。8. 小结author是 TypeDoc 内置的无行为块标签仅用于记录作者并渲染为注释中的一个可锚定小节它被内置进 tsdoc-defaults.ts 的blockTags清单经 defaults.ts 成为blockTags选项默认值因此使用时不会触发 unknown block tag 警告且有 issue #2603 的回归测试 保证解析结果正确渲染由默认主题的 commentTags 完成生成带锚点的h4标题加 Markdown 正文若你需要maintainer之类的同类型标签直接通过tsdoc.json或blockTags选项扩展即可渲染行为与author完全一致。赞分享开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载相关推荐TypeDoc 中 Markdown 的完整渲染链路从注释解析到项目文档集成TypeDoc 中 Markdown 的完整渲染链路从注释解析到项目文档集成 TypeDoc 将所有文档注释与独立 Markdown 文档统一交给 markd开发工具文档MNN MnnLlmChat 模型标签系统深度解析从 market_config.json 到 UI 渲染的完整链路MNN MnnLlmChat 模型标签系统深度解析从 market_config.json 到 UI 渲染的完整链路 导读 本文聚焦阿里巴巴 MNN 开源仓库人工智能大模型推理引擎深度学习本地部署模型量化模型优化多模态计算机视觉嵌入式Pandoc author-in-text 引文后缀解析从 Markdown 语法到 Citeproc 渲染的完整原理Pandoc author in text 引文后缀解析从 Markdown 语法到 Citeproc 渲染的完整原理 导读 author p. 33; 文档开发工具CLI上一篇如何使用 Shutter Encoder免费视频压缩神器的完整指南下一篇终极 GitToolBox 插件使用指南提升你的 IDE Git 工作流效率 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考