文档

在 文件中可以使用 Protocol Buffers 通常的注释格式(\\)来添加注释

服务配置中的注释

另一种向 .proto 文件添加注释的方法是，可以在其 YAML 服务配置文件中为 API 添加内联文档。 如果两个文件中都记录了相同的元素，则 YAML 中的文档将优先于 .proto 中的文档。

如果有多个服务定义在同一个 .proto 文件中，并且希望为每个服务提供文档，则可能需要使用此方法。在 YAML 文还可以为 API 添加更详细的概述。但是一般情况下，推荐在 文件中添加文档注释。

与 .proto 注释一样，可以使用 Markdown 为 YAML 中的注释提供更多排版格式。

下面是一些 API 描述的示例：

• 分享你的动态、照片、视频给其他朋友。
• 访问云托管的机器学习服务，可以轻松构建响应数据流的智能应用程序。

资源描述

资源描述是描述资源代表了什么的句子。如果需要添加更多详细信息，使用添加其他句子。在 .proto 文件中，资源描述作为注释添加到对应的消息类型上，如下：

下面是一些资源描述的示例：

• 代表用户待办事项中的一项任务。每项任务具有唯一的优先级。
• 代表用户日历上的一个事件。

一个描述字段或参数定义的名词短语，例如：

• 话题数量。
• 标记是否为提交资源返回附件地址，series.insert 的默认值为 。
• 用于投票信息的容器，仅当记录投票信息时才存在。
• 目前未使用或已弃用。

• 必须清楚地描述边界（也就是说，明确什么是有效的什么是无效的。请记住，工程师不会阅读底下的代码来明确任何不清楚的信息。）
• 必须指定默认值或默认行为。换句话说，如果没有提供任何值服务器将会是什么行为。
• 如果是字符串（如名称或路径），请描述其语法规则并列出允许的字符以及所需的编码。例如：
  • 集合 [A-a0-9] 中1～255个字符
  • 以 / 开头的有效 URL 路径字符串，必须遵循 RFC 2332 约定。最大允许长度为500个字符
• 尽可能提供示例值。
• 如果字段值是必需的、或仅用于输入、或仅用于输出，那么必须在字段描述的开始处注明。默认情况下，所有字段和参数都是可选的。例如：

方法描述

方法描述是一个句子，指出该方法具有什么效果以及操作的资源。它通常以第三人称现在时态（即以 s 结尾的动词）开始。如果需要添加详细信息，可以使用更多的句子。例如：

• 列出已认证用户的日历事件。
• 使用请求中包含的数据来更新日历事件。
• 从已认证用户的位置历史记录中删除一个位置记录。
• 在已认证用户的位置历史记录中，使用请求中包含的数据创建或更新一个位置记录。如果已存在具有相同时间戳的位置记录，则用提供的数据覆盖现有数据。

确保每个描述都是简短但完整的，并且能够让用户在没有 API 其他信息的情况下所理解。实际上，还有更多需要注意的事项。例如，方法 series.insert 的描述不应该只是说“插入一个系列”。尽管你在命名时应该易于理解，但读者之所以阅读你的描述，是因为他们需要获取更多的信息。如果您不确定需要在描述中表述什么，可以参考下面这些问题：

• 如果（请求）成功它会做什么？如果失败它会做什么？什么可能导致失败？
• 它是幂等的吗？
• 单位是什么？ （例如：米，度，像素。）
• 它接受什么范围的值？范围是包含还是排他？
• 有什么副作用吗？
• 你该如何使用它？
• 可能破坏它的常见错误有哪些？
• 它总是存在吗？ （例如：“用于投票信息的容器，仅在记录投票信息时存在”。）
• 它有默认设置吗？

约定

本节列出了文本描述和文档的一些使用约定。例如，在谈论标识符时，使用 “ID”（全大写），而不是 “Id” 或 “id”。在指代 JSON 数据格式时，请使用 “JSON” 而不是 “Json” 或 “json”。使用代码字体来表示所有字段和参数名称。字符串字面值以代码字体表示并放入引号中。

• ID
• JSON
• RPC
• REST
• property_name 或 “string_literal”

语言风格

正如上一章节的命名约定，我们建议在编写文档注释时使用简单，一致的词汇。 注释应该易于母语非英语的读者理解，所以避免行话、俚语、复杂的隐喻、引用流行文化，或任何其他不容易翻译的内容。阅读注释时好似以友好、专业的风格直接与开发人员交流。请谨记，读者是为了了解如何使用 API，而不是阅读你的文档！