diff --git a/aip/general/0192/aip.md b/aip/general/0192/aip.md new file mode 100644 index 00000000..59bee80b --- /dev/null +++ b/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 + + + +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. diff --git a/aip/general/0192/aip.yaml b/aip/general/0192/aip.yaml new file mode 100644 index 00000000..b57febfa --- /dev/null +++ b/aip/general/0192/aip.yaml @@ -0,0 +1,7 @@ +--- +id: 192 +state: approved +created: 2019-07-25 +placement: + category: polish + order: 20