TypeDoc 展开标签深度解析：@expand、@expandType 与 @preventExpand 如何控制类型引用的文档展示

开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载TypeDoc 在渲染文档时默认只会把类型别名或接口的引用显示为一个链接读者需要点进类型页面才能看到其内部结构。本文基于仓库中 expand.md 的官方说明系统讲解expand、expandType、preventExpand三个标签的语义差异、继承与覆盖规则并结合默认主题渲染器源码typeDetails.tsx还原其判定逻辑帮助你在 React 组件 props、嵌套对象类型等场景下精确控制类型信息的内联展示。一、Expand 标签的定位控制展示而非转换文档开头明确区分了两类标签的作用层面参见 inline.md标签族作用阶段效果inline/inlineType/preventInline转换阶段converter把类型别名/接口的引用内联转换成对象字面量结构签名里直接写成Hello(props: { name: string })expand/expandType/preventExpand渲染阶段renderer保持类型为引用但在渲染引用时把被引用类型的结构细节展开显示出来也就是说Expand 系列标签不影响模型中的类型表示只影响最终 HTML 里展开多少内容。三者分别对应全局开关、局部展开、取消展开expand标签类别为Modifier修饰符标签作用于类型别名和接口本身expandType标签类别为Block块标签带参数作用于任意 reflectionpreventExpand标签类别为Block块标签带参数用于抵消前两者的展开效果。标签类别的划分可以对照 tags.md 中 Block Tags / Modifier Tags 的定义也可以从源码确认tsdoc-defaults.ts 将preventExpand、expandType列入 TSDoc 块标签列表而expand出现在修饰符标签列表中。二、expand让被引用类型的结构在所有引用处展开用法expand可以放在类型别名和接口上。被标注后TypeDoc 会在所有有地方可放的位置把该类型的声明内联展示出来/** * Props docs * expand */ export type HelloProps { /** Name property docs */ name: string; }; /** * Hello */ export function Hello(props: HelloProps) { return {}; } /** * Hello2 * param props Props docs (used instead of expand description) */ export function Hello2(props: HelloProps) { return {}; }官方文档特别指出这对 React 组件很有价值查看组件函数时props参数旁边就能直接看到 props 类型的成员说明。上面的例子还展示了另一个细节——摘要回退机制Hello没有为自己的props参数写param因此渲染时会借用HelloProps上 Props docs 的摘要作为参数描述Hello2明确写了param props Props docs (used instead of \expand description)此时显式描述优先expand 类型上的摘要不会被使用。源码印证摘要回退逻辑位于默认主题的评论部分渲染器 comment.tsx 中commentSummary在自身 summary 为空、且参数类型是一个指向被expand标注类型的引用时直接渲染目标类型的 summaryconst target (props.isDeclaration() || props.isParameter()) props.type?.type reference ? props.type.reflection : undefined; if (target?.comment?.hasModifier(expand) target?.comment?.summary.some((part) part.text)) { return context.displayParts(target.comment.summary); }而结构展开本身则由 typeDetails.tsx 中的shouldExpandReference决定详见下文第四节。官方注意事项如果把expand应用到常用类型上会在每个引用处重复内联该类型及其成员注释显著增大生成的文档体积。三、expandType在引用方按需展开支持继承expandType可以放在任意reflection 上指示 TypeDoc 在该 reflection 内部渲染时展开某个具体的类型引用参数是不带类型实参的类型名export type HelloProps { /** Name description */ name: string; }; /** * Hello component * expandType HelloProps */ export function Hello(props: HelloProps) { return spanHello {props.name}!/span; }此时 TypeDoc 会在Hello处像HelloProps上写了expand一样展开它但不影响其他引用点。与expand作用于被引用方、全局生效不同expandType支持继承把它放在命名空间或模块上可以让该模块内所有对某类型的引用都被展开。这一继承行为可以从源码结构看得到——getExpandTypeInfo会沿着refl.parent链逐级收集父级命名空间/模块上的expandType与preventExpand名称集合再合并本节点自己的标签if (!refl.isProject()) { const info getExpandTypeInfo(refl.parent!); for (const item of info.expandType) expandType.add(item); for (const item of info.preventExpand) preventExpand.add(item); }四、preventExpand抵消三种来源的展开preventExpand是块标签参数同样是不带类型实参的类型名。它用来抵消以下任意来源产生的展开被引用类型上的expand当前或父级 reflection 上的expandType通过param高亮引用类型的属性而触发的展开参见 param.md。/** * expand */ export type HelloProps { /** Name property docs */ name: string; }; /** * Hello component - HelloProps will NOT be expanded here * preventExpand HelloProps */ export function Hello2(props: HelloProps) { return spanHello {props.name}!/span; }展开判定的完整源码逻辑shouldExpandReference 集中体现了三来源与抵消规则function shouldExpandReference(container: Reflection, reference: ReferenceType) { const target reference.reflection; ... // Prevent recursive expand if (expanded.has(target)) return false; const info getExpandTypeInfo(container); // Expand if the user explicitly requested it with param or expand if (reference.highlightedProperties || target.comment?.hasModifier(expand) || info.expandType.has(target.name)) { return !info.preventExpand.has(target.name); } return false; }几个关键点container是持有该类型引用的 reflectiontarget是被引用的类型。判定该不该展开时读取的是container侧含其父级继承链收集到的expandType/preventExpand名称集合——这正是expandType继承机制的落点三个触发条件param高亮属性highlightedProperties、目标类型带expand、expandType集合命中目标类型名任一满足才进入展开候选且最终仍要排除preventExpand集合中的名字getExpandTypeInfo内部对同名标签做了互斥处理遇到expandType时执行expandType.add(name); preventExpand.delete(name)遇到preventExpand时执行preventExpand.add(name); expandType.delete(name)。结合先继承父级、后处理自身标签的顺序可以推断出后声明者覆盖先声明者、子级覆盖父级的语义expanded集合在递归渲染引用目标时临时加入/移除目标 reflectiontypeDetailsImpl的reference分支中expanded.add(target)/expanded.delete(target)用于防止类型互相引用导致的无限递归展开。另外结果带有WeakMapReflection, ExpandTypeInfo缓存expandTypeCache同一 reflection 的展开信息只计算一次。五、继承、嵌套与覆盖行为来自测试夹具的证据仓库的渲染测试夹具 expandType.ts 完整覆盖了上述规则/** expand */ export interface ExpandedByDefault { /** B */ b: string; } /** * expandType Expandable * preventExpand ExpandedByDefault */ export type AExpanded { a: Expandable; b: ExpandedByDefault; c: Expandable2 }; // Defaults are fine export type BExpanded { a: Expandable; b: ExpandedByDefault; c: Expandable2 }; /** * expandType Expandable * * expandType Expandable2 */ export namespace NestedBehavior1 { export type AllExpanded { a: Expandable; b: ExpandedByDefault; c: Expandable2 }; /** * preventExpand Expandable * preventExpand Expandable2 */ export type AExpanded { a: Expandable; b: ExpandedByDefault; c: Expandable2 }; }对照夹具可以看出四个行为要点AExpanded同时使用expandType Expandable和preventExpand ExpandedByDefault尽管ExpandedByDefault自带expand本应默认展开该别名内b字段不会展开BExpanded不做任何标注ExpandedByDefault按expand默认展开而Expandable、Expandable2不展开NestedBehavior1命名空间上的expandType被其内部的AllExpanded继承三个成员类型中Expandable与Expandable2都被展开NestedBehavior1.AExpanded上的子级preventExpand覆盖了命名空间级的expandType两个类型在此处都不再展开。这些行为各有对应的渲染快照断言例如 ExpandType.AExpanded.json、ExpandType.BExpanded.json、ExpandType.ExpandedByDefault.json 以及命名空间继承场景的 ExpandType.NestedBehavior1.json、ExpandType.NestedBehavior1.AllExpanded.json、ExpandType.NestedBehavior1.AExpanded.json可作为验证展开结果的参照。六、标签的渲染可见性为什么页面上看不到这些标签expand、expandType、preventExpand都是纯控制性标签不会出现在生成的文档页面上。这一点由 defaults.ts 中的notRenderedTags列表保证——三个标签都位列其中默认主题的commentTags渲染时会过滤掉这些块标签的展示。如果项目自定义了 TSDoc 配置注意 tsdoc-defaults.ts 已把preventExpand、expandType声明为标准块标签通常无需再通过--blockTags选项手动注册选项机制参见 configuration.md。七、实战选型建议结合官方文档与源码语义可按如下原则选择标签被引用类型希望处处展开典型如 React 组件的 props 类型在被引用类型上写expand。代价是文档体积膨胀且引用方未写param时会借用其摘要只希望某处展开在引用方写expandType 类型名。若某模块内大量引用同一类型放在模块/命名空间注释上即可靠继承一次生效某处不想展开全局expand或模块级expandType的例外写preventExpand 类型名优先级高于expand与继承来的expandType只需要把结构写进签名而非仅展示那属于inline族标签的范畴参见 inline.md两者可以配合使用preventExpand同样能抵消通过param属性高亮触发的展开。三个标签均为可选微调工具不加任何标签时引用保持为链接只有被expand标注的类型会默认展开其余行为与仓库测试夹具BExpandedDefaults are fine所验证的默认渲染一致。赞分享开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载相关推荐nvidia/esm2_t48_15B_UR50D入门指南从安装到首次蛋白质结构预测nvidia/esm2_t48_15B_UR50D入门指南从安装到首次蛋白质结构预测 nvidia/esm2_t48_15B_UR50D是一款基于TransfJupyterLab 文档注册表Document Registry深度解析文档类型、工厂机制与扩展开发实战JupyterLab 文档注册表Document Registry深度解析文档类型、工厂机制与扩展开发实战 jupyterlab/docregistry前端后端数据科学开发工具TypeDoc文档标签系统全面解析TypeDoc文档标签系统全面解析 TypeDoc作为TypeScript项目的文档生成工具其标签系统是构建高质量API文档的核心。本文将深入剖析TypeDo开发工具文档上一篇ChatGPT Shortcut 浏览器扩展使用指南三种显示模式、侧边栏常驻与 AltShiftS 快捷键下一篇SOES同步机制详解SM同步与DC同步在工业控制中的实际应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考