开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载TypeDoc 的{include}标签族允许你在 TSDoc 文档注释或外部 Markdown 文档中直接嵌入仓库里的其他文件内容{include}用于引入 Markdown 文本{includeCode}用于以代码块形式引入任意文件自动按扩展名选择高亮语言。本文基于 官方标签文档 与 IncludePlugin 源码 展开帮助你掌握整文件引入、命名区域region截取、行号截取三种用法并理解其路径解析、循环引用检测与错误处理机制从而在项目中组织出可复用、可维护的长文档。1. 两个标签的定位都是 Inline 标签{include}与{includeCode}在 TypeDoc 中被归类为 Inline 标签。它们在 TSDoc 的解析阶段被注册为合法的 inline 标签——可以在 默认标签列表 中看到export const tsdocInlineTags [link, inheritDoc, label] as const; export const inlineTags [ ...tsdocInlineTags, linkcode, linkplain, include, includeCode, ] as const;两者的核心区别在于替换后的内容形态{include path}把标签整体替换为指定文件中的Markdown 内容并会对其继续做 TSDoc 解析包括递归解析其中嵌套的include/includeCode标签。{includeCode path}把标签替换为一个fenced code block代码语言取自文件扩展名用于语法高亮区域内容还会做去缩进dedent处理。注意来自官方文档include和includeCode中的路径必须使用POSIX 风格的正斜杠/不能使用 Windows 风格的反斜杠\。2. 基本用法官方文档 给出的标准示例如下展示了两种标签与example标签共存时的注意事项/** * {include ./doSomething_docs.md} * * Quick start: * {includeCode ../examples/doSomethingQuickStart.ts} * * example * This will only work if the jsdocCompatibility.exampleTag option is false * {includeCode ../test/doSomething.test.ts} */ function doSomething() {}其中涉及的一个配套选项是 jsdocCompatibility文档明确提示example的行为在jsdocCompatibility.exampleTag选项为false时才按上述方式工作如果你在项目中启用了 JSDoc 兼容模式测试用例的引入方式需要先确认该选项的取值。除了成员注释{include}同样可用于独立文档standalone Markdown 文档。TypeDoc 仓库的示例站点就是一个真实用例example/src/index.ts 通过document documents/include.md把一个独立 Markdown 文件挂到模块文档上example/src/documents/include.md 页面正文通过一行{include ./include-code.md}把整页内容从 include-code.md 引入include-code.md 又演示了{includeCode ../reexports.ts}整文件引入以及{include ../../../site/tags/include.md#includePartsOfFiles}这种“从官方文档页按区域反向引用”的用法。这套示例说明了一个典型工作流把长篇幅教程写在独立.md文件中再用document关联 include组装而不是把所有内容堆在注释里。3. 引入文件的一部分命名区域Regions整文件引入往往不是最优解——你通常只想截取某个函数、某段配置。TypeDoc 支持在文件路径后追加#regionName来引入命名区域{includeCode ../../example/src/enums.ts#simpleEnum}要点与官方文档一致可指定多个区域用逗号分隔TypeDoc 会把它们合并进同一个代码块{includeCode file.ts#region1,region2}区域在源文件内用注释定义例如 TypeScript 中// #region simpleEnumRegion // #region simpleEnum export enum Example { /* ... */ } // #endregion simpleEnum // #endregion simpleEnumRegion仓库中的 example/src/enums.ts 就定义了simpleEnum/simpleEnumRegion区域官方文档页直接以{includeCode ../../example/src/enums.ts#simpleEnum}引用它——TypeDoc 自己的文档站就是该功能的 dogfooding 实例。区域语法的设计目标是与 VS Code 的折叠Folding语法兼容不同语言的区域写法如下源自官方文档表格LanguageStart regionEnd regionBat::#region regionNameorREM #region regionName::#endregion regionNameorREM #endregion regionNameC##region regionName#endregion regionNameC/C#pragma region regionName#pragma endregion regionNameCSS/Less/SCSS/*#region regionName*//*#endregion regionName*/Coffeescript#region regionName#endregion regionNameF#//#region regionNameor(#_region) regionName//#endregion regionNameor(#_endregion) regionNameJava//#region regionNameor//editor-fold regionName//#endregion regionNameor///editor-fold regionNameMarkdown!-- #region regionName --!-- #endregion regionName --Perl5#region regionNameorpod regionName#endregion regionNameorcut regionNamePHP#region regionName#endregion regionNamePowerShell#region regionName#endregion regionNamePython#region regionNameor# region regionName#endregion regionNameor# endregion regionNameTypeScript/JavaScript//#region regionName//#endregion regionNameVisual Basic#Region regionName#End Region regionName从源码结构看这套映射实现在 IncludePlugin.ts 的regionTagREsByExt中每个文件扩展名对应一组“区域起始正则 / 区域结束正则”例如ts与js/mjs/tsx等共用//#region 名称模式java额外支持//editor-foldmd支持 HTML 注释形式site/tags/include.md 中!-- #region includePartsOfFiles --的用法即基于此。对于源码未覆盖的扩展名插件会报出“regions are not supported for this file extension”错误这一点可由测试 unsupportedExtension.ts 验证。4. 引入文件的一部分行号当你无法在目标文件中添加区域注释比如 JSON 文件可以改用行号引用{includeCode ../../package.json:2,6-7}语法规则与官方文档一致冒号:分隔文件路径与行号部分行号是一个逗号分隔的数字或区间列表区间形式为start-end如6-7两端包含行号从 1 开始不是 0与大多数代码编辑器一致。⚠️ 官方文档的警告行号引用应当尽量避免因为源文件一旦改动引用很容易失效。从源码看行号解析与校验逻辑集中在parseIncludeCodeTextPart与getLines先按#判定为区域否则按:判定为行号start end会报“invalid range”行号超出文件实际行数会报“the file only has N lines”。这些边界行为都有对应测试用例invalidLineRanges.ts 覆盖了100-200超界、200-100逆序区间、300超界单行三种错误输入断言逻辑则见 behavior.c2.test.ts 中的相关用例。5. 实现原理IncludePlugin 的工作流程理解 IncludePlugin.ts 的核心实现有助于预判各种边界情况。5.1 触发时机插件在转换器创建多种 Reflection 时都会介入见构造函数owner.on(ConverterEvents.CREATE_PROJECT, onCreate); owner.on(ConverterEvents.CREATE_DOCUMENT, onCreate); owner.on(ConverterEvents.CREATE_DECLARATION, onCreate); owner.on(ConverterEvents.CREATE_PARAMETER, onCreate); owner.on(ConverterEvents.CREATE_SIGNATURE, onCreate); owner.on(ConverterEvents.CREATE_TYPE_PARAMETER, onCreate);这解释了为什么{include}不仅出现在成员注释里也能用于独立文档CREATE_DOCUMENT、函数参数CREATE_PARAMETER、签名CREATE_SIGNATURE等所有携带注释的 Reflection。5.2 路径解析相对“包含者”而非当前目录这是实际使用中最容易踩坑的一点。onCreate 方法 中if (refl.isDocument()) { const relative this.application.files.getReflectionPath(refl)!; this.checkIncludeTagsParts(refl, path.dirname(relative), refl.content); } if (!refl.comment?.sourcePath) return; const relative path.dirname(refl.comment.sourcePath); this.checkIncludeTagsParts(refl, relative, refl.comment.summary);独立文档中的include相对该文档所在目录解析成员注释中的include相对注释所在源文件的目录解析被引入文件内部若再嵌套include其相对路径则继续相对被引入文件的目录解析见 checkIncludeTagsParts 的递归调用。另外被引用的文件会通过this.application.watchFile(file)注册进文件监视增量构建时源文件变化能触发重新生成。5.3 两种标签的替换逻辑对include插件把文件内容包进MinimalSourceFile后调用parseRawComment按 TSDoc 规则解析成展示片段CommentDisplayPart再原地 splice 替换该 inline tag 节点并对解析出的片段递归执行同样的 include 检查included参数传递已引入文件栈。对includeCode则把节点替换为一个kind: code的展示片段内容由makeCodeBlock生成function makeCodeBlock(lang: string, code: string) { const escaped code.replace(/(?)/g, \u200B); return \n\n lang \n escaped.trimEnd() \n; }注意两个细节语言标识即文件扩展名对连续反引号插入了零宽空格防止代码内容中出现 破坏围栏。同时区域内容在includeCode场景下会经过dedent()去除公共缩进getRegions 末尾因此从带缩进的源文件中截取的方法体片段会以顶格形式出现在代码块中——测试 includeTagDedent.ts 专门验证了这一行为。5.4 循环引用检测include会递归解析内容因此存在 A 引 B、B 又引 A 的风险。插件维护included文件栈检测到include再次引用栈中文件时直接报**循环引用circular include**错误源码。测试用例 circularInclude.ts 覆盖了该场景。includeCode因为是纯文本引入、不做 TSDoc 递归解析则不受此限制。6. 错误与警告行为速查结合 behavior.c2.test.ts 的断言与 includeTag 测试目录 的输入文件各失败场景的日志行为如下可用于排查生成文档时的警告场景日志级别对应测试文件区域在文件中不存在#noRegionerrorregion was not found in the filemissingRegion.ts只有区域开始注释、缺少结束注释errorregion opening comment was found, closing not found同上区域开始/结束注释各出现多次errorfound multiple times in the fileduplicateRegion.ts区域存在但内容为空warnregion found but it is emptyemptyRegion.ts文件扩展名不支持区域语法errorregions are not supported for this file extensionunsupportedExtension.ts行号区间逆序200-100或超出文件长度errorinvalid range / the file only has N linesinvalidLineRanges.ts引用的文件不存在或不是文件errorresolved to ... does not exist or is not a fileinvalidInclude.ts多个区域合并进一个代码块正常行为includeTagMultipleRegions.ts区域 行号的基础引入正常行为includeTag.ts另有一个真实问题回归用例 gh2800.ts 使用了{includeCode ./gh2800.ts}可作为整文件引入的参考。7. 实践建议综合官方文档与源码实现落地时建议优先用区域regions而非行号行号引用在文件变更后极易失效官方文档对此有明确警告区域注释与 VS Code 折叠兼容维护成本低。统一使用正斜杠路径跨平台环境下反斜杠路径不会被正确解析。把相对路径锚定到“包含者”写{include ./xxx.md}时路径相对的是当前文档/注释所在目录而非 TypeDoc 运行目录跨层引用时注意../的层级。长文档拆分策略用独立.md文件承载教程主体配合document关联再用{include}组装、{includeCode}嵌入示例代码示例站点 example/src/documents/ 下的include.md与include-code.md可直接参照。嵌套 include 要防止成环include会递归解析被引入文件中的标签循环引用会直接报错文档拆分时保持单向依赖。留意 jsdocCompatibility 选项example与 include 标签混用时需确认 jsdocCompatibility 选项的取值符合预期。延伸阅读jsdocCompatibility 选项Inline 标签总览IncludePlugin 完整实现include 行为测试用例集示例站点文档include.md、include-code.md赞分享开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载相关推荐TypeDoc include 与 includeCode 实战指南把外部 Markdown 与代码文件嵌入类型文档TypeDoc include 与 includeCode 实战指南把外部 Markdown 与代码文件嵌入类型文档 本文讲解 TypeDoc 的文档包含开发工具文档TypeDoc 文档中的代码引用include 与 includeCode 标签的用法、区域选取与源码实现全解TypeDoc 文档中的代码引用include 与 includeCode 标签的用法、区域选取与源码实现全解 在 TypeDoc 生成的文档站中API开发工具文档TypeDoc 外部文档指南用 document 标签与 projectDocuments 选项将独立 Markdown 文件纳入文档站TypeDoc 外部文档指南用 document 标签与 projectDocuments 选项将独立 Markdown 文件纳入文档站 在基于 TypeD开发工具文档上一篇Revel静态资源CDN配置提升全球访问速度下一篇如何使用KubePi实现多集群统一管理从安装到运维的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考