开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载category是 TypeDoc 提供的一个块标签Block Tag用于在页面索引中把多个相关的 API 条目归到同一个标题之下让大型模块的文档页从“一长串平铺列表”变成有结构的分组目录。本文完整讲解category的用法、categoryDescription描述机制、categoryOrder/defaultCategory/categorizeByGroup等配套选项并结合 CategoryPlugin 源码 剖析分类是在转换流程的哪个阶段、按什么规则落地的帮助你在编写 TypeScript 项目文档时精确控制分组、排序与导航树的呈现。category 标签的作用按 标签总览的分类category属于Block 标签写在注释块内用法要点如下它的作用是把若干相关的 API 条目reflection放到页面索引的同一个公共标题之下同一个文档注释中可以写多次category从而让一个条目同时出现在多个分组标题下源码实现见后文的getCategories它收集的是一个Set而非单一字符串。完整使用示例下面的示例来自 TypeDoc 官方文档site/tags/category.md展示了在一个模块上同时使用categoryDescription、showCategories和module的典型写法/** * categoryDescription Advanced Use * These functions are available for... * showCategories * module */ /** * category General Use */ export function runProcess(): void; /** * category Advanced Use */ export function unref(): void; /** * category Advanced Use */ export function ref(): void;示例中的几个关键结构模块级注释里的module声明这是一个模块showCategories控制分类是否进入导航树下文详述runProcess被归入General Use分类unref与ref被归入Advanced Use分类父级注释里的categoryDescription Advanced Use为Advanced Use这个分类提供了说明文字见下一节。category 标签是如何被收集的源码视角所有分类逻辑集中在 CategoryPlugin 中。它在构造函数里挂接了两个事件src/lib/converter/plugins/CategoryPlugin.ts#L44-L53ConverterEvents.RESOLVE_END转换完成解析阶段后对项目和所有容器型 reflection 执行分类ApplicationEvents.REVIVE从 JSON 反序列化恢复项目时重新分类保证typedoc二次处理如--json再渲染时分类信息依然生效。具体从哪些地方收集category由静态方法getCategories决定src/lib/converter/plugins/CategoryPlugin.ts#L256-L292。它会依次检查该条目自身的文档注释中的category块标签Comment.combineDisplayParts(tag.content).trim()即支持多段文字合并并去除首尾空白重载签名signature上的注释reflection.getNonIndexSignatures()的每个签名的注释都会扫描——这意味着给某个重载写category也能生效类型引用指向的声明当条目的type本身是 reflection 类型时会继续扫描其类型声明及签名的注释这覆盖了类型别名、接口属性等间接引用场景Markdown 文档的前置元数据如果条目是文档DocumentReflection其 frontmatter 里的category字段也会被纳入分类。最后categories.delete()会剔除空字符串分类避免产生无名分组。分类如何落到容器上分组模式与汇总模式categorize方法根据--categorizeByGroup选项选择两种策略之一src/lib/converter/plugins/CategoryPlugin.ts#L102-L108策略触发条件行为groupCategorizecategorizeByGroup为true且容器有groups按group划分出的每个组分别计算分类L110-L131lumpCategorize默认对容器下全部子项childrenIncludingDocuments统一计算分类L133-L150两种策略共用getReflectionCategoriesL158-L210核心行为可以归纳为未分类项归入默认分类某个子项没有收集到任何category时自动归入CategoryPlugin.defaultCategory静态值默认Other可被--defaultCategory选项覆盖见 L39 与setup方法 L73-L81一个条目可属于多个分类对每个子项的每个分类名把该子项push进对应ReflectionCategory.children与“可重复指定”的文档描述一致全默认时隐藏分类层如果最终只有一个分类且它就是默认分类名则把categories置为undefined——整页都没有人工分类时页面索引不会多出一个没有意义的“Other”标题分类内部排序每个分类内的子项会用getSortFunction(parent)排序该方法会读取父级注释上的sortStrategy标签支持对单个容器单独调整排序策略L212-L223。categoryDescription为分类补充说明categoryDescription是配套的块标签用于给某个由category创建出的分类提供上下文说明。使用规则放置位置必须写在包含那些带category子项的 reflection 的注释里例如示例中的模块注释而不是写在使用category的子项上内容格式第一行作为分类名后续行作为分类描述支持 Markdown。源码中这一行为同样由getReflectionCategories实现遍历父级注释的块标签遇到categoryDescription时用Comment.splitPartsToHeaderAndBody(tag.content)拆出首行header与正文body再把正文挂到同名分类的description上src/lib/converter/plugins/CategoryPlugin.ts#L183-L203。一个值得注意的健壮性细节如果描述的分类名在子项中不存在拼写不一致或子项未标注TypeDoc 不会静默忽略而是输出一条告警日志i18n 键comment_for_0_includes_categoryDescription_for_1_but_no_child_in_group方便定位拼写错误。分类排序与命名categoryOrder 与 defaultCategory分类之间的先后顺序由--categoryOrder控制。setup会把该选项的值存入静态属性CategoryPlugin.WEIGHTSsortCatCallback按权重索引排序src/lib/converter/plugins/CategoryPlugin.ts#L232-L254。排序规则按分类名在categoryOrder数组中的位置索引越小越靠前排序支持*通配符未出现在categoryOrder中的分类统一排在*所在位置若未写*则排在所有具名分类之后权重相同时按title.localeCompare字母序兜底。默认分类名由--defaultCategory控制setup中若配置了该选项就覆盖静态默认值Other影响“未标注分类的子项归到哪里”以及“是否隐藏唯一分类”的判断。分类与导航树navigation.includeCategories 及修饰器标签默认情况下分类只作用于页面索引不进入侧边导航树。要让分类出现在导航树中需要开启 navigation.includeCategories 选项选项定义见 src/lib/utils/options/sources/typedoc.ts#L609。开启后还可用两个修饰器标签在父级 reflection 的注释中做选择性开关showCategories强制让该容器的分类进入导航树hideCategories强制隐藏。这两个标签的行为逻辑位于默认主题 DefaultTheme 中src/lib/output/themes/default/DefaultTheme.tsx#L392-L394带hideCategories的一律返回false否则看showCategories是否显式声明。此外在 默认标签列表中showCategories与hideCategories均被登记为修饰器标签无需额外配置即可识别。示例中最开头的模块注释正是同时写了showCategories让General Use/Advanced Use两个分类随导航树呈现。相关选项速查category生态涉及的全部选项及其在源码中的声明位置如下选项类型作用声明位置--categorizeByGroupboolean按group分组分别计算分类而非整页汇总sources/typedoc.ts#L823--defaultCategorystring未分类子项归入的默认分类名默认Othersources/typedoc.ts#L835--categoryOrderstring[]分类排序权重支持*通配符sources/typedoc.ts#L840--searchCategoryBoostsRecordstring, number分类名到权重的映射用于提升指定分类条目在搜索结果中的排名sources/typedoc.ts#L681--navigation.includeCategoriesboolean是否将分类加入导航树sources/typedoc.ts#L609其中categorizeByGroup、defaultCategory、categoryOrder的语义文档见 organization 选项页searchCategoryBoosts与navigation见 output 选项页。选项的类型映射定义在 src/lib/utils/options/declaration.ts#L307-L336。相关标签group标签按组组织条目可与categorizeByGroup配合实现“先分组、组内再分类”的两级结构。小结category体系的设计可以概括为三点分类信息就近标注在条目或签名注释里同时兼容 Markdown frontmatter分类结果延迟到 RESOLVE_END 统一计算由CategoryPlugin落库并在反序列化REVIVE阶段重算呈现层级则由navigation.includeCategories与showCategories/hideCategories在输出阶段决定。理解这条“标注 → 计算 → 呈现”的链路后再配合categoryOrder的权重排序和categoryDescription的说明机制就能对大型 API 文档页的目录结构做精细化控制。赞分享开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载相关推荐TypeDoc 外部 Markdown 文档实战用 document 标签、projectDocuments 选项与 Frontmatter 组织长文指南TypeDoc 外部 Markdown 文档实战用 document 标签、projectDocuments 选项与 Frontmatter 组织长文指南开发工具文档3个关键节点快速上手平衡车FOC固件hoverboard-firmware-hack-FOC新手指南3个关键节点快速上手平衡车FOC固件hoverboard firmware hack FOC新手指南 某天你从储物间翻出一台吃灰的平衡车充电、开机站上去的嵌入式硬件开发智能硬件物联网Halo 分类内文章导航cursorByCategory 主题 API 与 scopecategory REST 参数的实现全解Halo 分类内文章导航cursorByCategory 主题 API 与 scopecategory REST 参数的实现全解 导读 本文围绕 Halo后端前端CMS上一篇OptiScaler终极指南跨GPU上采样技术让任何显卡都能享受DLSS级画质下一篇Nativefier 与 Web Audio 缓冲区管理内存优化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考