1# Tags, Modules, And Links
2
3## Declaration Shape
4
5Use a multiline JSDoc block for a public declaration:
6
7````ts
8/**
9 * Short description as one paragraph.
10 *
11 * **When to use**
12 *
13 * Optional practical usage guidance.
14 *
15 * **Details**
16 *
17 * Optional details for complex behavior.
18 *
19 * **Gotchas**
20 *
21 * Optional concrete caveats.
22 *
23 * **Example** (Parsing JSON)
24 *
25 * ```ts import.meta.vitest
26 * operation() // => expected
27 * ```
28 *
29 * @category constructors
30 * @since 1.0.0
31 */
32````
33
34Write practical English about the public concept, not its implementation. Start
35functions and methods with a present-tense action such as `Creates`, `Returns`,
36or `Converts`; match nearby noun families for values, such as `Schema for`,
37`Layer that`, or `Service that`.
38
39Optional non-empty sections appear once in this order: `**When to use**`,
40`**Details**`, `**Gotchas**`. Separate descriptions, sections, examples, and
41tags with exactly one blank line. Use prose for one fact and bullets for
42parallel facts. Do not add other headings.
43
44`**When to use**` states a positive use case distinct from the description and
45begins with `Use to`, `Use when`, `Use as`, or `Use with`. Put sibling
46comparisons in `@see`. Reserve `**Gotchas**` for concrete preconditions, edge
47cases, surprising behavior, and important failure modes.
48
49## Tags
50
51Declaration tags appear in this order:
52
531. `@deprecated`
542. `@default`
553. `@see`
564. `@stability unstable` or `@stability experimental` (when applicable)
575. `@category`
586. `@since`
59
60- Roots require stable-semver `@since` and no `@default`; category requirements
61 live in [categories.md](categories.md).
62- Namespaces and their declarations require stable-semver `@since`, permit
63 `@category`, and reject `@default`.
64- Member JSDoc is optional; when present it permits stable-semver `@since` and
65 non-empty `@default`, rejects `@category`, and follows the prose contract.
66- Any declaration permits one non-empty `@deprecated` and repeated non-empty
67 `@see` tags.
68- Use `@stability unstable` when an API may receive breaking changes in minor
69 releases, or `@stability experimental` when it may receive breaking changes
70 across patch versions. Leave the tag out for APIs that follow strict semver.
71- Tag any API that exposes a third-party dependency `@stability unstable`: an
72 accessor to the underlying client or instance, options typed as the
73 dependency's options, constructors that accept its instances, re-exports of
74 it, and signatures that mention its types. Tag the whole module when it exists
75 to wrap the dependency; otherwise tag only the exposing declarations or
76 members. Runtime built-ins (Node, Bun, Deno, DOM) and framework types inherent
77 to a binding (React, Solid, Vue) are exempt.
78
79Use canonical `**Example**` sections rather than `@example` tags or loose code
80fences.
81
82## Modules And Links
83
84When present, the first top-level JSDoc is the module block unless TypeScript
85attaches it to a non-import first declaration. An `@internal` module is omitted.
86Module prose does not use the declaration template. Its tags are optional
87non-empty `@deprecated`, repeated non-empty `@see`, optional `@stability unstable`
88or `@stability experimental`, then required stable-semver `@since`. Its examples
89and links follow the declaration contracts.
90
91Inline `{@link Symbol}` targets must resolve to TypeScript symbols; use normal
92Markdown links for URLs. Prefer code formatting when navigation does not help a
93reader understand or choose the API.
94
95Use `@see` only for a verified related public API: a close alternative,
96inverse, complement, level variant, or closely returned, consumed, or
97configured type. Explain non-obvious relationships. Exclude implementation
98dependencies, broad concepts, example-only helpers, private APIs, and merely
99lexical matches.