---
name: docs-files-api
description: 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](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.
- **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 its `main` has no call sites
  for JSDoc to show at. If the script prints its usage, make the manual a
  `HELP` string 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
  `@see` link 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.