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

A comment can "link" to another component (service, method, message, field, enum, or enum value) as a Markdown reference link. The reference must be one of the following forms:

  • The fully-qualified name of the element e.g. [Book][google.example.v1.Book]
  • A scope-relative reference qualified e.g. [Sci-Fi genre][Genre.GENRE_SCI_FI]
  • An implied reference e.g. [Book][] which equates to [Book][Book]

These references are resolved as per name resolution rules.

Containing fields names must not be used in references. They will not resolve. The original definition must be referenced instead. For example, [author][Book.author.family_name] where author is a field of Book, will not resolve, but [author][Author.family_name] will.

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

  • 2024-10-29: Include cross-reference resolution rules.
  • 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.