TypeDoc @readonly 标签详解：将可写成员标记为文档只读

开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载导读readonly是 TypeDoc 提供的一组修饰符标签Modifier Tag之一它允许你在 TypeScript 类型系统认为某个成员“可写”的情况下仍指示 TypeDoc 在生成文档时将其呈现为只读non-writable。本文结合 TypeDoc 仓库源码完整讲解readonly的语义、底层处理流程、渲染效果与测试用例帮助你在 API 文档中精确表达“消费方不应修改”的设计意图。readonly标签语义根据 site/tags/readonly.md 的官方说明Thereadonlytag indicates that a reflection should be documented as non-writable, even if writable according to TypeScript.即readonly的作用是覆盖 TypeScript 本身的可写性判断。无论 TypeScript 认为该成员是否有 setter、是否可赋值只要注释中带有readonlyTypeDoc 就会将其记录为只读并如此渲染。该标签属于修饰符标签Modifier Tag与private、protected、public、abstract、sealed等同属一类完整清单见 tags.md。官方示例getter 与 setter 的处理原文档给出的示例展示了一个经典场景——某个属性同时定义了 getter 与 setter但从文档视角应视为只读export class Readable { /** readonly */ get prop() { return 1; } /** Will be removed from the documentation due to the readonly tag */ set prop(_: number) { throw new Error(Not permitted); } }在这个例子中getterprop上的readonly使整个属性在文档中被标记为只读setterprop的注释也说明它会因 readonly 标签而从文档中移除。源码级解析readonly的完整处理链路1. 修饰符识别与标志设置readonly的解析发生在转换器插件 CommentPlugin.ts 的applyModifiers中。当注释包含readonly修饰符时第 234–240 行if (comment.hasModifier(readonly)) { const target reflection.kindOf(ReflectionKind.GetSignature) ? reflection.parent! : reflection; target.setFlag(ReflectionFlag.Readonly); comment.removeModifier(readonly); }关键逻辑在于如果反射对象是GetSignaturegetter 签名则把Readonly标志设置到它的父级即属性/访问器本身否则直接设置到当前反射对象处理完成后会从注释中移除readonly修饰符确保它不会以原始标签形式出现在渲染结果中。ReflectionFlag.Readonly定义在 Reflection.ts 中是一个位标志export enum ReflectionFlag { None 0, // ... Readonly 1 9, // ... }同时它被列入relevantFlags第 45–53 行并对外暴露isReadonlygetter第 124–125 行供渲染模板查询get isReadonly() { return this.hasFlag(ReflectionFlag.Readonly); }2. 解决阶段隐藏 setter 并清理标志在onBeginResolve第 361–368 行中TypeDoc 会遍历项目中的反射对**访问器Accessor**做特殊处理if (ref.kindOf(ReflectionKind.Accessor) ref.flags.isReadonly) { const decl ref as DeclarationReflection; if (decl.setSignature) { hidden.add(decl.setSignature); } // Clear flag set by readonly since it shouldnt be rendered. ref.setFlag(ReflectionFlag.Readonly, false); }这段代码揭示了两点实现细节setter 被加入隐藏集合凡是被readonly标记的访问器其setSignature会被隐藏最终通过project.removeReflection从文档中移除——这正是原文档示例中 setter “被移除”的底层原因清除访问器本身的 Readonly 标志注释明确指出该标志“不应被渲染”shouldnt be rendered因为只读性最终体现在签名渲染的关键字上而不是访问器本身上。3. 渲染阶段readonly关键字的输出只读标志最终会以 TypeScript 的readonly关键字形式出现在生成的文档签名中。在默认主题的索引签名渲染中可以看到templates/reflection.tsx第 79–84 行{index.flags.isReadonly ( span classtsd-signature-keywordreadonly/span { } / )}partials/typeDetails.tsx第 388–393 行中也有完全相同的渲染逻辑用于参数索引签名。也就是说isReadonly标志一旦置位文档签名前就会出现readonly关键字让读者一眼看出该成员不可写。测试用例验证仓库在 readonlyTag.ts 中提供了覆盖readonly行为的测试样例包含两种典型用法export class Book { /** * Technically property has a setter, but for documentation purposes it should * be presented as readonly. * readonly */ get title(): string { return hah; } set title(_value: string) { throw new Error(This property is read-only!); } /** * Should be documented as readonly because no consumer should change it. * readonly */ author!: string; }该测试用例与原文档示例相互印证覆盖了两个典型场景含 setter 的属性title在类型层面可写存在 setter但通过readonly声明为文档只读类属性字段author使用!断言definite assignment assertion本身是可赋值的同样通过readonly在文档中呈现为只读。使用建议与注意事项适用场景API 设计中的“防御性只读”属性虽然出于实现原因保留了 setter但设计上禁止外部修改如内部状态、缓存值。此时用readonly向文档读者明确传达契约避免误导的类型系统表达当 TypeScript 的类型信息无法表达“不可变”语义例如定义了 setter 但会抛错、或使用!断言声明的字段readonly是补充文档语义的正确工具索引签名对于索引签名index signatureReadonly 标志同样会被渲染为readonly关键字可配合使用。注意事项readonly只影响 TypeDoc 的文档输出不会改变 TypeScript 的类型检查行为不要用它替代readonly修饰符或ReadonlyT类型工具标记了readonly的访问器的setter 会从文档中完全移除这是预期行为而非 bug见 CommentPlugin.ts 的隐藏逻辑与private、sealed等一样它属于修饰符标签会在转换阶段被消费并从注释中移除不会残留在渲染文本中。小结readonly是 TypeDoc 修饰符标签家族中一个简洁但实用的工具通过一行注释即可覆盖 TypeScript 的可写性判断将成员在文档中呈现为只读并自动隐藏对应的 setter。其完整链路——从 CommentPlugin.ts 的标志设置、解决阶段的 setter 隐藏到默认主题模板中的readonly关键字渲染——都体现了 TypeDoc “以注释驱动、以类型为基础”的文档生成理念。当你的 API 存在“类型可写但契约只读”的成员时readonly就是表达该契约的标准方式。赞分享开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载相关推荐TypeDoc abstract 标签在 TypeScript 中把“非抽象”方法标记为抽象并写入文档TypeDoc abstract 标签在 TypeScript 中把“非抽象”方法标记为抽象并写入文档 本篇基于 TypeDoc 官方文档中 abstra开发工具文档TypeDoc internal 标签详解标记内部 API 并通过 --excludeInternal 从文档中移除TypeDoc internal 标签详解标记内部 API 并通过 excludeInternal 从文档中移除 本文围绕 TypeDoc 的 inter开发工具文档TypeDoc deprecated 标签详解从文档标记到删除线渲染的完整机制TypeDoc deprecated 标签详解从文档标记到删除线渲染的完整机制 本文基于 TypeDoc 官方文档 site/tags/deprecated开发工具文档上一篇munder-difflin 时间窗口技能解析last30Days 如何把近 30 天解析为精确的 ISO 日期范围下一篇终极指南ViewAnimator从iOS 8到iOS 15的跨版本适配要点创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考