1.2 KiB
1.2 KiB
name, description
| name | description |
|---|---|
| docs-files-api | JSDoc placement rules for TypeScript/JSDoc code — use when writing or reviewing JSDoc comments, deciding where @file/@see links go, or documenting external specs of exported symbols. |
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.
- 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, @see to
authoritative external sources only where they define the contract.