dckc
5f9527a8f0
Comments say what the code is and why in the reader's terms: no traces of the design conversation, and nothing the code already says. Generated-by: Claude Opus 5.5
2.6 KiB
2.6 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. - Exception: program scripts (run directly: a shebang, or
import.meta.main). The manual goes at the top: a one-line purpose, a usage synopsis, the arguments, and what it writes or prints. People open a script to learn how to run it, and itsmainhas no call sites for JSDoc to show at. If the script prints its usage, make the manual aHELPstring constant right under a one-line@file(JavaScript has no docstrings; a string literal is the honest equivalent) rather than copying it or reading the script's own source. Helpers inside still get their own JSDoc. - Write for the reader, not the conversation: Comments say what the code is and why, in the reader's terms. No traces of how it came to be (design discussions, who asked, "for now", analogies used while deciding), and nothing the code or its shebang already says.
- 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.