---
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.