effect/docgen 实战指南Effect 项目 API 文档自动生成器的演进、配置与源码解析【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3codeeffect/docgen是 Effect 生态中面向 TypeScript 项目的“有主见”的文档生成器它扫描src目录中的源码与 JSDoc 注释自动校验示例代码tsc类型检查 tsx运行并输出带目录、按category分组的 Markdown 文档。本文以 .repos/effect-smol/packages/tools/docgen/CHANGELOG.md 为主线结合同目录下的 README.md、schema.json 与 src 源码系统讲解它的能力边界、配置项、命令行参数与内部实现流水线帮助你快速为 Effect 风格的项目接入并深度定制文档生成。一、它是什么从 changelog 与定位说起在 Effect 生态中库的 API 文档通常需要与源码保持同步。effect/docgen承担了这一任务它读取docgen.json配置扫描srcDir默认src下的 TypeScript 文件解析 JSDoc 注释把每个模块导出渲染成独立的 Markdown 页面并自动生成 GitHub Pages 所需的_config.yml、index.md、modules/index.md等站点骨架文件。其定位在 package.json 中写得很清楚——An opinionated documentation generator for Effect projects。README 也明确说明它受到docs-ts项目的启发。从版本号看它经历过两代生命周期0.x时代0.0.1→0.5.2作为独立包快速迭代随后在4.0.0-beta.102被整体迁入 Effect 单体仓库并升级到 Effect 4以4.0.0-rc.x的节奏与effect、effect/platform-node同步发版。需要特别说明的是CHANGELOG 中4.0.0-rc.104至4.0.0-rc.112之间的大多数条目是“Updated dependencies”即跟随effect4.0.0-rc.x与effect/platform-node4.0.0-rc.x的常规依赖升级真正承载功能信息的是0.x时代的 Patch/Minor 记录与4.0.0-beta.102/103/104的几条重要变更。理解这一点你就能从这份 changelog 中高效提取有效信息。二、从 CHANGELOG 看功能演进的关键里程碑1. 正式并入 Effect 仓库并适配 Effect 44.0.0-beta.102CHANGELOG 标注为Major Changes的只有一条Migrateeffect/docgeninto the Effect monorepo and update it to Effect 4 while retaining existing behavior.这是版本号从0.5.2直接跳到4.0.0-beta.102的原因为了与 Effect 主版本号对齐而不是语义化的 1.0 跳变。合并意味着它开始与effect、effect/platform-node使用同一套 workspace 依赖与发布节奏从 package.json 中的effect: workspace:^、effect/platform-node: workspace:^可以印证。同版本还有一个值得注意的 PatchAdd Record.assignProperty and safely handle dynamic record keys such as __proto__ and inherited property names——这与 Domain.ts 中Process服务读取process.env时的安全赋值实现直接对应源码使用Rec.assignProperty(env, key, value)而非普通对象赋值。2. 解析与校验能力的两次重要收紧4.0.0-beta.103该版本包含两条直接影响文档输出的变更Docgen now omitsinternaloption properties from generated signatures生成函数签名时会剔除带有internal标记的选项属性。这意味着你可以在公开函数签名里为内部选项打上internal注解生成的 API 文档会“看不见”它们实现“公开接口 内部扩展”的文档级隔离。Removed explicit./indexentrypoints包导出不再提供显式的./index子路径。对照 package.jsonexports中确实声明了./index: null、./bin: null这是对上一版本“移除显式入口”的落地。3. 0.x 时代的功能铺陈文档生成器核心能力成型0.x阶段的 changelog 记录了 docgen 主要能力的引入顺序理解这些条目能帮你把握它的设计脉络版本变更意义0.1.0把docs-ts.json重命名为docgen.json确立了配置文件命名0.1.4支持 namespaces清理/docs目录中的陈旧模块文件引入命名空间文档化并保证输出目录不残留过期文件0.1.5支持从 tsconfig 文件解析 compilerOptions解析器开始感知项目的 TypeScript 编译选项0.1.6修复 compilerOptions 解析引起的回归稳定 tsconfig 集成0.1.7支持export * from ...识别重导出语法0.1.8支持解析export * as namespace识别命名空间重导出0.2.0引入effect/platform-node依赖走向纯 Effect 实现0.3.0现代化改造基于tsctsx支持NodeNext模块解析示例的类型检查与执行机制定型0.3.1新增--no-examples选项命令行可关闭示例处理0.4.0使用ConfigProvider加载 docgen 配置配置系统改为 Effect Config 驱动源码见 Configuration.ts0.4.1上报tsc与tsx的错误信息示例失败时给出可读诊断0.4.2用effect/markdown-toc取代 GitHub 依赖生成目录目录生成内部化0.4.4升级ts-morph到 23.0.0修复srcDir/outDir被忽略的 bug配置项真正生效0.4.6支持 Extended Markdown 围栏代码块支持深层嵌套命名空间此前的错误是[Markdown] Unsupported namespace nesting: 4此后深度 ≥ 3 的命名空间标题改用 H4 渲染0.4.7 / 0.5.1对命名空间示例做类型检查支持深层命名空间中的示例检查示例校验覆盖面扩展0.5.0渲染示例时支持自定义代码围栏示例展示样式可定制0.5.2移除重复 logger输出更干净其中0.4.6的“深层嵌套命名空间”能力在 Core.ts 的extractPrefixedNestedNamespaces中有直接实现它递归遍历命名空间并用-拼接前缀如prefix-namespace用于为嵌套命名空间下的接口、类型别名、示例文件生成稳定的文件名与标题。4. 示例的类型检查与执行0.4.1、0.4.5、0.4.7、0.5.1CHANGELOG 中多条记录围绕“示例”展开这是effect/docgen区别于普通注释文档生成器的最大卖点example与描述中的 TS 代码块会被真实地类型检查甚至被真实运行。0.4.1上报tsc/tsx错误关闭 issue #660.4.5修复 Windows 上示例的类型检查与执行tsc可执行文件在 Windows 上是tsc.cmd0.4.7、0.5.1把类型检查逐步覆盖到命名空间及其深层嵌套的示例。在 Core.ts 中可以看到完整的实现runTscOnExamples以--noEmit --project outDir/examples/tsconfig.json调用tscWindows 下追加.cmd后缀并走 shellrunTsxOnExamples则以--tsconfig tsconfig index调用tsx运行示例入口。示例的编译选项来自配置的examplesCompilerOptions并写入outDir/examples/tsconfig.json见createExamplesTsConfigJson。三、快速上手安装、脚本与最小配置按 README.md 与 package.json 的要求Node.js 版本engines声明node 18.0.0README 中的警告块同样强调 Node v18 以上peer 依赖tsx 4.19.3 5.0.0、typescript 5.8.2 7.0.0当前仓库版本实际使用typescript ^6.0.3、tsx ^4.23.12开发。安装与接入npm install -D effect/docgenrc在package.json中添加脚本可选再建一个docgen.json{ scripts: { docgen: docgen }, devDependencies: { effect/docgen: 4.0.0-rc.112 } }最小配置文件只需声明 JSON Schema 引用即可获得编辑器校验与自动补全{ $schema: node_modules/effect/docgen/schema.json }然后运行npm run docgen。默认行为扫描src下全部**/*.ts在 Core.ts 中由readSourceFiles通过glob完成把生成的 Markdown 输出到docs目录。四、docgen.json 配置详解配置接口同时定义在 Configuration.ts 的ConfigurationSchema与 schema.json 中interface Config { readonly projectHomepage?: string readonly srcLink?: string readonly srcDir?: string readonly outDir?: string readonly theme?: string readonly enableSearch?: boolean readonly enforceDescriptions?: boolean readonly enforceExamples?: boolean readonly enforceVersion?: boolean readonly tscExecutable?: string readonly runExamples?: boolean readonly exclude?: ReadonlyArraystring readonly parseCompilerOptions?: string | Recordstring, unknown readonly examplesCompilerOptions?: string | Recordstring, unknown }各参数的目的与默认值参数作用默认值projectHomepage生成文档的 Auxiliary Links 中链接到的项目主页package.json的homepage字段srcLink生成文档中指向项目源码的链接{projectHomepage}/blob/main/src/srcDirdocgen 搜索 TypeScript 文件的目录srcoutDirMarkdown 输出目录docstheme写入生成_config.yml的 GitHub Pages 主题mikearnaldi/just-the-docs常量见 Configuration.tsenableSearch生成的_config.yml是否启用站点搜索trueenforceDescriptions是否强制每个模块导出都有描述falseenforceExamples是否强制每个模块导出都有example模块级文档不强制falseenforceVersion是否强制每个模块导出都有sincetruetscExecutable程序化调用编译器的可执行文件路径tscrunExamples是否实际运行示例代码并把输出写进文档false该字段同时存在于 schema 与 ConfigurationSchema但 README 配置表未列出excludeglob 数组排除不参与文档生成的源文件[]parseCompilerOptions解析源码时使用的编译器选项或指向 tsconfig 的路径{}examplesCompilerOptions类型检查/运行示例时使用的编译器选项或 tsconfig 路径{}README 中给出的完整示例配置路径映射部分请按你的项目名替换{ exclude: [src/internal/**/*.ts], parseCompilerOptions: { noEmit: true, strict: true, skipLibCheck: true, moduleResolution: Bundler, target: ES2022, lib: [ES2022, DOM], paths: { effect/project-name: [./src/index.js], effect/project-name/test/*: [./test/*.js], effect/project-name/examples/*: [./examples/*.js], effect/project-name/*: [./src/*.js] } }, examplesCompilerOptions: { noEmit: true, strict: true, skipLibCheck: true, moduleResolution: Bundler, target: ES2022, lib: [ES2022, DOM], paths: { effect/project-name: [../../src/index.js], effect/project-name/test/*: [../../test/*.js], effect/project-name/examples/*: [../../examples/*.js], effect/project-name/*: [../../src/*.js] } } }需要留意两处细节parseCompilerOptions/examplesCompilerOptions既可以是内联对象也可以是 tsconfig 文件路径字符串——Configuration.ts 的resolveCompilerOptions在值为字符串时会调用tsconfck.parse读取对应 tsconfig 的compilerOptions完全未配置时回退到内置的defaultCompilerOptionsnoEmit: true, strict: true, skipLibCheck: true, moduleResolution: Bundler, target: ES2022, lib: [ES2022, DOM]。配置存在优先级链CLI 显式参数 环境变量 docgen.json 内置默认值。Configuration.ts 的configProviderLayer构造了一个ConfigProvider环境变量以DOCGEN_为前缀如DOCGEN_ENABLE_SEARCH且环境变量优先于docgen.json。这正是 changelog0.4.0“use ConfigProvider to load configuration” 的落地。五、命令行参数全览CLI.ts 基于 Effect 的Command/Flag模块定义了完整的 CLI。除--homepage、--srcLink、--src、--out、--theme与配置文件对应外还有以下开关参数作用--disable-search/--enable-search显式关闭/开启生成站点的搜索--enforce-descriptions强制要求每个导出有描述--enforce-examples强制要求每个导出有example--no-enforce-version/--enforce-version关闭/开启强制since--run-examples除类型检查外还实际运行示例并把输出写入文档--exclude glob...指定排除的 glob 模式可多次传入--parse-tsconfig-file path解析源码用的 tsconfig 文件--parse-compiler-options json内联 JSON 形式的解析编译器选项--examples-tsconfig-file path示例用的 tsconfig 文件--examples-compiler-options json内联 JSON 形式的示例编译器选项注意两对互斥参数--parse-tsconfig-file与--parse-compiler-options不能同时使用--examples-tsconfig-file与--examples-compiler-options同理同时给出时CLI.ts 会直接抛出CliError.InvalidValue。内联选项以 JSON 字符串传入解析失败时也会得到带明确预期的报错。历史上0.3.1还曾提供--no-examples关闭示例处理但当前版本中该能力已由--exclude与配置取舍替代README 与 CLI 中均不再保留。六、支持的 JSDoc 标签标签作用默认行为category把模块导出分组到生成文档的对应分类下utilsexample提供使用示例所有示例会被tsc类型检查也可被tsx运行配合 Node 内置assert做即时测试—since标注某段源码最近更新的库版本—deprecated标记弃用代码生成文档中对名称加删除线falseinternal阻止为该代码块生成文档若tsconfig.json开启stripInternalTypeScript 也不会为其生成声明—ignore阻止为该代码块生成文档—internal的意义在4.0.0-beta.103得到强化——生成签名时会省略被标记为internal的选项属性见上文。ignore与internal的区别在于internal同时影响 TS 声明产出需stripInternal配合ignore纯粹是 docgen 层面的文档排除开关。七、源码级流水线一次 docgen 运行发生了什么入口 bin.ts 加载配置层与NodeServices调用cli真正的主流程在 Core.ts 的program中读取模块readSourceFiles用 glob 匹配srcDir/**/*.ts应用exclude并记录找到的模块数解析模块Parser.parseFiles把源码解析为Domain.ModuleDomain.ts 中的Module、Class、Interface、Function、TypeAlias、Constant、Namespace、Export等模型并行执行两条子 Fiber检查 FiberChecker.checkModules校验文档完整性依据enforceDescriptions/enforceExamples/enforceVersion随后typeCheckAndRunExamples负责示例的类型检查与可选的运行Markdown FibergetMarkdown生成index.md、modules/index.md、_config.yml按theme/enableSearch/projectHomepage渲染以及每个模块的 Markdown 页面writeMarkdown会先删除outDir/**/*.ts.md旧产物再写入合并等待Fiber.joinAll等两条子 Fiber 都完成后输出✓ Docs generation succeeded!任一条失败则抛出带模块名上下文的DocgenError。示例的完整处理链路Core.ts先清理outDir/examples目录getExampleFiles从模块文档、example标签中抽取围栏代码块按模块路径-类型-名称-序号.ts命名写入outDir/examples/并生成汇总index.ts入口与tsconfig.json依次执行tsc --noEmit --project examples/tsconfig.json与若runExamples开启tsx --tsconfig ... examples/index.ts完成后再次清理 examples 目录中间产物不落盘。代码块抽取规则在extractFencedCodeCore.ts同时支持与~~~围栏仅当围栏元数据以ts/typescript开头且不包含skip-type-checking时才纳入示例。因此你可以在示例围栏上写ts skip-type-checking // 这段代码不会被 docgen 纳入类型检查 未闭合的围栏会以 warning 形式记录。示例文件写入时被标记为可覆盖isOverwriteable: true而index.md、modules/index.md等骨架文件不可覆盖避免破坏已有站点结构。八、常见问题与限制函数重载如何文档化README 的 FAQ 明确回答不支持为每个重载分别写文档docgen 只使用函数第一个重载的文档。Windows 兼容tsc/tsx在 Windows 下以.cmd形式经 shell 调用Core.ts这是 changelog0.4.5修复的问题。命名空间深度0.4.6之前超过 3 层嵌套会报[Markdown] Unsupported namespace nesting: 4此后深度 ≥ 3 的命名空间标题统一用 H4 渲染。配置忽略历史0.4.4修复前srcDir/outDir实际不生效——如果是从旧版本升级请确认使用的是修复后的版本。示例质量保障example不是可选的“装饰”——在默认enforceVersion: true之外开启enforceExamples后文档生成会因缺少示例而失败把示例当作 CI 的一等公民来约束。九、小结effect/docgen的价值不在于“把注释变成 Markdown”而在于它把文档、示例、类型检查与真实运行绑定成一条流水线源码注释即文档源example即测试用例。通过 CHANGELOG.md 可以看到这条流水线一步步成型的过程——从命名空间支持、tsconfig 感知到tsc/tsx驱动的示例校验再到并入 Effect 仓库后的internal签名收敛与配置系统重构。若你的项目遵循 Effect 风格JSDoc category分组 since版本标记接入effect/docgen并配合enforceExamples与runExamples即可用最小的成本获得一份始终与源码同步、示例可验证的 API 文档。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
