企业官网建设流程全解析

• 开发工具
• 文档

@useDeclaredType是 TypeDoc 提供的一个修饰型（Modifier）标签，专门用于指导类型别名的文档化方式：当类型别名基于ReturnType、typeof、泛型实例化等派生表达式时，它能让 TypeDoc 优先使用 TypeScript 编译器解析出的"声明类型"（declared type）来生成文档，而不是直接照搬源码中的类型节点（type node），从而显著改善派生类型的可读性。本文以 TypeDoc 官方标签文档为主体，结合 转换器源码 与 行为测试用例 的源码级证据，完整讲解该标签的用法、底层实现原理、适用场景与已知边界。

标签定位：一个修饰型（Modifier）标签

@useDeclaredType在 TypeDoc 的标签体系中属于Modifier（修饰符）类别（见 tags.md）。所谓修饰标签，是指那些不携带正文内容、仅以"开关"方式改变转换行为的标签，与其同类的还有@interface、@namespace、@reexport、@expand等。

从仓库配置可以印证这一点：

• 在 tsdoc-defaults.ts 的modifierTags数组中，@useDeclaredType与@abstract、@class、@interface、@namespace、@reexport等标签并列注册（第 98 行）；
• 在项目根目录的 tsdoc.json 中，该标签被声明为"syntaxKind": "modifier"，即按修饰符语法解析；
• 在 中文语言包 中，它被翻译为tag_useDeclaredType: "使用声明类型"，这也直接点明了标签的语义：使用声明类型。

核心语义：声明类型 vs 类型节点

默认情况下，TypeDoc 在把类型别名转换成文档时，读取的是该别名声明的type node——也就是你在源码里写出的那一段类型表达式。但对于派生类型（derived types），源码中写出的往往是一个"计算过程"而非"最终结果"。

@useDeclaredType的作用就是告诉 TypeDoc：不要照抄源码中的类型表达式，而是用 TypeScript 编译器对符号求值得到的声明类型来转换。TypeDoc 官方文档的原话是：

This tag can be specified on type aliases to tell TypeDoc to convert them using the declared type rather than the type node. This can result in better documentation for derived types.

需要注意的是：该标签只对类型别名（type alias）生效，如果标注在其它声明上（类、接口、函数、变量等），TypeDoc 会忽略它，不产生任何效果。

源码级实现原理

在 src/lib/converter/symbols.ts 中，类型别名的转换逻辑完整地体现了这一语义。简化后的关键代码路径如下：

