AIP-192 文档
| 编号 | 192 |
|---|---|
| 原文链接 | AIP-192: Documentation |
| 状态 | 批准 |
| 创建日期 | 2019-07-25 |
| 更新日期 | 2019-07-25 |
文档是API设计中最关键的方面之一。API用户无法深入到实现细节去更好地理解API。通常，API界面定义和相关文档是用户仅有的东西。因此文档必须尽量清晰、完整、明确。
指南
使用protocol buffer定义的API， 必须 在每个组件（服务、方法、消息、域、枚举和枚举值）中包含符合protocol buffer格式的公开注释。即使一些注释简短又乏味，也很重要，因为许多工具会读取和使用注释。
特别对于服务， 应当 存在描述性注释，解释服务是什么，以及用户可以拿来做什么。
注意 许多读者可能不是以英语为母语的人。注释 应当 避免使用行业惯用语、俚语、复杂隐喻、流行文化引用，或其他难以翻译的内容。此外，许多读者存在不同的背景和视角；在编写涉及人物的示例时，注释 应当 使用无争议的、非健在的人物。
样式
注释 应当 使用语法正确的美式英语。每个注释的第一句 应当 省略主语，使用第三人称现在时：
// Creates a book under the given publisher.
rpc CreateBook(CreateBookRequest) returns (Book) {
option (google.api.http) = {
post: "/v1/{parent=publishers/*}/books"
body: "book"
};
}
描述
消息和域的描述 应当 简洁而完整。有时注释可以非常简单，如果确实没有太多东西可说。然而在得出这个结论之前，考虑是否涉及以下问题：
- 它是什么？
- 如何使用它？
- 成功时它会做什么？失败时呢？
- 它是幂等的吗？
- 单位是什么？（例如：米、度、像素）
- 有什么副作用？
- 有哪些可能导致失败的常见错误？
- 要求的输入格式是什么？
- 接受的值的范围是什么？（例如
[0.0, 1.0)，[1, 10]）- 范围边界是包含还是排除？
- 对于字符串，最小和最大长度是多少，允许哪些字符？
- 如果超过最大长度，是截断还是返回错误？
- 它总是存在的吗？（例如：“投票信息容器仅在记录投票信息时存在。”）
- 它有默认设置吗？（例如：“如果省略
page_size，则默认为50。”）
格式化
注释中的任何带有格式的内容 必须 使用CommonMark。 不得 使用标题和表格，它们会导致多个工具出现问题，也不适合客户端库参考文档。
注释 应当 使用 代码字体 表示域或方法名字以及字面值（如 true ）。
不得 使用原始HTML。
不得 使用“ASCII art”在协议中展示图表。很多渲染器会使用协议中的Markdown，ASCII art不太可能被所有渲染器正确展示。如果图表有助于理解API，请包含链接指向一个文档页，在文档页中展示图表。
交叉引用
注释可以使用Markdown参考链接“链接”到另一个组件（服务、方法、消息、域、枚举或枚举值）。参考 必须 是以下形式之一：
- 元素的完全限定名，例如
[Book][google.example.v1.Book] - 相对范围引用，例如
[科幻类型][Genre.GENRE_SCI_FI] - 隐含引用，例如
[Book][]等同于[Book][Book]
这些引用按照名字解析规则解析。
不得 在引用中包含域名字。域名字无法解析， 必须 引用原始定义。例如 [author][Book.author.family_name] ，其中 author 是 Book 中的域，无法解析，但 [author][Author.family_name] 可以解析。
外部链接
注释 可以 链接到外部页面，提供比注释更多的背景信息。外部链接 必须 使用绝对（而非相对）URL，包括协议（通常是 https ），并且 不应 假定文档位于某个特定主机上。例如： [Spanner文档](https://cloud.google.com/spanner/docs)
商标名
在注释中引用公司或产品的正确商标名时， 不应 使用缩写。缩写是主流口语用法、非缩写可能产生困惑的除外（例如：IBM）。
注释中商标名的拼写和大小写 应当 与商标所有者当前品牌一致。
废弃
废弃组件（服务、方法、消息、域、枚举或枚举值）时， 必须 将 deprecated 选项设为 true ，相应注释的第一行 必须 以 "Deprecated: " 开头，并为开发者提供替代方案。如果没有替代方案， 必须 给出废弃原因。
内部注释
注释 可以 标记为内部，方法是将内容包围在 (-- 和 --) 中。
非公开链接、内部实现备注（如 TODO 和 FIXME 指令）以及其他此类材料 必须 标记为内部。
注意 应当 仅使用前导注释（而非尾注释或分离注释）。特别的，*不得* 同时使用前导和尾注释来描述组件，这是无意中遗漏内部内容的常见原因。
修订记录
- 2024-10-29 包含交叉引用解析规则。
- 2023-08-11 扩展弃用注释要求到所有组件。
- 2021-04-20 添加弃用服务和远程过程调用指南。
- 2020-04-01 添加要求外部链接使用绝对URL的指南。
- 2020-02-14 添加关于使用商标名的指南。
- 2019-09-23 添加关于不使用前导和尾注释的指南。
- 2019-08-01 将示例从“书架”更改为“出版商”，更好的展示资源所有权。