jsdocs

Write a multiline JSDoc comment with a one-paragraph short description, optional `**When to use**`, `**Details**`, and `**Gotchas**` sections in that order, `**Example** (Title)` sections with one ts code fence each, and ordered tags ending with `@category` and `@since`.

Inspect the declaration and existing comment, rewrite it into the required documentation shape while preserving correct facts and examples, then run `pnpm docgen` from the package directory and `pnpm lint` to confirm the diagnostics are resolved.

Only the standard sections are allowed: a short description, `**When to use**`, `**Details**`, `**Gotchas**`, and `**Example** (Title)` sections. Markdown headings and ad hoc bold headings like `**Notes**` are not permitted.

Use `@see` only for semantically useful related public APIs such as siblings, alternatives, or inverse operations. Do not link implementation dependencies, broad concepts, or APIs that merely share a name, and pair `@see` tags with `**When to use**` guidance when the use case is not obvious.

No. Module-level JSDoc is ignored by the rule, declarations marked `@internal` are skipped, and default exports do not require JSDoc. Only public root, namespace, and member declarations are checked.