The best way to control Claude Code, Codex and more from any computer or phone

main
md 100 lines 3.68 KB
Rendered Raw
1 # Tags, Modules, And Links
2
3 ## Declaration Shape
4
5 Use 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
34 Write practical English about the public concept, not its implementation. Start
35 functions and methods with a present-tense action such as `Creates`, `Returns`,
36 or `Converts`; match nearby noun families for values, such as `Schema for`,
37 `Layer that`, or `Service that`.
38
39 Optional non-empty sections appear once in this order: `**When to use**`,
40 `**Details**`, `**Gotchas**`. Separate descriptions, sections, examples, and
41 tags with exactly one blank line. Use prose for one fact and bullets for
42 parallel facts. Do not add other headings.
43
44 `**When to use**` states a positive use case distinct from the description and
45 begins with `Use to`, `Use when`, `Use as`, or `Use with`. Put sibling
46 comparisons in `@see`. Reserve `**Gotchas**` for concrete preconditions, edge
47 cases, surprising behavior, and important failure modes.
48
49 ## Tags
50
51 Declaration tags appear in this order:
52
53 1. `@deprecated`
54 2. `@default`
55 3. `@see`
56 4. `@stability`
57 5. `@category`
58 6. `@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 - Roots, export specifiers, and root namespaces require `@stability stable`,
69 `@stability unstable`, or `@stability experimental`. Use `unstable` when an
70 API may receive breaking changes in minor releases, `experimental` when it may
71 receive breaking changes across patch versions, and `stable` otherwise.
72 - Tag any API that exposes a third-party dependency `@stability unstable`: an
73 accessor to the underlying client or instance, options typed as the
74 dependency's options, constructors that accept its instances, re-exports of
75 it, and signatures that mention its types. Tag the whole module when it exists
76 to wrap the dependency; otherwise tag only the exposing declarations or
77 members. Runtime built-ins (Node, Bun, Deno, DOM) and framework types inherent
78 to a binding (React, Solid, Vue) are exempt.
79
80 Use canonical `**Example**` sections rather than `@example` tags or loose code
81 fences.
82
83 ## Modules And Links
84
85 When present, the first top-level JSDoc is the module block unless TypeScript
86 attaches it to a non-import first declaration. An `@internal` module is omitted.
87 Module prose does not use the declaration template. Its tags are optional
88 non-empty `@deprecated`, repeated non-empty `@see`, required `@stability`, then
89 required stable-semver `@since`. Its examples and links follow the declaration
90 contracts.
91
92 Inline `{@link Symbol}` targets must resolve to TypeScript symbols; use normal
93 Markdown links for URLs. Prefer code formatting when navigation does not help a
94 reader understand or choose the API.
95
96 Use `@see` only for a verified related public API: a close alternative,
97 inverse, complement, level variant, or closely returned, consumed, or
98 configured type. Explain non-obvious relationships. Exclude implementation
99 dependencies, broad concepts, example-only helpers, private APIs, and merely
100 lexical matches.