---
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 `@file` comment is the script's manual: 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. 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
  `@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.