docs/proto: Adding comments to fields/enums that have no comments (#3…

…7018)

An internal tool we have notified us that some API fields and
enum-values that we use do not have comments.
I've added some comments, and updated some of the ext-proc comments to
make it a bit clearer.

Signed-off-by: Adi Suissa-Peleg <[email protected]>

api/envoy/config/core/v3/base.proto

@@ -453,6 +453,7 @@ message HeaderValueOption {
 message HeaderMap {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.HeaderMap";
 
+  // A list of header names and their values.
   repeated HeaderValue headers = 1;
 }
 

api/envoy/service/ext_proc/v3/external_processor.proto

@@ -45,7 +45,6 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 // In other words, the process is a request/response conversation, but
 // using a gRPC stream to make it easier for the server to
 // maintain state.
-
 service ExternalProcessor {
   // This begins the bidirectional stream that Envoy will use to
   // give the server control over what the filter does. The actual
@@ -129,6 +128,7 @@ message ProcessingRequest {
 // set to false, the server must send back exactly one ProcessingResponse message.
 // [#next-free-field: 11]
 message ProcessingResponse {
+  // The response type that is sent by the server.
   oneof response {
     option (validate.required) = true;
 
@@ -220,19 +220,25 @@ message HttpHeaders {
   map<string, google.protobuf.Struct> attributes = 2
       [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"];
 
-  // If true, then there is no message body associated with this
+  // If ``true``, then there is no message body associated with this
   // request or response.
   bool end_of_stream = 3;
 }
 
-// This message contains the message body that Envoy sends to the external server.
+// This message is sent to the external server when the HTTP request and
+// response bodies are received.
 message HttpBody {
+  // The contents of the body in the HTTP request/response. Note that in
+  // streaming mode multiple ``HttpBody`` messages may be sent.
   bytes body = 1;
 
+  // If ``true``, this will be the last ``HttpBody`` message that will be sent and no
+  // trailers will be sent for the current request/response.
   bool end_of_stream = 2;
 }
 
-// This message contains the trailers.
+// This message is sent to the external server when the HTTP request and
+// response trailers are received.
 message HttpTrailers {
   // The header value is encoded in the
   // :ref:`raw_value <envoy_v3_api_field_config.core.v3.HeaderValue.raw_value>` field.
@@ -241,25 +247,34 @@ message HttpTrailers {
 
 // The following are messages that may be sent back by the server.
 
-// This message must be sent in response to an HttpHeaders message.
+// This message is sent by the external server to Envoy after ``HttpHeaders`` was
+// sent to it.
 message HeadersResponse {
+  // Details the modifications (if any) to be made by Envoy to the current
+  // request/response.
   CommonResponse response = 1;
 }
 
-// This message must be sent in response to an HttpTrailers message.
-message TrailersResponse {
-  // Instructions on how to manipulate the trailers
-  HeaderMutation header_mutation = 1;
-}
-
-// This message must be sent in response to an HttpBody message.
+// This message is sent by the external server to Envoy after ``HttpBody`` was
+// sent to it.
 message BodyResponse {
+  // Details the modifications (if any) to be made by Envoy to the current
+  // request/response.
   CommonResponse response = 1;
 }
 
+// This message is sent by the external server to Envoy after ``HttpTrailers`` was
+// sent to it.
+message TrailersResponse {
+  // Details the modifications (if any) to be made by Envoy to the current
+  // request/response trailers.
+  HeaderMutation header_mutation = 1;
+}
+
 // This message contains common fields between header and body responses.
 // [#next-free-field: 6]
 message CommonResponse {
+  // The status of the response.
   enum ResponseStatus {
     // Apply the mutation instructions in this message to the
     // request or response, and then continue processing the filter
@@ -322,7 +337,7 @@ message CommonResponse {
 // to the downstream codec, or reset the stream.
 // [#next-free-field: 6]
 message ImmediateResponse {
-  // The response code to return
+  // The response code to return.
   type.v3.HttpStatus status = 1 [(validate.rules).message = {required: true}];
 
   // Apply changes to the default headers, which will include content-type.
@@ -343,7 +358,7 @@ message ImmediateResponse {
 
 // This message specifies a gRPC status for an ImmediateResponse message.
 message GrpcStatus {
-  // The actual gRPC status
+  // The actual gRPC status.
   uint32 status = 1;
 }
 
@@ -365,11 +380,12 @@ message HeaderMutation {
 // Replace the entire message body chunk received in the corresponding
 // HttpBody message with this new body, or clear the body.
 message BodyMutation {
+  // The type of mutation for the body.
   oneof mutation {
-    // The entire body to replace
+    // The entire body to replace.
     bytes body = 1;
 
-    // Clear the corresponding body chunk
+    // Clear the corresponding body chunk.
     bool clear_body = 2;
   }
 }

api/envoy/type/v3/http_status.proto

@@ -21,116 +21,172 @@ enum StatusCode {
   // `enum` type.
   Empty = 0;
 
+  // Continue - ``100`` status code.
   Continue = 100;
 
+  // OK - ``200`` status code.
   OK = 200;
 
+  // Created - ``201`` status code.
   Created = 201;
 
+  // Accepted - ``202`` status code.
   Accepted = 202;
 
+  // NonAuthoritativeInformation - ``203`` status code.
   NonAuthoritativeInformation = 203;
 
+  // NoContent - ``204`` status code.
   NoContent = 204;
 
+  // ResetContent - ``205`` status code.
   ResetContent = 205;
 
+  // PartialContent - ``206`` status code.
   PartialContent = 206;
 
+  // MultiStatus - ``207`` status code.
   MultiStatus = 207;
 
+  // AlreadyReported - ``208`` status code.
   AlreadyReported = 208;
 
+  // IMUsed - ``226`` status code.
   IMUsed = 226;
 
+  // MultipleChoices - ``300`` status code.
   MultipleChoices = 300;
 
+  // MovedPermanently - ``301`` status code.
   MovedPermanently = 301;
 
+  // Found - ``302`` status code.
   Found = 302;
 
+  // SeeOther - ``303`` status code.
   SeeOther = 303;
 
+  // NotModified - ``304`` status code.
   NotModified = 304;
 
+  // UseProxy - ``305`` status code.
   UseProxy = 305;
 
+  // TemporaryRedirect - ``307`` status code.
   TemporaryRedirect = 307;
 
+  // PermanentRedirect - ``308`` status code.
   PermanentRedirect = 308;
 
+  // BadRequest - ``400`` status code.
   BadRequest = 400;
 
+  // Unauthorized - ``401`` status code.
   Unauthorized = 401;
 
+  // PaymentRequired - ``402`` status code.
   PaymentRequired = 402;
 
+  // Forbidden - ``403`` status code.
   Forbidden = 403;
 
+  // NotFound - ``404`` status code.
   NotFound = 404;
 
+  // MethodNotAllowed - ``405`` status code.
   MethodNotAllowed = 405;
 
+  // NotAcceptable - ``406`` status code.
   NotAcceptable = 406;
 
+  // ProxyAuthenticationRequired - ``407`` status code.
   ProxyAuthenticationRequired = 407;
 
+  // RequestTimeout - ``408`` status code.
   RequestTimeout = 408;
 
+  // Conflict - ``409`` status code.
   Conflict = 409;
 
+  // Gone - ``410`` status code.
   Gone = 410;
 
+  // LengthRequired - ``411`` status code.
   LengthRequired = 411;
 
+  // PreconditionFailed - ``412`` status code.
   PreconditionFailed = 412;
 
+  // PayloadTooLarge - ``413`` status code.
   PayloadTooLarge = 413;
 
+  // URITooLong - ``414`` status code.
   URITooLong = 414;
 
+  // UnsupportedMediaType - ``415`` status code.
   UnsupportedMediaType = 415;
 
+  // RangeNotSatisfiable - ``416`` status code.
   RangeNotSatisfiable = 416;
 
+  // ExpectationFailed - ``417`` status code.
   ExpectationFailed = 417;
 
+  // MisdirectedRequest - ``421`` status code.
   MisdirectedRequest = 421;
 
+  // UnprocessableEntity - ``422`` status code.
   UnprocessableEntity = 422;
 
+  // Locked - ``423`` status code.
   Locked = 423;
 
+  // FailedDependency - ``424`` status code.
   FailedDependency = 424;
 
+  // UpgradeRequired - ``426`` status code.
   UpgradeRequired = 426;
 
+  // PreconditionRequired - ``428`` status code.
   PreconditionRequired = 428;
 
+  // TooManyRequests - ``429`` status code.
   TooManyRequests = 429;
 
+  // RequestHeaderFieldsTooLarge - ``431`` status code.
   RequestHeaderFieldsTooLarge = 431;
 
+  // InternalServerError - ``500`` status code.
   InternalServerError = 500;
 
+  // NotImplemented - ``501`` status code.
   NotImplemented = 501;
 
+  // BadGateway - ``502`` status code.
   BadGateway = 502;
 
+  // ServiceUnavailable - ``503`` status code.
   ServiceUnavailable = 503;
 
+  // GatewayTimeout - ``504`` status code.
   GatewayTimeout = 504;
 
+  // HTTPVersionNotSupported - ``505`` status code.
   HTTPVersionNotSupported = 505;
 
+  // VariantAlsoNegotiates - ``506`` status code.
   VariantAlsoNegotiates = 506;
 
+  // InsufficientStorage - ``507`` status code.
   InsufficientStorage = 507;
 
+  // LoopDetected - ``508`` status code.
   LoopDetected = 508;
 
+  // NotExtended - ``510`` status code.
   NotExtended = 510;
 
+  // NetworkAuthenticationRequired - ``511`` status code.
   NetworkAuthenticationRequired = 511;
 }
 

tools/spelling/spelling_dictionary.txt

@@ -236,6 +236,7 @@ IANA
 IDL
 IETF
 IFADDRS
+IMUsed
 INADDR
 INET
 INVAL