dckc
7a9b25538b
What a declaration is or does goes in /** */ on it (IDEs show it at call sites and on hover); `//` is for the why of a line inside a body. The description gains the trigger: a `//` comment explaining a declaration. Generated-by: Claude Opus 5.5
1.7 KiB
1.7 KiB
name, description
| name | description |
|---|---|
| docs-files-api | JSDoc placement rules for TypeScript/JSDoc code — use when writing or reviewing code comments, JSDoc, or file headers; deciding where @file/@see links go; documenting exported symbols or external specs; when a `//` comment explains what a declaration is or does (it belongs in JSDoc). |
Documentation Conventions
JSDoc placement rules (from the portfolio-contract contributing notes):
- File comments: Use a 1–2 line
@filesummary rather than a long file header essay. Include@seelinks only for major entry points, and keep those links intra-file (e.g.{@link someExport}), not external URLs. - Entry-point JSDoc: Put the meaningful docs on the exported symbols — that's what shows up in IDE call sites. External URLs belong here when they define the canonical ABI/spec of the thing being exported.
- API docs are JSDoc, not
//: What a function, class, method, type, field, or constant is or does goes in a/** … */comment on its declaration — IDEs show it at call sites and on hover; a//line above the declaration shows nowhere.//is for implementation notes inside a body: the why of a non-obvious line, next to that line. - External design constraints: If a module is constrained by external
contracts, standards, or off-repo design docs, add a short JSDoc note with a
@seelink to the authoritative source at the relevant entry point(s).
In short: brief at the top of the file, meaty on exports (in JSDoc),
// only for the why inside bodies, @see to authoritative external
sources only where they define the contract.