开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载privateRemarks是 TypeDoc 支持的 TSDoc 标准块级标签用于在文档注释中书写仅供维护者查看、且不会出现在生成 API 参考中的文字。本文基于 TypeDoc 仓库的 标签文档 与 源码实现 展开讲清它的写法、TypeDoc 默认将其剔除的底层机制以及自定义--excludeTags时必须注意的坑并展示该标签在 TypeDoc 自身源码中的真实用法。一、什么是 privateRemarksprivateRemarks属于Block块级标签标签总表见 tags.md其规范来源是 TSDoc 标准。它的用途很明确用来包含那些不应出现在生成的 API 参考中的文档文字。典型场景是团队内部约定给某个 API 写上实现细节、临时说明、已知局限等这些信息对阅读源码的开发者有价值但对外部 API 使用者是噪音。privateRemarks就是把这些内容“藏”在文档注释里的标准位置。TypeDoc 对 TSDoc 的态度是“兼容但不强制”——它应能解析几乎所有 TSDoc 合规的注释但并不要求你的注释严格遵循标准见 TSDoc Support。privateRemarks是 TSDoc 块级标签之一在 TypeDoc 内部的 tsdoc-defaults.ts 中被明确列入tsdocBlockTags列表与defaultValue、deprecated、example、param、remarks、returns、see、throws、typeParam等并列。二、怎么写完整示例官方文档给出的示例如下继承自 site/tags/privateRemarks.md/** * Some docs here * * privateRemarks * Implementation detail notes not useful to the API consumer */ export function rand(): number;要点privateRemarks作为块级标签放在注释体内、独立成段其后每一行都属于该标签的内容直到下一个块级标签或注释结束标签前面的正文Some docs here会正常渲染到 API 文档中标签块内的文字默认不会出现在生成的文档页面里。标签内容同样支持 TSDoc 注释中允许的 markdown 片段TypeDoc 把大部分注释解析委托给其 markdown 解析器见 TSDoc Support因此备注中可以写多行文字、列表等写法上与remarks完全一致。三、为什么默认不显示excludeTags 机制privateRemarks被隐藏不是特判逻辑而是由excludeTags选项的统一机制实现的。3.1 默认的排除列表TypeDoc 在 defaults.ts 中定义了excludeTags选项的默认值export const excludeTags: readonly TagString[] [ override, virtual, privateRemarks, satisfies, overload, inline, inlineType, ];privateRemarks就在其中——这就是“TypeDoc 默认把该标签从文档中剔除”的直接出处。3.2 剔除发生在注释处理阶段选项定义位于 typedoc.tsname: excludeTags, help: () i18n.help_excludeTags(), defaultValue: OptionDefaults.excludeTags, validate: makeTagArrayValidator(excludeTags),选项帮助文本在各语言本地化文件中给出例如 en.ts 中为 Remove the listed block/modifier tags from doc comments从文档注释中移除列出的块级/修饰符标签。真正执行剔除的是转换器插件 CommentPlugin。它通过Option(excludeTags)注入该选项第 124-125 行并在每个声明/签名反射创建时调用removeExcludedTags第 341 行private removeExcludedTags(comment: Comment) { for (const tag of NEVER_RENDERED) { comment.removeTags(tag); comment.removeModifier(tag); } for (const tag of this.excludeTags) { comment.removeTags(tag); comment.removeModifier(tag); } }从源码结构看剔除发生在转换conversion阶段标签被从Comment对象中移除后后续的序列化、渲染环节根本看不到它因此它不会进入 JSON 输出也不会被默认主题渲染。另外注意NEVER_RENDERED常量type、typedef等纯 JS 类型提示类标签是无条件剔除的而excludeTags是用户可配置的剔除列表——privateRemarks属于后者。四、注意自定义 --excludeTags 时必须保留 privateRemarks官方文档 site/tags/privateRemarks.md 的 “TSDoc Compatibility” 一节强调TypeDoc will omit this tag from the documentation by default,but the user is responsible for including it in the--excludeTagslist if it is set.TypeDoc 默认会省略该标签但如果用户设置了excludeTags则需要用户自行将其列入。原因是选项覆盖语义一旦你通过命令行--excludeTags或配置文件中的excludeTags指定了新列表新的列表会整体替换默认值默认列表中的override、virtual、satisfies、overload、inline、inlineType以及privateRemarks都不再自动生效。如果你的意图只是额外排除某几个标签正确做法是在自定义列表中带上原默认项例如// typedoc.json { excludeTags: [ override, virtual, privateRemarks, satisfies, overload, inline, inlineType, myCustomInternalTag ] }反过来TSDoc Support 也说明privateRemarks“可以被配置为包含在文档中”——即如果你就是想让这些备注展示出来把privateRemarks从excludeTags中移除或干脆使用不含它的自定义列表即可它便会像普通块级标签一样以标题形式渲染。选项的完整说明见 options/comments.md。五、真实用法TypeDoc 源码自己就在用最有说服力的例子是 TypeDoc 自身代码库里对privateRemarks的使用——它正是“写在 API 表面、但不想随文档发布”的实现备注。例如 ReflectionSymbolId/** * This exists so that TypeDoc can store a unique identifier for a ts.Symbol without * keeping a reference to the ts.Symbol itself. ... * * privateRemarks * The ReflectionSymbolId class instance should be treated as immutable. All properties must * be marked readonly to assist with this. */ export class ReflectionSymbolId { ... }类注释主体解释了它“是什么、为什么存在”会对外展示而privateRemarks里的“实例应视为不可变”是纯内部约定不对外展示。类似的用法还出现在Context.createSymbolReference / createSymbolId备注说明“这些方法放在 Context 上是为了让 typedoc-plugin-missing-exports 可以 monkey-patch”ReflectionSymbolId.fileName备注说明“typedoc-plugin-dt-links 用这个路径去读取 DefinitelyTyped 包的源码”以及 GroupPlugin、types.ts、events.ts 等文件中的同类备注。这些例子展示了推荐的使用姿势privateRemarks的读者是读源码的同事而不是读 API 文档的用户。六、与 remarks、hidden 的边界区分容易混淆的三个标签定位不同标签类型是否展示作用对象remarksBlock展示默认主题下以# Remarks标题渲染把总结与长文说明分段使用{inheritDoc}时会被复制privateRemarksBlock默认不展示列入默认excludeTags存放仅维护者可见的备注hiddenModifier标签本身不作为文本展示隐藏整个符号整个 reflection 被移除而不仅仅是备注文字关键区别privateRemarks只丢弃“备注这一块内容”符号本身及其其余文档照常生成hidden则是把整个 API 条目从文档中拿掉。若你想隐藏的是“带internal标注的内容”则配合excludeInternal选项其机制见 defaults.ts 中各默认值与 CommentPlugin 的isHidden判定。顺带一提在中文本地化中该标签的标题被翻译为“私有备注”见 zh.ts 中的tag_privateRemarks: 私有备注——当它未被排除而渲染出来时中文文档中会显示该标题。七、小结privateRemarks是 TSDoc 标准块级标签用于书写不进入 API 参考的内部备注TypeDoc 通过excludeTags选项的默认值defaults.ts将其剔除剔除动作由 CommentPlugin 在转换阶段完成一旦你自定义了--excludeTags默认值被整体替换必须自行把privateRemarks保留在列表中否则备注会泄漏到文档中该标签的受众是读源码的人TypeDoc 自身在 ReflectionSymbolId、Context 等处大量使用可作为写法范例。相关文档remarks标签、excludeTags选项、TSDoc 支持说明、标签总表。赞分享开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载相关推荐终极TypeDoc注释标签指南掌握50JSDoc和TSDoc标签的完整技巧终极TypeDoc注释标签指南掌握50JSDoc和TSDoc标签的完整技巧 TypeDoc是TypeScript项目的文档生成工具能够将代码中的注释转换为开发工具文档TypeDoc 的 JSDoc 注释兼容机制jsDocCompatibility 选项与 JSDoc 类型标签的实现原理TypeDoc 的 JSDoc 注释兼容机制jsDocCompatibility 选项与 JSDoc 类型标签的实现原理 本文以 TypeDoc 官方文档 J开发工具文档TypeDoc 标签体系详解TypeScript 项目文档注释中的 Block、Modifier 与 Inline 标签TypeDoc 标签体系详解TypeScript 项目文档注释中的 Block、Modifier 与 Inline 标签 TypeDoc 允许开发者在 JSD开发工具文档上一篇动物森友会岛屿设计终极指南用Happy Island Designer打造你的梦幻小岛下一篇一键解决Windows更新问题的终极免费工具Script-Reset-Windows-Update-Tool完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考