feat: AIP-192 – Documentation

aip/general/0192/aip.md

@@ -0,0 +1,122 @@
+# Documentation
+
+Documentation is one of the most critical aspects of API design. Users of your
+API are unable to dig into the implementation to understand the API better;
+often, the API surface definition and its corresponding documentation will be
+the only things a user has. Therefore, it is important that documentation be as
+clear, complete, and unambiguous as possible.
+
+## Guidance
+
+In APIs defined in protocol buffers, public comments **must** be included over
+every component (service, method, message, field, enum, and enum value) using
+the comment format provided by your IDL. This is important even in cases where
+the comment is terse and uninteresting, as numerous tools read these comments
+and use them.
+
+Services, in particular, **should** have descriptive comments that explain what
+the service is and what users are able to do with it.
+
+**Note:** Many readers will not be native English speakers. Comments **should**
+avoid jargon, slang, complex metaphors, pop culture references, or anything
+else that will not easily translate. Additionally, many readers will have
+different backgrounds and viewpoints; if writing examples involving people,
+comments **should** use people who are non-controversial and no longer alive.
+
+### Style
+
+Comments **should** be in grammatically correct American English. However, the
+first sentence of each operation comment **should** omit the subject and be in
+the third-person present tense:
+
+```typescript
+// An API for managing the inventory for a library: Users may create, read,
+// and otherwise manipulate the library's inventory of books.
+interface Library {
+  // Creates a book under the given publisher.
+  createBook(request: CreateBookRequest): Book;
+}
+```
+
+### Descriptions
+
+Descriptions of messages and fields **should** be brief but complete. Sometimes
+comments are necessarily perfunctory because there is little to be said;
+however, before jumping to that conclusion, consider whether some of the
+following questions are relevant:
+
+- What is it?
+- How do you use it?
+- What does it do if it succeeds? What does it do if it fails?
+- Is it idempotent?
+- What are the units? (Examples: meters, degrees, pixels)
+- What are the side effects?
+- What are common errors that may break it?
+  - What is the expected input format?
+  - What range of values does it accept? (Examples: `[0.0, 1.0)`, `[1, 10]`)
+    - Is the range inclusive or exclusive?
+  - For strings, what is the minimum and maximum length, and what characters
+    are allowed?
+    - If a value is above the maximum length, do you truncate or send an error?
+- Is it always present? (Example: "Container for voting information. Present
+  only when voting information is recorded.")
+- Does it have a default setting? (Example: "If `page_size` is omitted, the
+  default is 50.")
+
+### Formatting
+
+Any formatting in comments **must** be in [CommonMark][]. Headings and tables
+**must not** be used, as these cause problems for several tools, and are
+unsuitable for client library reference documentation.
+
+Comments **should** use `code font` for property names and for literals (such
+as `true`).
+
+Raw HTML **must not** be used.
+
+### External links
+
+Comments **may** link to external pages to provide background information
+beyond what is described in the public comments themselves. External links
+**must** use absolute (rather than relative) URLs, including the protocol
+(usually `https`), and **should not** assume the documentation is located on
+any particular host. For example:
+`[Spanner Documentation](https://cloud.google.com/spanner/docs)`
+
+### Trademarked names
+
+When referring to the proper, trademarked names of companies or products in
+comments, acronyms **should not** be used, unless the acronym is such dominant
+colloquial use that avoiding it would obscure the reference (example: [IBM][]).
+
+Comments **should** spell and capitalize trademarked names consistent with the
+trademark owner's current branding.
+
+### Internal comments
+
+<!-- TODO: This does not work outside of Google.
+           We should probably try to get that fixed. -->
+
+Comments **may** be explicitly marked as internal by wrapping internal content
+in `(--` and `--)`.
+
+Non-public links, internal implementation notes (such as `TODO` and `FIXME`
+directives), and other such material **must** be marked as internal.
+
+**Note:** In IDLs using code comment syntax, comments **should** use only
+leading comments (not trailing comments or detached comments). In particular,
+comments **must not** use both a leading and trailing comment to describe any
+component, because this is a common source of inadvertent omissions of the
+internal content annotation.
+
+[commonmark]: https://commonmark.org/
+[ibm]: https://en.wikipedia.org/wiki/IBM
+
+## Changelog
+
+- **2020-04-01**: Added guidance requiring absolute URLs for external links.
+- **2020-02-14**: Added guidance around the use of trademarked names.
+- **2019-09-23**: Added guidance about not using both leading and trailing
+  comments.
+- **2019-08-01**: Changed the examples from "shelves" to "publishers", to
+  present a better example of resource ownership.

aip/general/0192/aip.yaml

@@ -0,0 +1,7 @@
+---
+id: 192
+state: approved
+created: 2019-07-25
+placement:
+  category: polish
+  order: 20