---
name: docs
description: Docs and comment rules. Use before you write any prose.
---

# Documentation and comments

Change documentation and comments in the same change as the behavior,
interface, or constraint that they describe.

## Documentation

- `README.rst` is the entry point. It says what the project is and how
  to build, run, and check it. Keep it short.
- `doc/` holds one document for each subject: a contract, an
  integration, or a device. Add to the document of the subject before
  you add a new document.
- Use reStructuredText. Use Markdown only for files that a tool requires
  by name, such as `AGENTS.md` and `SKILL.md`.
- Follow
  [Google's timeless documentation guide](https://developers.google.com/style/timeless-documentation).
  Describe what the checked-in code does. Do not use labels that depend
  on time, such as "new", "now", "currently", and "previously".
- Follow
  [Google's tense guide](https://developers.google.com/style/tense). Use
  the present tense for general behavior. Use the future tense only when
  the timing of an action requires it, not for planned features.
- Keep previous designs, development history, roadmaps, and future work
  in issues.
- State exact support and limits instead of labels such as "prototype".
  Keep implemented, tested, and unverified behavior apart.
- Keep safety requirements and known limits explicit. For example, say
  when emulator tests do not verify compatibility with the physical
  device.
- Keep compatibility and old-schema details when the code or the
  migration tests require them. They describe an active contract, not
  history.
- Do not remove a warning or claim support only to remove historical
  wording. Check the implementation and the tests before you change a
  claim.
- Compare claims, examples, paths, and links with the implementation and
  the tests. Make sure that examples use supported interfaces and
  contain no secrets.

## Lists

- Give each list item one paragraph only. Put a code block or a second
  paragraph after the list, because the formatters add an empty line
  between all items of a list that has one.

## Comments

- A comment explains the declaration that it belongs to: the contract,
  invariants, non-obvious reasons, and required compatibility behavior.
  Do not repeat what the code shows or describe unrelated caller
  behavior.
- State input constraints, results, errors, and concurrency or resource
  ownership rules when a caller needs them.
- Keep a comment next to the code that it describes. Update or remove a
  comment when its code changes.
- Write prose comments as continuous paragraphs, with one space between
  words and sentences. Do not use semicolons in prose.
- Reflow each changed comment paragraph with `bin/reflow`. Do not reflow
  by hand or with your own editor configuration.
- Give `bin/reflow` the first and the last line of the paragraph only.
  Lists, examples, and directives in a comment keep their line breaks.

This example reflows the comment on lines 12 to 15:

```sh
bin/reflow main.go 12 15
```

## Go comments

- Follow [Go Doc Comments](https://go.dev/doc/comment). Write complete
  sentences. Start a declaration comment with the name of the symbol.
- Do not write a package comment.
- Document each exported declaration and its contract.

## Swift comments

These rules apply to the iOS app in `ios/`. They follow the
[Swift API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/)
and Apple's
[symbol documentation guide](https://developer.apple.com/documentation/xcode/writing-symbol-documentation-in-your-source-files).

- Use `///` for a documentation comment and `//` for an implementation
  comment.
- Write a documentation comment for each type and for each member whose
  use is not clear from its name.
- Start a documentation comment with a summary that ends with a period.
  For a function, say what it does and what it returns. For a type or a
  property, say what it is. The summary does not start with the symbol
  name, and it can be a sentence fragment.
- Add `- Parameter`, `- Returns`, or `- Throws` only when the summary
  does not make them clear.
- Describe the behavior of the code and the server API that it uses. Do
  not write which server features are missing or will come. Write what
  the app does without them, and put the missing feature in an issue.
- Text that the app shows is not a code comment.