dmmulroy/overseer/jsdocs

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

Workflow

When updating public API JSDoc:

1. Inspect the declaration, implementation, nearby tests, and nearby JSDoc before editing.
2. Decide whether the task is a single API fix or a module refinement pass.
3. Rewrite comments into the required documentation shape while preserving correct facts and examples.
4. For module refinements, complex APIs, or APIs with related alternatives, run the @see and **Gotchas** audits.
5. Run the narrowest relevant validation.

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 import.meta.vitest
 * const result = example()
 * ```
 *
 * @category constructors
 * @since 1.0.0
 */

Prose Rules

• Use sober, practical prose.
• Write all public JSDoc prose in English.
• 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.
• Make the short description stand on its own. Do not rely on **When to use**

to make the API understandable.

• For functions and methods, prefer present-tense, action-first prose such as

Creates, Returns, Checks, Provides, Represents, Converts, Decodes, or Formats.

• For technical value exports, use consistent noun forms such as Schema for,

Layer that, Service that, Context reference that, or Constructors and matchers for.

• Avoid leading A or An for canonical technical nouns when the surrounding

module uses a standard noun family, for example prefer Schema for ... over A schema for ....

• Do not describe implementation mechanics when a public concept is clearer.

For example, prefer Constructors and matchers for ... over wording that only says an API uses Data.taggedEnum.

• Avoid generic purity or non-mutation remarks unless they document a real

surprise, caveat, or meaningful contrast with a mutating-looking API.

• 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.
• Prefer prose over bullet lists for single-item **Details**, **When to use**, or **Gotchas** sections. Use bullets only when there are two or more parallel facts, options, cases, or caveats.
• **When to use** describes the positive use case for the documented API. Do not use it as a routing section for sibling APIs. If neighboring APIs need to be mentioned, put that boundary in @see tag text instead.
• **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 clarifies the documented API's own use case.
• **When to use** must start with one of these practical guidance forms: Use to, Use when, Use as, or Use with. Avoid bullet lists and vague openers such as Use this... or Useful for....
• Prefer reader-centered **When to use** wording, especially Use when you ...,

when the sentence describes a user's goal. Avoid third-person noun-phrase subjects such as the input is ..., a service needs ..., or values should ... when they would become awkward in generated prompts.

• A good **When to use** sentence should still read naturally if reused as

a user intent prompt, for example after I need ... or I have ....

• Keep short and **When to use** distinct: the short description says what

the API is or does; **When to use** says when to choose it.

• Add internal @see tags only for semantically useful related public APIs.
• Write @see tag text as normal prose after the link; no special separator is required. Prefer forms like @see {@link otherApi} for ... when a short explanation helps.
• 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.
• Example titles should be short use-case phrases, not generic labels.
• Prefer gerund or action-noun titles that read naturally after for, for

example Parsing JSON, Creating a scoped runtime, or Comparing structs.

• Avoid imperative titles such as Parse JSON, vague labels such as Syntax

or Basic usage, and title-cased fragments such as String Ordering.

• Preserve canonical technical capitalization inside the phrase, such as

Option, Effect, Schema, DateTime, HashMap, Base64, and JSON.

• For multiple examples on the same API, make each title describe the distinct

use case shown by that example.

• Prefer examples with stable, deterministic output. Avoid assertions or

console.log comments that depend on stack traces, object inspection, Error formatting, concurrency order, timing, randomness, or environment-specific formatting. Examples may assume Node.js console formatting. Direct Set / Map output is acceptable when insertion order is deterministic and the expected output uses Node's format; otherwise demonstrate a stable property instead.

• 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}.
• Avoid overlinking in prose. Use {@link Symbol} only when navigation to

that symbol helps the reader choose or understand the API. For the API being documented, the module's central type, nearby obvious names, or repeated mentions, prefer plain code formatting such as Cause, Effect, or Context.

• 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.
• For low-level public values, prefer accurate categories such as symbols,

type IDs, or prototypes over compensating with verbose descriptions.

Example quality

Examples are optional. They should demonstrate:

• behavior or constraints that are not clear from the signature;
• meaningful composition with other public APIs;
• a realistic use case supported by repository tests or call sites; or
• useful type inference, narrowing, or overload behavior.

A good example:

• focuses on the documented API and includes only the context needed to

understand it;

• is a complete, self-contained TypeScript module without placeholders or

omitted setup;

• imports public APIs rather than internal modules or unrelated test helpers;
• uses stable, deterministic, bounded behavior and does not require network

access, external services, timing assumptions, randomness, or machine-specific state;

• demonstrates the meaningful result, with a concise expected-value comment

when useful; and

• uses explanatory prose only when the code cannot communicate an important

choice or caveat on its own.

Executable examples

• Mark runnable TypeScript fences with import.meta.vitest. Run changed examples from the repository root with pnpm doctest --run <source files>.
• Write each marked example as a complete isolated module. Import public APIs, define every runtime value, await asynchronous work, and keep execution deterministic and bounded.
• Prefer operation() // => expected over introducing a result binding used only by the assertion. Retain bindings for reuse, mutation, identity checks, or meaningful multi-step setup, and insert a blank line before a separate assertion block.
• Keep direct assertions on one line up to 120 characters. Use dense expected arrays such as [1, 2] and semantic Effect values such as Option.some(1) rather than console formatting.
• Preserve import.meta.vitest for type-level examples, but do not add tautological runtime assertions to them.
• Leave examples that register Vitest tests or suites as plain ````ts` fences because the doctest collector executes

runnable snippets inside tests. Call the registration API directly to show its intended top-level usage.

• Keep documentation-only snippets as plain ````ts` fences.

When reviewing existing examples:

1. Derive the example's use case and behavior from repository evidence. Inspect

the declaration, implementation, tests, call sites, and related APIs. Do not invent a scenario merely to retain an example.

1. Keep a correct, clear, high-value example without gratuitous rewriting.
2. Fix or replace an example when repository evidence supports a concise,

valuable version.

1. Remove an example when it is trivial, misleading, contrived, or requires more

scaffolding than the insight justifies. Also remove it when a good replacement would require guessing at a use case.

Prefer concise trailing // => assertions that keep the meaningful result visible; public documentation should not look like a test suite. Type-level examples may demonstrate inference or assignability without runtime assertions. For lazy APIs such as Effect, execute enough of the program to demonstrate the behavior unless the example's value is specifically type-level or construction-oriented.

If an example review exposes a likely implementation or type-definition bug, do not change runtime or API code as part of the documentation pass. Report the finding and do not present the suspected behavior as recommended usage.

Tag rules

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

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

Tag requirements by declaration kind:

• Root declarations require @category and stable-semver @since, and must

not use @default.

• Namespaces and declarations inside namespaces require stable-semver @since,

may use @category, and must not use @default.

• Member JSDoc is optional. When present, it follows the same prose and layout

rules, may use optional stable-semver @since, may use non-empty @default, and must not use @category.

• Any declaration may use @deprecated with a non-empty message and repeated

non-empty @see tags for semantically useful related public APIs.

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**, behavior details into **Details**, and real caveats into **Gotchas**.
4. Convert @example tags and loose ts fences into **Example** (Title) sections.
5. Preserve valid @see, @deprecated, @default, @category, and @since tags.
6. Remove @see tags that do not point to semantically useful related public APIs.
7. Replace redundant inline {@link ...} tags with plain code formatting when

the link target is already obvious from the current declaration or module.

1. Remove sections that would be empty.

Module refinement

When asked to refine an existing module: