This section provides guidelines for adding inline documentation to your API. Most APIs will also have overviews, tutorials, and higher-level reference documentation, which are outside the scope of this Design Guide. For information on API, resource, and method naming, see Naming Conventions.
Comment format in proto files
Add comments to your .proto
file using the usual Protocol Buffers //
comment format.
// Creates a shelf in the library, and returns the new Shelf.
rpc CreateShelf(CreateShelfRequest) returns (Shelf) {
option (google.api.http) = { post: "/v1/shelves" body: "shelf" };
}
Comments in service configuration
As an alternative to adding documentation comments to your .proto
file, you can add inline documentation to your API in its YAML service
configuration file.
Documentation in this file will take precedence over documentation in
your .proto
if the same element is documented in both files.
documentation:
summary: Gets and lists social activities
overview: A simple example service that lets you get and list possible social activities
rules:
- selector: google.social.Social.GetActivity
description: Gets a social activity. If the activity does not exist, returns Code.NOT_FOUND.
...
You may need to use this approach if you have multiple services that use
the same .proto
files and want to provide service-specific
documentation. YAML documentation rules also let you add a more detailed
overview
to your API description. However, in general adding
documentation comments to your .proto
is preferred.
As with .proto
comments, you can use Markdown to provide additional
formatting in your YAML file comments.
API description
The API description is a phrase starting with an active verb that
describes what you can do with the API. In your .proto
file, an API
description is added as a comment to the corresponding service
, as in
the following example:
// Manages books and shelves in a simple digital library.
service LibraryService {
...
}
Here are some more example API descriptions:
- Shares updates, photos, videos, and more with your friends around the world.
- Accesses a cloud-hosted machine learning service that makes it easy to build smart apps that respond to streams of data.
Resource description
A resource description is a partial sentence that describes what the
resource represents. If you need to add more detail, use additional
sentences. In your .proto
file, a resource description is added as a
comment to the corresponding message type, as in the following example:
// A book resource in the Library API.
message Book {
...
}
Here are some example resource descriptions:
- A task on the user's to-do list. Each task has a unique priority.
- An event on the user's calendar.
Field and parameter descriptions
A noun phrase that describes a field or parameter definition, as shown in the following examples:
- The number of topics in this series.
- The accuracy of the latitude and longitude coordinates, in meters. Must be non-negative.
- Flag governing whether attachment URL values are returned for
submission resources in this series. The default value for
series.insert
istrue
. - The container for voting information. Present only when voting information is recorded.
- Not currently used or deprecated.
Field and parameter descriptions should describe what values are valid and invalid. Remember that engineers will do their best to break any service, and will not be able to read the underlying code to clarify any unclear information.
For strings, the description should describe the syntax and permissible characters, as well as any required encoding. For example:
- 1-255 characters in the set [A-a0-9]
- A valid URL path string starting with / that follows the RFC 2332 conventions. Max length is 500 characters.
The description should specify any default value or behavior, but may omit describing default values that are effectively null.
If the field value is required, input only, output only, it should be documented at the start of the field description. By default, all fields and parameters are optional. For example:
message Table {
// Required. The resource name of the table.
string name = 1;
// Input only. Whether to validate table creation without actually doing it.
bool validate_only = 2;
// Output only. The timestamp when the table was created. Assigned by
// the server.
google.protobuf.Timestamp create_time = 3;
// The display name of the table.
string display_name = 4;
}
Method description
A method description is a sentence indicating what effect the method has and what resource it operates on. It usually starts with a third-person, present tense verb, i.e., in English, a verb ending in "s". If you need to add more details, use additional sentences. Here are some examples:
- Lists calendar events for the authenticated user.
- Updates a calendar event with the data included in the request.
- Deletes a location record from the authenticated user's location history.
- Creates or updates a location record in the authenticated user's location history using the data included in the request. If a location resource already exists with the same timestamp value, the data provided overwrites the existing data.
Checklist for all descriptions
Make sure each description is brief but complete and can be understood
by users who don't have additional information about the API. In most
cases, there's more to say than just restating the obvious; for example,
the description of the series.insert
method shouldn't just say
"Inserts a series." — while your naming should be informative, most
readers are reading your descriptions because they want more information
than the names themselves provide. If you're not sure what else to say
in a description, try answering all of the following questions that are
relevant:
- What is it?
- What does it do if it succeeds? What does it do if it fails? What can cause it to fail, and how?
- Is it idempotent?
- What are the units? (Examples: meters, degrees, pixels.)
- What range of values does it accept? Is the range inclusive or exclusive?
- What are the side effects?
- How do you use it?
- What are common errors that may break it?
- Is it always present? (For example: "Container for voting information. Present only when voting information is recorded.")
- Does it have a default setting?
Conventions
This section lists some usage conventions for textual descriptions and
documentation. For example, use "ID" (all caps), rather than "Id" or
"id" when talking about identifiers. Use "JSON" rather than "Json" or
"json" when referring to that data format. Show all field/parameter
names in code font
. Put literal string values in code font
and
quotes.
- ID
- JSON
- RPC
- REST
property_name
or"string_literal"
true
/false
Requirement levels
To set expectations or state requirement levels, use the terms: must, must not, required, shall, shall not, should, should not, recommended, may, and optional.
The meanings are defined in RFC 2119. You might want to include the statement from the RFC abstract in your API documentation.
Determine which term meets your requirements while giving developers flexibility. Don't use absolute terms like must when other options technically work in your API.
Language style
As in our naming conventions, we recommend using a simple, consistent vocabulary and style when writing doc comments. Comments should be understandable by readers who don't speak English natively, so avoid jargon, slang, complex metaphors, pop culture references, or anything else that won't easily translate. Use a friendly, professional style that speaks directly to the developers reading your comments, and keep things as concise as possible. Remember, most readers want to find out how to do something with your API, not read your documentation!