dckc
018339689b
Refines the program-script exception: when the script prints its usage, the manual is a HELP string constant under a one-line @file (JS has no docstrings), not a comment copied into code or re-read from source. Generated-by: Claude Opus 5.5
2.3 KiB
2.3 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. - 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.