翻译自 API Design Guide - Documentation
这一章是为 API 添加内部文档的指南。大部分 API 有概述、教程和更高级别的参考文档（此指南不讨论）。API 名、资源名和方法名的信息请查看命名约定。
注释格式
在 .proto 文件中使用 // 来添加注释。
// 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" };
}
在服务配置中添加注释
作为在 .proto 文件中添加注释的替代方法，你可以在 API 的 YAML 服务配置文件中添加注释。如果两个文件中都记录了相同的元素，则该文件中的文档将优先于 .proto 中的文档
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.
...
当在一个 .proto 文件中有多个服务并且要提供特定于服务的文档时，你就需要上面的方法。可以在 YAML 中添加 overview 详细记录 API 的描述信息。但是，一般推荐将注释添加到 .proto。
与 .proto 注释一样，可以在 YAML 文件的注释中使用 Markdown 来提供其他格式。
API 描述
API 描述是一个描述此 API 能做什么，以动词开始的句子。在 .proto 文件中，API 描述以注释的方法添加到对应的 service 上，例如：
// Manages books and shelves in a simple digital library.
service LibraryService {
...
}
API 描述的其他示例：
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.
资源描述
顾名思义资源描述用来描述资源代表的什么东西。在 .proto 文件中，资源描述作为注释添加到对应消息上，例如：
// A book resource in the Library API.
message Book {
...
}
资源描述的其他示例：
字段和参数描述
用于描述字段和参数的定义，一些示例：
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 is true.
The container for voting information. Present only when voting information is recorded.
Not currently used or deprecated.
字段和参数描述:
必须清楚地描述边界条件（描述哪些值有效哪些值无效。API 用户会尽最大的可能来误用服务，而且不能阅读底层代码来弄清楚）
必须指定默认值和默认行为
-
当是字符串时，要描述语法、允许的字符和需要的编码格式，例如
如果可以的话，提供示例
当字段 必须、仅输入、仅输出 时，必须在字段描述的开始进行说明。默认情况下所有字段和参数都是可选的。例如：
message Table {
// Required. The resource name of the table.
string name = 1;
// Input only. Whether to dry run the table creation.
bool dryrun = 2;
// Output only. The timestamp when the table was created. Assigned by
// the server.
Timestamp create_time = 3;
// The display name of the table.
string display_name = 4;
}
方法描述
方法描述用来说明方法的作用和操作的资源。通常以第三人称的现在时动词开始。示例：
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.
注意事项
确保描述简洁完整并且容易被理解。不能仅做重述，例如 series.insert 方法的描述不能简单地写成 "Inserts a series"。命名应该包含丰富的信息，大多数读者会阅读描述，因为他们需要比名字本身更多的信息。如果不知道在描述中要写什么，试着回答下面的问题：
惯例
本节列出了文本描述和文档的一些使用惯例。使用 ID 表示标识符（而不使用 Id 或 id）。使用 JSON 表示数据格式（而不使用 Json 或 json）。所有字段/参数使用 code font 的格式，字符串要用引号括起来。
语言风格
和命名约定一样，在写注释时推荐使用简洁一致的词语和风格，让母语非英语的读者容易理解。因此要避免行话、俚语、复杂的隐喻、流行文化或其他不容易理解的内容。使用友好专业的风格直接与读者“交谈”，并尽可能保持注释的简洁。请记住，大部分读者只想知道如何使用 API，而不是阅读你的文档！
查看其他章节
