22 lines
1.2 KiB
Markdown
22 lines
1.2 KiB
Markdown
---
|
||
name: docs-files-api
|
||
description: 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](https://github.com/Agoric/agoric-sdk/blob/master/packages/portfolio-contract/CONTRIBUTING.md#documentation-conventions)):
|
||
|
||
- **File comments:** Use a 1–2 line `@file` summary rather than a long file
|
||
header essay. Include `@see` links 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
|
||
`@see` link 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. |