新闻详情

新闻详情

首页 / 资讯中心 / 详情

TypeDoc @category 标签详解:为 API 文档组织分类、排序与导航

发布时间:2026/11/18 17:16:55来源:尧图网络
TypeDoc @category 标签详解:为 API 文档组织分类、排序与导航
开发工具文档【免费下载链接】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),仅供参考
网站建设高端定制企业官网
RELATED

相关资讯

更多精彩内容,欢迎继续阅读

较早相关资讯

最新相关资讯

【外设】之大彩串口显示屏 2026/11/17 7:04:08

【外设】之大彩串口显示屏

大彩串口屏初步使用 1 .官网下载 STM32 屏幕 GUI 设计资料 http://www.gz-dc.com/category/typeid/4112 找到 STM32 Keil 工程,移植相关代码因项目而异进行移植,由于项目简单,本人只对用到的指令接口进行修改。 比如:注意事项&…

阅读更多 →
无法下载Windows系统iso文件 2026/11/18 14:20:46

无法下载Windows系统iso文件

当我遇到这个问题的时候,我打开了一个网站: 登录 然后我打算下载的时候: 突然那个官方的连接就可以下载了:

阅读更多 →
【清华代码熊】DeepSeek V4.1 Flash 后训练详解 2026/11/17 19:43:34

【清华代码熊】DeepSeek V4.1 Flash 后训练详解

📌 上期解析了 DeepSeek V4.1 Flash 模型架构改进,本期解析 DeepSeek V4.1 Flash 预训练/后训练技术: 🌟 预训练:45T 文本 多模态混合语料、直接训练 sparse attention(取消 DeepSeek V4 的 dense 冷启动&…

阅读更多 →
Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ... 2026/11/18 11:04:06

Shuffle-R1: Efficient RL framework for Multimodal Large Language Models via Data-centric Dynamic ...

文章主要内容和创新点 主要内容 本文聚焦于多模态大语言模型(MLLM)强化学习(RL)训练中的效率问题,提出了一个名为Shuffle-R1的框架。研究发现,当前RL训练存在两个关键缺陷: 优势值坍缩(Advantage Collapsing):批次中大多数优势值集中在零附近,导致有效梯度信号被淹…

阅读更多 →
PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction 2026/11/18 15:55:22

PRvL: Quantifying the Capabilities and Risks of Large Language Models for PII Redaction

一、文章主要内容总结 本文聚焦于利用大型语言模型(LLMs)实现个人身份信息(PII)脱敏的研究,旨在解决传统脱敏方法(如基于规则的系统、领域特定命名实体识别(NER)模型)泛化能力差、跨格式/跨语境适应性弱的问题。 研究通过全面评估多种LLM架构(包括密集型LLM(D-LLM…

阅读更多 →
LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model 2026/11/17 19:43:32

LLaVA-RE: Binary Image-Text Relevancy Evaluation with Multimodal Large Language Model

文章主要内容和创新点 主要内容 本文聚焦于二进制图像-文本相关性评估任务(判断图像与文本“相关”或“不相关”),针对该任务中文本格式多样、相关性定义随场景变化等挑战,提出了基于多模态大语言模型(MLLM)的解决方案LLaVA-RE。 模型设计:LLaVA-RE基于LLaVA 1.5架构,…

阅读更多 →

今日资讯

本周资讯

本月资讯

看完文章仍有疑问?

联系尧图顾问,获取一对一建站咨询

立即免费咨询 📞 400-888-8888
📞 ✉