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 property names and for literals (such as true).

Raw HTML must not be used.

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]

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

  • 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.