if (ts.isTypeAliasDeclaration(declaration)) { const comment = context.getComment(symbol, ReflectionKind.TypeAlias); // ... @reexport 与 @interface 的先行判断 ... const reflection = context.createDeclarationReflection( ReflectionKind.TypeAlias, symbol, exportSymbol, ); context.finalizeDeclarationReflection(reflection); if (reflection.comment?.hasModifier("@useDeclaredType")) { reflection.comment.removeModifier("@useDeclaredType"); reflection.type = context.converter.convertType( context.withScope(reflection), context.checker.getDeclaredTypeOfSymbol(symbol), // ← 声明类型 ); } else { reflection.type = context.converter.convertType( context.withScope(reflection), declaration.type, // ← 类型节点 ); } // ... 后续联合类型注释、对象字面量提升等处理 ... }

从中可以提取出三条实现事实：

1. 入口限制：@useDeclaredType的检查位于ts.isTypeAliasDeclaration(declaration)分支内部（symbols.ts），因此该标签天然只作用于类型别名——这与文档中"标注在其他声明上无效"的描述严格对应。
2. 类型来源切换：默认路径使用declaration.type（源码类型节点）调用convertType；带标签时改用context.checker.getDeclaredTypeOfSymbol(symbol)（TypeScript 编译器解析出的声明类型）。这是整个标签行为差异的核心。
3. 修饰符清理：转换完成后会通过reflection.comment.removeModifier("@useDeclaredType")将该修饰符从注释中移除，避免它被渲染进最终文档页面（symbols.ts）。

此外，@useDeclaredType与@interface在实现上是平级且互斥的关系：@interface的检查（comment?.hasModifier("@interface")）先行执行，命中后直接走convertTypeAliasAsInterface分支返回；只有未命中@interface时，才会走到@useDeclaredType的判断（symbols.ts）。

典型使用场景：派生类型别名的文档化

@useDeclaredType最典型的应用场景是那些无法直接写出、必须通过类型运算得到的别名。官方文档给出了如下示例：

function getData() { return [{ abc: 123 }]; } /** @useDeclaredType */ export type Data = ReturnType<typeof getData>; // Data 将被文档化为等价于手写： export type DataManual = { abc: number }[];

不使用该标签时，TypeDoc 会在文档中显示ReturnType<typeof getData>这一原始的运算表达式——它对阅读文档的开发者而言既不直观也无法直接获知结构；加上@useDeclaredType后，TypeDoc 直接展开为{ abc: number }[]，文档清晰可读。

这一行为在仓库测试中得到了精确验证。测试夹具 useDeclaredTypeTag.ts 复用了getData与Data的示例代码，而 behavior.c2.test.ts 中的用例断言了转换结果：

it("Handles the @useDeclaredType tag on types", () => { const project = convert("useDeclaredTypeTag"); const data = query(project, "Data"); equal(data.type?.toString(), "{ abc: number }[]"); });

即：带@useDeclaredType的Data，其最终渲染类型必须是展开后的{ abc: number }[]，而非ReturnType<typeof getData>。这为标签的预期行为提供了可回归验证的自动化保障。

已知约束与边界：何时不该使用

官方文档明确警告，使用该标签并非总是得到更好的文档，其输出存在以下不稳定因素：

• 跨版本不稳定：带此标签的输出在不同 TypeScript 版本之间，或类型内部发生非常微小的变化时，都可能随之改变；
• 可能反而更差：取决于类型别名的具体写法，使用该标签后文档质量可能比默认方式更差；
• 最常见的错误形态：类型被文档化为"对自身的引用"（a reference to itself），即展开结果变成递归引用自身别名，破坏可读性。

官方示例同时给出了一个明确不适用的反例——映射类型（mapped type）：

// 这种方式不幸地不会按预期工作 export type Bar = { a: string }; /** @useDeclaredType */ export type BarNum = { [K in keyof Bar]: number };

对BarNum这类基于keyof的映射类型，声明类型展开后往往会产生难以预期的结果，因此并不适合使用该标签。这也提醒开发者：先在小范围内实验，确认生成的文档符合预期后再推广使用，并建议在文档构建流程中检查渲染结果，防止类型展开引入自引用等退化情况。

与@interface标签的配合关系

@useDeclaredType与@interface标签在功能上有互补关系，二者可以视为"类型别名文档化的两种改写手段"：

• @interface：将类型别名转换为接口形态展示，把 Record、映射等"动态属性"展开为真实属性成员；
• @useDeclaredType：将类型别名按编译器求值后的声明类型展示，适用于派生类型（如ReturnType）。

在 interface.md 文档 的 "See Also" 一节中，两个标签互相引用，说明官方将其视为一组相关的修饰标签。实际使用中，如果目标是让派生类型展示出"数据结构的真实形态"，@useDeclaredType是直接答案；如果目标是让类型别名以接口语义呈现并支持成员级注释，则应考虑@interface（可参考 interface.md 中的Record<"a" | "b" | "c", string>展开示例）。

相关资源

继续深入探索时，可在当前仓库中参考以下内容：

• 官方标签总览：tags.md
• 标签原始文档：useDeclaredType.md
• 转换器核心实现：src/lib/converter/symbols.ts
• 修饰标签注册表：src/lib/utils/options/tsdoc-defaults.ts
• TSDoc 配置声明：tsdoc.json
• 行为测试用例：src/test/behavior.c2.test.ts
• 测试夹具源码：src/test/converter2/behavior/useDeclaredTypeTag.ts
• 中文语言包翻译：src/lib/internationalization/locales/zh.ts

• 开发工具
• 文档