63 lines
3.6 KiB
Markdown
63 lines
3.6 KiB
Markdown
---
|
||
name: docs-files-api
|
||
description: Where docs go — README vs CONTRIBUTING vs AGENTS.md, and JSDoc placement — use when writing or reviewing a README, CONTRIBUTING, or AGENTS.md/CLAUDE.md; when someone asks "how do I run it?" and there's no README; 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
|
||
|
||
## README, CONTRIBUTING, AGENTS.md
|
||
|
||
A **README** sells, then gets the reader running:
|
||
|
||
- **Up top, about two sentences:** what it is and why to care. Then
|
||
straight to getting started.
|
||
- **Getting started:** get them to TADA! with no fuss. Readers skip to
|
||
the first fenced block and copy it; if it doesn't work, boo. So that
|
||
block runs as-is from a fresh clone and ends with something to look
|
||
at (a URL, output). No architecture, no principles.
|
||
- **After that:** features and benefits, as much as earns its place.
|
||
|
||
Everything else goes in **CONTRIBUTING**: design, layout of the code,
|
||
how to test, conventions, deploying.
|
||
|
||
**AGENTS.md is a symlink to CONTRIBUTING.md** (likewise CLAUDE.md, if a
|
||
tool wants one). Good advice is good advice, for people and bots alike.
|
||
If agents need something people don't, give it a short section in
|
||
CONTRIBUTING.
|
||
|
||
## JSDoc
|
||
|
||
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. |