AIP-192
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 protocol buffers comment format. 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 comment should omit the subject and be in the third-person present tense:
// Creates a book under the given publisher.
rpc CreateBook(CreateBookRequest) returns (Book) {
option (google.api.http) = {
post: "/v1/{parent=publishers/*}/books"
body: "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 field or method names and for literals
(such as true
).
Raw HTML must not be used.
"ASCII art" attempts to present a diagram within the protos must not be used. The Markdown within the protos is consumed by a large number of renderers, and any ASCII art is very unlikely to be well-presented by all of them. If a diagram is useful in order to understand the API, include a link to a documentation page containing the diagram as an image.
Cross-references
Comments may "link" to another component (service, method, message, field,
enum, or enum value) by using the fully-qualified name of the element as a
Markdown reference link. For example: [Book][google.example.v1.Book]
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.
Deprecations
To deprecate a component (service, method, message, field, enum, or enum value),
the deprecated
option
must be set to true
, and the first line of the respective comment
must start with "Deprecated: "
and provide alternative solutions for
developers. If there is no alternative solution, a deprecation reason must
be given.
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: 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.
Changelog
- 2023-08-11: Expand deprecated comment requirement to all components.
- 2021-04-20: Added guidance for deprecated services and RPCs.
- 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.