git.giacomolli.uk - onehouse/blob - .agents/skills/docs/SKILL.md

   1 ---
   2 name: docs
   3 description: Docs and comment rules. Use before you write any prose.
   4 ---
   5
   6 # Documentation and comments
   7
   8 Change documentation and comments in the same change as the behavior,
   9 interface, or constraint that they describe.
  10
  11 ## Documentation
  12
  13 - `README.rst` is the entry point. It says what the project is and how
  14   to build, run, and check it. Keep it short.
  15 - `doc/` holds one document for each subject: a contract, an
  16   integration, or a device. Add to the document of the subject before
  17   you add a new document.
  18 - Use reStructuredText. Use Markdown only for files that a tool requires
  19   by name, such as `AGENTS.md` and `SKILL.md`.
  20 - Follow
  21   [Google's timeless documentation guide](https://developers.google.com/style/timeless-documentation).
  22   Describe what the checked-in code does. Do not use labels that depend
  23   on time, such as "new", "now", "currently", and "previously".
  24 - Follow
  25   [Google's tense guide](https://developers.google.com/style/tense). Use
  26   the present tense for general behavior. Use the future tense only when
  27   the timing of an action requires it, not for planned features.
  28 - Keep previous designs, development history, roadmaps, and future work
  29   in issues.
  30 - State exact support and limits instead of labels such as "prototype".
  31   Keep implemented, tested, and unverified behavior apart.
  32 - Keep safety requirements and known limits explicit. For example, say
  33   when emulator tests do not verify compatibility with the physical
  34   device.
  35 - Keep compatibility and old-schema details when the code or the
  36   migration tests require them. They describe an active contract, not
  37   history.
  38 - Do not remove a warning or claim support only to remove historical
  39   wording. Check the implementation and the tests before you change a
  40   claim.
  41 - Compare claims, examples, paths, and links with the implementation and
  42   the tests. Make sure that examples use supported interfaces and
  43   contain no secrets.
  44
  45 ## Lists
  46
  47 - Give each list item one paragraph only. Put a code block or a second
  48   paragraph after the list, because the formatters add an empty line
  49   between all items of a list that has one.
  50
  51 ## Comments
  52
  53 - A comment explains the declaration that it belongs to: the contract,
  54   invariants, non-obvious reasons, and required compatibility behavior.
  55   Do not repeat what the code shows or describe unrelated caller
  56   behavior.
  57 - State input constraints, results, errors, and concurrency or resource
  58   ownership rules when a caller needs them.
  59 - Keep a comment next to the code that it describes. Update or remove a
  60   comment when its code changes.
  61 - Write prose comments as continuous paragraphs, with one space between
  62   words and sentences. Do not use semicolons in prose.
  63 - Reflow each changed comment paragraph with `bin/reflow`. Do not reflow
  64   by hand or with your own editor configuration.
  65 - Give `bin/reflow` the first and the last line of the paragraph only.
  66   Lists, examples, and directives in a comment keep their line breaks.
  67
  68 This example reflows the comment on lines 12 to 15:
  69
  70 ```sh
  71 bin/reflow main.go 12 15
  72 ```
  73
  74 ## Go comments
  75
  76 - Follow [Go Doc Comments](https://go.dev/doc/comment). Write complete
  77   sentences. Start a declaration comment with the name of the symbol.
  78 - Do not write a package comment.
  79 - Document each exported declaration and its contract.
  80
  81 ## Swift comments
  82
  83 These rules apply to the iOS app in `ios/`. They follow the
  84 [Swift API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/)
  85 and Apple's
  86 [symbol documentation guide](https://developer.apple.com/documentation/xcode/writing-symbol-documentation-in-your-source-files).
  87
  88 - Use `///` for a documentation comment and `//` for an implementation
  89   comment.
  90 - Write a documentation comment for each type and for each member whose
  91   use is not clear from its name.
  92 - Start a documentation comment with a summary that ends with a period.
  93   For a function, say what it does and what it returns. For a type or a
  94   property, say what it is. The summary does not start with the symbol
  95   name, and it can be a sentence fragment.
  96 - Add `- Parameter`, `- Returns`, or `- Throws` only when the summary
  97   does not make them clear.
  98 - Describe the behavior of the code and the server API that it uses. Do
  99   not write which server features are missing or will come. Write what
 100   the app does without them, and put the missing feature in an issue.
 101 - Text that the app shows is not a code comment.