补全协议定义与远程接口文档
依据服务端实现补充协议注释,明确字段语义、错误码和重试条件,并验证参考文档生成。
完整提示词
<context>
Comments directly above a service, RPC, message, field or enum value in a `.proto` file are leading comments; they flow into generated code in every language and into reference generators (protoc-gen-doc, Buf Schema Registry). Proto3 has quirks readers must be told about: scalar fields have no presence by default, so 0, "" and false are indistinguishable from unset unless the field is `optional` or a wrapper type; enums need a zero value that means unspecified; `oneof` means at most one is set. Error behaviour is not in the proto at all: which gRPC status codes an RPC returns (NOT_FOUND, INVALID_ARGUMENT, FAILED_PRECONDITION, ALREADY_EXISTS, UNAVAILABLE) and whether it is safe to retry lives only in server code and must be documented in the RPC comment. Field numbers and names are the wire and JSON contract, so a docs pass must never touch them.
</context>
<task>
Document these Protobuf definitions:
<protos>
{{protos}}
</protos>
1. Read the server implementation for each RPC: validation, the status codes returned and when, side effects, idempotency, deadlines and pagination.
2. Add leading `//` comments on each service (purpose, auth), RPC (what it does, status codes and their conditions, retry safety, idempotency key if any), message (what it represents), field (meaning, units, format, required by the server or not, what the zero value means, presence), and every enum value (meaning; first value documented as unspecified).
3. For `oneof`, `map` and `repeated` fields, document ordering and limits the server enforces.
4. For `google.protobuf.Timestamp`, `Duration` and `FieldMask` usage, state the semantics (for example which fields an update mask accepts).
5. Mark deprecated fields with `[deprecated = true]` only if they already are; otherwise note candidates. Mention `reserved` numbers in a comment if the reason is known.
6. Set up or run reference generation if the repo uses buf or protoc plugins (for example protoc-gen-doc or the Buf Schema Registry), and run `buf lint` or the project's proto checks.
</task>
<constraints>
- Comments only. Never change field numbers, names, types, options or package names.
- Status codes and retry advice must come from the server code; mark anything unconfirmed.
- Use leading comments, not trailing ones, so generators pick them up.
{{> guardrails/investigate-before-answering}}
</constraints>
<output_format>
Apply the edits. Then reply with:
## Changes
Files and elements documented.
## Status codes by RPC
Table: RPC | Code | When | Retry safe.
## Reference generation
What generates the reference, the command, and lint results.
## Questions for the owners
Unknown behaviour and contract issues (missing UNSPECIFIED enum values, presence problems).
</output_format>可替换内容
- {{protos}}
- {{> guardrails/investigate-before-answering}}
- [deprecated = true]
分类与标签
编程开发、协议文档、接口注释、错误码说明、参考文档生成