三级标准化分组
基于 @microsoft/tsdoc 0.16.0 编写
速查
- 每个 TSDoc 标签除了"种类"（块/修饰/内联），还被标了一个标准化分组，表达"工具该多大程度上支持它"
- Core：必备——所有文档工具都应识别、支持
- Extended：可选——但工具一旦实现，就必须按标准语义来
- Discretionary：可选——语义可因实现而异
- 跨多工具协作（同一套注释给 TypeDoc + API Extractor 共用）→ 优先用 Core 档标签最稳
- "分组"与"种类"是两个正交维度：一个标签既属于某个种类，又属于某个分组
- 官方页只给三档定义；某个标签具体归哪档以官方 spec / 源码为准，别凭记忆套
为什么要分组
TSDoc 的核心诉求是"互操作"——同一份注释要能被多种工具一致解析。但不同工具能力不同，不可能强求每个工具都支持每个标签。于是 TSDoc 给标签分了三档"标准化程度"，让工具与作者对"这个标签靠不靠得住跨工具一致"有明确预期。
三档定义
| 分组 | 官方定性 | 含义 | 跨工具可靠性 |
|---|---|---|---|
| Core | “considered essential” | 核心、必备，所有文档工具都应识别支持 | 最高：放心跨工具用 |
| Extended | “optional” | 可选；但工具若实现它，就得遵循标准定义的语义 | 中：实现了就一致，但不保证都实现 |
| Discretionary | “optional” | 可选；其语义可因具体实现而异 | 低：同名标签在不同工具里可能行为不同 |
Core 与 Discretionary 的关键差异
Core 标签"每个工具都应识别"且语义统一；Discretionary 标签连"语义"都可能因工具而异。所以做跨工具协作时，优先依赖 Core 档标签最稳妥，Discretionary 档要查清你用的那套工具是怎么解释它的。
分组 ≠ 种类
这两个维度互相独立，别混为一谈：
- 种类（kind）：决定写法——块标签独占行、修饰标签放末尾、内联标签包在
{}里。 - 分组（group）：决定跨工具的标准化程度——Core / Extended / Discretionary。
同一个标签同时拥有这两个属性。例如 @param 是"块标签"（种类）且属"Core"（分组）；{@link} 是"内联标签"（种类）且属"Core"（分组）。
权威归属去哪查
官方 spec 页只给出三档的定义，并不在页面上逐一列出"哪个标签属哪档"——该分类维护在 TSDoc 仓库的源码（Standardization.ts）中。要确认某个标签的准确分组，去 tsdoc.org 对应标签页或仓库源码核对，不要凭印象断言。