standard-jsdoc

name	standard-jsdoc
description	Write, insert, or update Effect public API JSDoc so it satisfies the standard-jsdoc oxlint rule. Use when adding or fixing JSDoc comments, resolving standard-jsdoc diagnostics, preparing docs for JSON extraction, or reviewing public API documentation.

Use this skill to write well-formed JSDoc for Effect public APIs.

Required documentation shape

Use a normal multiline JSDoc comment in TypeScript source:

/**
 * Short description as one paragraph.
 *
 * **When to use**
 *
 * Optional practical usage guidance.
 *
 * **Details**
 *
 * Optional details for complex APIs, options, overloads, or behavior.
 *
 * **Gotchas**
 *
 * Optional edge cases, footguns, or surprising behavior.
 *
 * **Example** (Short title)
 *
 * Optional prose explaining the example.
 *
 * ```ts
 * const result = example()
 * ```
 *
 * @category constructors
 * @since 1.0.0
 */

Writing rules

• Use sober, practical prose.
• Do not use jargon when a plain word works.
• Do not be clever.
• Do not add filler sections.
• The short description is required and must be exactly one paragraph.
• Optional sections must appear in this order:
  1. **When to use**
  2. **Details**
  3. **Gotchas**
• Include an optional section only when it has useful, non-empty content.
• **When to use** is important when the API has close alternatives, trade-offs, or @see tags. If @see tags are present, inspect the referenced APIs and add **When to use** when it helps readers choose between them.
• Add @see only for APIs that are similar to the documented API but intended for different situations or usage patterns. Do not add @see for loosely related helpers, dependencies, implementation details, or general background links.
• Before deciding whether to include **Gotchas**, inspect the implementation and nearby tests for edge cases, footguns, preconditions, surprising behavior, or important failure modes. Add **Gotchas** only when you find a real gotcha worth documenting.
• Use exactly one blank line between the short description, sections, examples, and tags.
• Do not use Markdown headings such as # Heading or ad hoc bold headings such as **Notes**; only the standard headings are allowed.
• Examples must use **Example** (Title), optional prose, and exactly one non-empty ts code fence.
• Example titles must be unique after trimming and lowercasing.
• Do not use @example.
• Do not put TypeScript code fences outside **Example** (Title) sections.
• Inline {@link Symbol} targets must resolve to TypeScript symbols; do not link to URLs with {@link}.
• Do not document module-level comments; module JSDoc is ignored by this rule.
• @internal means the item is ignored; do not rewrite it as public docs.
• Default exports are ignored by this rule and do not need JSDoc.
• Do not add unsupported constructs such as enums or empty exports in checked files.

Tag rules

When multiple tags are present, keep them in this order:

1. @deprecated
2. @default
3. @see
4. @category
5. @since

Root declarations:

• Require @category.
• Require @since with stable semver like 1.2.3.
• May use @deprecated with a non-empty message.
• May use repeated non-empty @see tags, but only for similar APIs with different usage patterns.
• Must not use @default.

Namespaces and declarations inside namespaces:

• Require @since with stable semver like 1.2.3.
• May use optional @category.
• May use @deprecated with a non-empty message.
• May use repeated non-empty @see tags, but only for similar APIs with different usage patterns.
• Must not use @default.

Members:

• JSDoc is optional.
• When member JSDoc is present, it must follow the same short description, section, example, spacing, and tag-order rules.
• May use optional @since with stable semver like 1.2.3.
• May use @default with a non-empty value.
• May use @deprecated with a non-empty message.
• May use repeated non-empty @see tags, but only for similar APIs with different usage patterns.
• Must not use @category.

Updating existing JSDoc

When fixing or updating existing docs:

1. Preserve correct facts and examples.
2. Rewrite the layout into the standard template.
3. Move usage guidance into **When to use**; when @see tags are present, inspect the referenced APIs and explain selection guidance if useful.
4. Move option, overload, and behavior details into **Details**.
5. Move caveats into **Gotchas**; if no caveat is already documented, inspect the implementation and nearby tests before deciding whether a **Gotchas** section is warranted.
6. Convert @example tags and loose ts fences into **Example** (Title) sections.
7. Preserve valid @see, @deprecated, @default, @category, and @since tags.
8. Remove @see tags that do not point to similar APIs with meaningfully different usage patterns.
9. Remove sections that would be empty.

Validation

After changing JSDoc governed by the rule, run the narrowest relevant validation:

pnpm test packages/tools/oxc/test/standard-jsdoc.test.ts
pnpm check:tsgo

If the changed package has generated docs, also run pnpm docgen from that package directory.