Effect 公共 API 文档规范JSDoc 声明形状、标签顺序与链接约定实战指南【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect本文基于 effect 仓库的.agents/skills/jsdocs/文档体系系统讲解如何为 TypeScript 公共 API 编写统一、可校验、可被 doctest 执行的 JSDoc 文档。你将掌握声明块的标准结构When to use/Details/Gotchas/Example、标签deprecated/default/see/category/since的强制顺序与各声明层级约束以及模块块、{link}、see的链接规范并了解pnpm jsdocs --check校验与effect/doctest运行示例的完整工作流。背景为什么一套统一的公共 API 文档规范如此重要Effect 是一个用 TypeScript 构建生产级应用的开源项目其核心包packages/effect/src包含数百个模块、数千个公开声明。海量 API 若各自随意书写注释会带来三类问题检索与引用困难{link}指向模糊、see滥用导致 API 参考文档中链接 404 或指向无关声明写作风格混乱有的注释讲实现细节、有的只写函数二字读者无法快速判断何时使用、有什么坑示例不可验证文档中的代码片段可能是随手贴的伪代码无法保证与真实行为一致。为此仓库在.agents/skills/jsdocs/下沉淀了一整套文档规范declarations.md、categories.md、examples.md并配套jsdocs.config.json与工具链docgen、doctest、jsdocs 检查让文档成为可评审、可自动校验、可执行的工程资产。本文即围绕这套规范展开。声明形状Declaration Shape公共声明注释的标准骨架规范要求所有公共声明使用多行 JSDoc 块结构如下来自 declarations.md/** * Short description as one paragraph. * * **When to use** * * Optional practical usage guidance. * * **Details** * * Optional details for complex behavior. * * **Gotchas** * * Optional concrete caveats. * * **Example** (Parsing JSON) * * ts import.meta.vitest * operation() // expected * * * category constructors * since 1.0.0 */书写语言讲公共概念而非实现围绕公共概念写作而不是其内部实现函数与方法以现在时动作动词开头如Creates、Returns、Converts值类型value匹配邻近的名词族表达如Schema for、Layer that、Service that一个事实用散文prose并列事实用项目符号bullets除规范中的固定小节外不得添加其他标题。可选小节的出现顺序与语义可选的三个小节按以下顺序出现且每个小节至多出现一次小节语义写作要求**When to use**何时使用以Use to、Use when、Use as或Use with开头陈述一个与描述不同的正面用例**Details**复杂行为细节仅用于说明复杂行为**Gotchas**具体陷阱只写具体前提条件、边界情况、意外行为与重要失败模式规范特别强调兄弟/对照 API 的比较放在see中不要写进When to use**Gotchas**必须具体禁止泛泛而谈。分隔规则描述、小节、示例与标签之间恰好空一行。标签Tags顺序与各声明层级的约束标签在声明中的出现顺序是强制的见 declarations.mddeprecateddefaultseecategorysince按声明层级区分的规则声明层级sincecategorydefaultdeprecated/seeRoot模块根导出必需stable-semver必需规则见 categories.md禁止允许一个非空deprecated、可重复非空see命名空间及其内部声明必需stable-semver允许禁止同上成员member允许可选stable-semver禁止允许非空default同上任何声明———允许一个非空deprecated与可重复的非空see即Root 必须有since且不能有default成员注释是可选的一旦存在就必须遵循散文契约prose contract允许since和非空default但不允许category。示例部分用**Example**而非example规范明确示例应使用规范的**Example**小节而不是example标签或零散的裸代码块loose code fences。分类CategoriesRoot 声明的category约束Root 声明必须携带一个非空的category见 categories.md。分类书写要复用邻近模块已有的分类优先使用小写复数形式与动名词gerunds同时保留规范领域的大小写canonical domain casing。常见的分类族包括形状类Shapesconstructors、destructors、models、schemas、guards、predicates、getters、accessors、instances、constants、protocols、prototypes、re-exports、unsafe、testingEffect 类services、tags、layers、context、resource management、running、errors、error handling操作类Operationscombinators、filtering、mapping、sequencing、zipping、combining、merging、converting、transforming、folding、splitting、repetition共享类Sharedutility types、encoding、decoding、serialization、tracing、metrics、logging、annotations、references、symbols、type IDs、configuration、math、comparisons、ordering。分类边界避免概念混淆categories.md 强调以下语义边界services 是契约tags 标识服务layers 提供服务getters 取回值accessors 读取上下文errors 建模失败error handling 恢复或映射失败models 是领域数据utility types 是类型层契约guards 做类型收窄narrowpredicates 返回布尔值。模块与链接Modules And Links模块块、{link}与see模块块Module Block当存在时第一个顶层 JSDoc 即模块块除非 TypeScript 将其附加到第一个非 import 声明上internal模块省略不计模块散文不使用声明模板模块标签顺序可选的非空deprecated、可重复的非空see随后是必需的 stable-semversince模块的示例与链接遵循与声明一致的契约。行内链接与 URL行内{link Symbol}的目标必须解析为 TypeScript 符号URL 使用普通 Markdown 链接当导航无助于读者理解或选择 API 时优先使用代码格式化即用code代替链接。see的严格使用see只用于已验证的相关公共 API包括相近替代close alternative、逆操作inverse、互补complement、级别变体level variant密切返回、消费或配置的类型。需要解释不明显的关联关系并排除以下内容实现依赖implementation dependencies宽泛概念broad concepts仅供示例使用的辅助工具example-only helpers私有 APIprivate APIs仅词法上相似merely lexical matches的声明。示例规范Examples可执行文档的写法示例是可选的仅在以下情况保留或新增行为无法从签名直接看出有意义的组合composition有用的类型推断或收窄inference or narrowing。无意义、误导、牵强或脚手架过重的示例应替换或删除见 examples.md。结构要求使用**Example** (Unique use-case title)标题格式可加可选散文说明恰好一个非空ts代码栅栏标题在去空格、转小写后必须全局唯一。可运行栅栏与行内断言doctest 语法示例能否运行由effect/doctest支撑。给栅栏标记import.meta.vitest即可把示例抽取为独立的 Vitest 模块执行详见 packages/tools/doctest/README.md/** * ts import.meta.vitest nameadds two numbers * 1 1 // 2 * */ export const value 1在表达式末尾追加// 注释可进行行内断言期望值是一个 TypeScript 表达式按 Effect 的Equal.equals语义比较因此天然支持原始类型、数组、普通对象以及Option、Result、Exit、HashMap等 Effect 数据结构/** * ts import.meta.vitest * import { Array, Option } from effect * * Array.get([1, 2, 3], 1) // Option.some(2) * Array.get([1, 2, 3], 10) // Option.none() * */ export const value 1此外examples.md 还强调几条实战原则使用公共 import将较复杂的示例组织为准备setup→ 操作operation→ 语义观察semantic observation三段转换过程不会自动运行 Effect 或 await Promise优先使用await Effect.runPromise只有在文档契约本就声明同步执行时才使用Effect.runSync类型级示例保留可运行标记但不要添加同义反复tautological的运行时断言对于并发、中断、竞态场景使用Ref、Deferred或Queue作为观察工具不要引入可变探针mutable probes若研究示例过程中发现实现或类型 bug应上报问题而不是在纯文档任务中修改运行时代码。工作流与校验从写作到pnpm jsdocs --checkjsdocs技能见 SKILL.md给出了完整的文档编写工作流检查声明、实现、邻近 JSDoc、测试与调用点按需加载对应规范分支标签/模块/链接 →declarations.md分类 →categories.md示例 →examples.md做聚焦的 API 修复或模块打磨保留已验证事实与有价值的示例而非机械重写对于模块打磨或存在近似替代的 API审计see链接并从实现与测试中提炼具体的**Gotchas**运行pnpm jsdocs --check及所有适用的根级校验命令。internal声明与默认导出default exports不在公共 JSDoc 写作范围内受检文件不支持导出枚举exported enums与空导出声明。任务完成的标准是所有改动的公共声明满足对应规范、检查器通过、可运行示例通过定向 doctest、其余适用检查通过或明确报告未运行。仓库中的真实实践以Array.ts为样板上面的规范并非纸上谈兵仓库源码即是活样本。以 packages/effect/src/Array.ts 为例模块块与导出声明完全遵循本文规范/** * Works with JavaScript arrays, readonly arrays, and non-empty arrays. * * The helpers cover common collection work such as creating arrays, reading * elements, transforming values, sorting, grouping, splitting, combining, and * reducing many values to one result. Helpers that change contents return new * arrays and preserve non-empty array types when the result is guaranteed to * contain values. * * since 2.0.0 */模块块使用散文描述公共概念而非实现仅携带必需的since符合模块散文不使用声明模板的规定。再看一个公开导出/** * Exposes the global array constructor. * * **When to use** * * Use to access native JavaScript array constructor methods such as isArray * or from from the Effect module namespace. * * **Example** (Accessing the Array constructor) * * ts import.meta.vitest * import { Array } from effect * * Array.Array globalThis.Array // true * * * category constructors * since 4.0.0 */ export const Array globalThis.Array注意其中的每个细节描述以现在时动作Exposes开头**When to use**以Use to开头且与描述语义不同**Example**使用唯一标题、单个ts栅栏并标记import.meta.vitest使其可被 doctest 执行标签按category→since顺序排列此处无更靠前的deprecated/default/see。同文件中的类型声明则展示了category utility types的用法/** * Type lambda for ReadonlyArray, used for higher-kinded type operations. * * category utility types * since 2.0.0 */ export interface ReadonlyArrayTypeLambda extends TypeLambda { readonly type: ReadonlyArraythis[Target] }在整个packages/effect/src目录中category与since标记数以百计地分布在Array.ts、BigDecimal.ts、Channel.ts、Cause.ts、DateTime.ts、Graph.ts等模块中证明了这套规范的落地规模。工具链配置jsdocs 扫描范围仓库根目录的 jsdocs.config.json 定义了公共 API 文档的扫描范围tsconfig指向tsconfig.packages.json包含packages/**/src/*.ts与packages/**/src/**/*.ts排除node_modules、ai-docs、packages/tools/**、各包src/index.ts、StandardSchema.ts、*Generated.ts以及所有internal目录packages/**/src/internal/**输出到.data/jsdocs.json。这解释了规范中的一条隐含约定internal声明与内部实现目录不参与公共文档写作公共 JSDoc 只面向对外暴露的 API 面。写作自检清单完成公共 API 文档后建议按以下清单自查综合各规范文档形状是否为多行块描述是否一段自包含的实用散文可选小节是否按When to use→Details→Gotchas顺序且各至多一次语言函数/方法是否以现在时动作开头值类型是否匹配名词族散文与项目符号使用是否得当标签顺序是否为deprecated→default→see→category→since各层级root / namespace / member的允许项是否满足约束since是否 stable-semver示例是否使用规范的**Example** (唯一标题)与单个ts栅栏需要运行时验证的示例是否标记import.meta.vitest并正确使用// 断言链接{link Symbol}是否解析为真实 TS 符号see是否只指向验证过的相关公共 API且已排除实现依赖、宽泛概念与词法巧合校验运行pnpm jsdocs --check并通过适用检查可运行示例通过定向 doctest。这套规范的价值在于它把写注释从个人风格问题转化为可评审、可校验、可执行的工程约定——读者通过统一的When to use/Gotchas/Example结构快速决策工具通过category/since生成有序的 API 参考doctest 则保证文档示例与真实行为永远一致。【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Effect 公共 API 文档规范：JSDoc 声明形状、标签顺序与链接约定实战指南
Effect 公共 API 文档规范JSDoc 声明形状、标签顺序与链接约定实战指南【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect本文基于 effect 仓库的.agents/skills/jsdocs/文档体系系统讲解如何为 TypeScript 公共 API 编写统一、可校验、可被 doctest 执行的 JSDoc 文档。你将掌握声明块的标准结构When to use/Details/Gotchas/Example、标签deprecated/default/see/category/since的强制顺序与各声明层级约束以及模块块、{link}、see的链接规范并了解pnpm jsdocs --check校验与effect/doctest运行示例的完整工作流。背景为什么一套统一的公共 API 文档规范如此重要Effect 是一个用 TypeScript 构建生产级应用的开源项目其核心包packages/effect/src包含数百个模块、数千个公开声明。海量 API 若各自随意书写注释会带来三类问题检索与引用困难{link}指向模糊、see滥用导致 API 参考文档中链接 404 或指向无关声明写作风格混乱有的注释讲实现细节、有的只写函数二字读者无法快速判断何时使用、有什么坑示例不可验证文档中的代码片段可能是随手贴的伪代码无法保证与真实行为一致。为此仓库在.agents/skills/jsdocs/下沉淀了一整套文档规范declarations.md、categories.md、examples.md并配套jsdocs.config.json与工具链docgen、doctest、jsdocs 检查让文档成为可评审、可自动校验、可执行的工程资产。本文即围绕这套规范展开。声明形状Declaration Shape公共声明注释的标准骨架规范要求所有公共声明使用多行 JSDoc 块结构如下来自 declarations.md/** * Short description as one paragraph. * * **When to use** * * Optional practical usage guidance. * * **Details** * * Optional details for complex behavior. * * **Gotchas** * * Optional concrete caveats. * * **Example** (Parsing JSON) * * ts import.meta.vitest * operation() // expected * * * category constructors * since 1.0.0 */书写语言讲公共概念而非实现围绕公共概念写作而不是其内部实现函数与方法以现在时动作动词开头如Creates、Returns、Converts值类型value匹配邻近的名词族表达如Schema for、Layer that、Service that一个事实用散文prose并列事实用项目符号bullets除规范中的固定小节外不得添加其他标题。可选小节的出现顺序与语义可选的三个小节按以下顺序出现且每个小节至多出现一次小节语义写作要求**When to use**何时使用以Use to、Use when、Use as或Use with开头陈述一个与描述不同的正面用例**Details**复杂行为细节仅用于说明复杂行为**Gotchas**具体陷阱只写具体前提条件、边界情况、意外行为与重要失败模式规范特别强调兄弟/对照 API 的比较放在see中不要写进When to use**Gotchas**必须具体禁止泛泛而谈。分隔规则描述、小节、示例与标签之间恰好空一行。标签Tags顺序与各声明层级的约束标签在声明中的出现顺序是强制的见 declarations.mddeprecateddefaultseecategorysince按声明层级区分的规则声明层级sincecategorydefaultdeprecated/seeRoot模块根导出必需stable-semver必需规则见 categories.md禁止允许一个非空deprecated、可重复非空see命名空间及其内部声明必需stable-semver允许禁止同上成员member允许可选stable-semver禁止允许非空default同上任何声明———允许一个非空deprecated与可重复的非空see即Root 必须有since且不能有default成员注释是可选的一旦存在就必须遵循散文契约prose contract允许since和非空default但不允许category。示例部分用**Example**而非example规范明确示例应使用规范的**Example**小节而不是example标签或零散的裸代码块loose code fences。分类CategoriesRoot 声明的category约束Root 声明必须携带一个非空的category见 categories.md。分类书写要复用邻近模块已有的分类优先使用小写复数形式与动名词gerunds同时保留规范领域的大小写canonical domain casing。常见的分类族包括形状类Shapesconstructors、destructors、models、schemas、guards、predicates、getters、accessors、instances、constants、protocols、prototypes、re-exports、unsafe、testingEffect 类services、tags、layers、context、resource management、running、errors、error handling操作类Operationscombinators、filtering、mapping、sequencing、zipping、combining、merging、converting、transforming、folding、splitting、repetition共享类Sharedutility types、encoding、decoding、serialization、tracing、metrics、logging、annotations、references、symbols、type IDs、configuration、math、comparisons、ordering。分类边界避免概念混淆categories.md 强调以下语义边界services 是契约tags 标识服务layers 提供服务getters 取回值accessors 读取上下文errors 建模失败error handling 恢复或映射失败models 是领域数据utility types 是类型层契约guards 做类型收窄narrowpredicates 返回布尔值。模块与链接Modules And Links模块块、{link}与see模块块Module Block当存在时第一个顶层 JSDoc 即模块块除非 TypeScript 将其附加到第一个非 import 声明上internal模块省略不计模块散文不使用声明模板模块标签顺序可选的非空deprecated、可重复的非空see随后是必需的 stable-semversince模块的示例与链接遵循与声明一致的契约。行内链接与 URL行内{link Symbol}的目标必须解析为 TypeScript 符号URL 使用普通 Markdown 链接当导航无助于读者理解或选择 API 时优先使用代码格式化即用code代替链接。see的严格使用see只用于已验证的相关公共 API包括相近替代close alternative、逆操作inverse、互补complement、级别变体level variant密切返回、消费或配置的类型。需要解释不明显的关联关系并排除以下内容实现依赖implementation dependencies宽泛概念broad concepts仅供示例使用的辅助工具example-only helpers私有 APIprivate APIs仅词法上相似merely lexical matches的声明。示例规范Examples可执行文档的写法示例是可选的仅在以下情况保留或新增行为无法从签名直接看出有意义的组合composition有用的类型推断或收窄inference or narrowing。无意义、误导、牵强或脚手架过重的示例应替换或删除见 examples.md。结构要求使用**Example** (Unique use-case title)标题格式可加可选散文说明恰好一个非空ts代码栅栏标题在去空格、转小写后必须全局唯一。可运行栅栏与行内断言doctest 语法示例能否运行由effect/doctest支撑。给栅栏标记import.meta.vitest即可把示例抽取为独立的 Vitest 模块执行详见 packages/tools/doctest/README.md/** * ts import.meta.vitest nameadds two numbers * 1 1 // 2 * */ export const value 1在表达式末尾追加// 注释可进行行内断言期望值是一个 TypeScript 表达式按 Effect 的Equal.equals语义比较因此天然支持原始类型、数组、普通对象以及Option、Result、Exit、HashMap等 Effect 数据结构/** * ts import.meta.vitest * import { Array, Option } from effect * * Array.get([1, 2, 3], 1) // Option.some(2) * Array.get([1, 2, 3], 10) // Option.none() * */ export const value 1此外examples.md 还强调几条实战原则使用公共 import将较复杂的示例组织为准备setup→ 操作operation→ 语义观察semantic observation三段转换过程不会自动运行 Effect 或 await Promise优先使用await Effect.runPromise只有在文档契约本就声明同步执行时才使用Effect.runSync类型级示例保留可运行标记但不要添加同义反复tautological的运行时断言对于并发、中断、竞态场景使用Ref、Deferred或Queue作为观察工具不要引入可变探针mutable probes若研究示例过程中发现实现或类型 bug应上报问题而不是在纯文档任务中修改运行时代码。工作流与校验从写作到pnpm jsdocs --checkjsdocs技能见 SKILL.md给出了完整的文档编写工作流检查声明、实现、邻近 JSDoc、测试与调用点按需加载对应规范分支标签/模块/链接 →declarations.md分类 →categories.md示例 →examples.md做聚焦的 API 修复或模块打磨保留已验证事实与有价值的示例而非机械重写对于模块打磨或存在近似替代的 API审计see链接并从实现与测试中提炼具体的**Gotchas**运行pnpm jsdocs --check及所有适用的根级校验命令。internal声明与默认导出default exports不在公共 JSDoc 写作范围内受检文件不支持导出枚举exported enums与空导出声明。任务完成的标准是所有改动的公共声明满足对应规范、检查器通过、可运行示例通过定向 doctest、其余适用检查通过或明确报告未运行。仓库中的真实实践以Array.ts为样板上面的规范并非纸上谈兵仓库源码即是活样本。以 packages/effect/src/Array.ts 为例模块块与导出声明完全遵循本文规范/** * Works with JavaScript arrays, readonly arrays, and non-empty arrays. * * The helpers cover common collection work such as creating arrays, reading * elements, transforming values, sorting, grouping, splitting, combining, and * reducing many values to one result. Helpers that change contents return new * arrays and preserve non-empty array types when the result is guaranteed to * contain values. * * since 2.0.0 */模块块使用散文描述公共概念而非实现仅携带必需的since符合模块散文不使用声明模板的规定。再看一个公开导出/** * Exposes the global array constructor. * * **When to use** * * Use to access native JavaScript array constructor methods such as isArray * or from from the Effect module namespace. * * **Example** (Accessing the Array constructor) * * ts import.meta.vitest * import { Array } from effect * * Array.Array globalThis.Array // true * * * category constructors * since 4.0.0 */ export const Array globalThis.Array注意其中的每个细节描述以现在时动作Exposes开头**When to use**以Use to开头且与描述语义不同**Example**使用唯一标题、单个ts栅栏并标记import.meta.vitest使其可被 doctest 执行标签按category→since顺序排列此处无更靠前的deprecated/default/see。同文件中的类型声明则展示了category utility types的用法/** * Type lambda for ReadonlyArray, used for higher-kinded type operations. * * category utility types * since 2.0.0 */ export interface ReadonlyArrayTypeLambda extends TypeLambda { readonly type: ReadonlyArraythis[Target] }在整个packages/effect/src目录中category与since标记数以百计地分布在Array.ts、BigDecimal.ts、Channel.ts、Cause.ts、DateTime.ts、Graph.ts等模块中证明了这套规范的落地规模。工具链配置jsdocs 扫描范围仓库根目录的 jsdocs.config.json 定义了公共 API 文档的扫描范围tsconfig指向tsconfig.packages.json包含packages/**/src/*.ts与packages/**/src/**/*.ts排除node_modules、ai-docs、packages/tools/**、各包src/index.ts、StandardSchema.ts、*Generated.ts以及所有internal目录packages/**/src/internal/**输出到.data/jsdocs.json。这解释了规范中的一条隐含约定internal声明与内部实现目录不参与公共文档写作公共 JSDoc 只面向对外暴露的 API 面。写作自检清单完成公共 API 文档后建议按以下清单自查综合各规范文档形状是否为多行块描述是否一段自包含的实用散文可选小节是否按When to use→Details→Gotchas顺序且各至多一次语言函数/方法是否以现在时动作开头值类型是否匹配名词族散文与项目符号使用是否得当标签顺序是否为deprecated→default→see→category→since各层级root / namespace / member的允许项是否满足约束since是否 stable-semver示例是否使用规范的**Example** (唯一标题)与单个ts栅栏需要运行时验证的示例是否标记import.meta.vitest并正确使用// 断言链接{link Symbol}是否解析为真实 TS 符号see是否只指向验证过的相关公共 API且已排除实现依赖、宽泛概念与词法巧合校验运行pnpm jsdocs --check并通过适用检查可运行示例通过定向 doctest。这套规范的价值在于它把写注释从个人风格问题转化为可评审、可校验、可执行的工程约定——读者通过统一的When to use/Gotchas/Example结构快速决策工具通过category/since生成有序的 API 参考doctest 则保证文档示例与真实行为永远一致。【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考