api: some comment cleanups in preparation for v3 proto transforms. (#8300)

* Move trailing detached comments that protoc ignores to some anchored place. In the near future,
  this will be enforced by check_format.

* Remove comments on reserved fields; we won't be using reserved in v3 and it's a bit of a pain
  preserving them.

Risk level: Low
Testing: Docs build, diff inspection, comparison against output of proto transform tool.

Signed-off-by: Harvey Tuch <htuch@google.com>

Mirrored from https://github.com/envoyproxy/envoy @ 22712d26c427091a47324b5f05fd0b493ee4be01

envoy/api/v2/core/grpc_service.proto

@@ -160,7 +160,6 @@ message GrpcService {
   // request.
   google.protobuf.Duration timeout = 3;
 
-  // Field 4 reserved due to moving credentials inside the GoogleGrpc message
   reserved 4;
 
   // Additional metadata to include in streams initiated to the GrpcService.

envoy/api/v2/core/health_check.proto

@@ -189,8 +189,7 @@ message HealthCheck {
     CustomHealthCheck custom_health_check = 13;
   }
 
-  reserved 10; // redis_health_check is deprecated by :ref:`custom_health_check
-               // <envoy_api_field_core.HealthCheck.custom_health_check>`
+  reserved 10;
   reserved "redis_health_check";
 
   // The "no traffic interval" is a special health check interval that is used when a cluster has

envoy/api/v2/core/protocol.proto

@@ -1,5 +1,3 @@
-// [#protodoc-title: Protocol options]
-
 syntax = "proto3";
 
 package envoy.api.v2.core;

envoy/api/v2/route/route.proto

@@ -1291,11 +1291,8 @@ message HeaderMatcher {
   // Specifies the name of the header in the request.
   string name = 1 [(validate.rules).string.min_bytes = 1];
 
-  reserved 2; // value deprecated by :ref:`exact_match
-              // <envoy_api_field_route.HeaderMatcher.exact_match>`
-
-  reserved 3; // regex deprecated by :ref:`regex_match
-              // <envoy_api_field_route.HeaderMatcher.regex_match>`
+  reserved 2;
+  reserved 3;
 
   // Specifies how the header match will be performed to route the request.
   oneof header_match_specifier {

envoy/config/bootstrap/v2/bootstrap.proto

@@ -293,15 +293,18 @@ message RuntimeLayer {
   string name = 1 [(validate.rules).string.min_bytes = 1];
 
   oneof layer_specifier {
+    option (validate.required) = true;
+
     // :ref:`Static runtime <config_runtime_bootstrap>` layer.
     // This follows the :ref:`runtime protobuf JSON representation encoding
     // <config_runtime_proto_json>`. Unlike static xDS resources, this static
     // layer is overridable by later layers in the runtime virtual filesystem.
-    option (validate.required) = true;
-
     google.protobuf.Struct static_layer = 2;
+
     DiskLayer disk_layer = 3;
+
     AdminLayer admin_layer = 4;
+
     RtdsLayer rtds_layer = 5;
   }
 }

envoy/config/filter/http/buffer/v2/buffer.proto

@@ -14,7 +14,7 @@ import "validate/validate.proto";
 // Buffer :ref:`configuration overview <config_http_filters_buffer>`.
 
 message Buffer {
-  reserved 2; // formerly max_request_time
+  reserved 2;
 
   // The maximum request size that the filter will buffer before the connection
   // manager will stop buffering and return a 413 response.

envoy/config/filter/network/dubbo_proxy/v2alpha1/dubbo_proxy.proto

@@ -38,12 +38,14 @@ message DubboProxy {
 
 // Dubbo Protocol types supported by Envoy.
 enum ProtocolType {
-  Dubbo = 0; // the default protocol.
+  // the default protocol.
+  Dubbo = 0;
 }
 
 // Dubbo Serialization types supported by Envoy.
 enum SerializationType {
-  Hessian2 = 0; // the default serialization protocol.
+  // the default serialization protocol.
+  Hessian2 = 0;
 }
 
 // DubboFilter configures a Dubbo filter.

envoy/config/filter/network/http_connection_manager/v2/http_connection_manager.proto

@@ -350,7 +350,7 @@ message HttpConnectionManager {
     // Whether to forward the subject of the client cert. Defaults to false.
     google.protobuf.BoolValue subject = 1;
 
-    reserved 2; // san deprecated by uri
+    reserved 2;
 
     // Whether to forward the entire client cert in URL encoded PEM format. This will appear in the
     // XFCC header comma separated from other values with the value Cert="PEM".

envoy/config/trace/v2/trace.proto

@@ -169,7 +169,7 @@ message OpenCensusConfig {
   // format: https://github.com/grpc/grpc/blob/master/doc/naming.md
   string ocagent_address = 12;
 
-  reserved 7; // Formerly zipkin_service_name.
+  reserved 7;
 
   enum TraceContext {
     // No-op default, no trace context is utilized.

envoy/data/tap/v2alpha/transport.proto

@@ -31,10 +31,10 @@ message SocketEvent {
 
   // Data read by Envoy from the transport socket.
   message Read {
+    // TODO(htuch): Half-close for reads.
+
     // Binary data read.
     Body data = 1;
-
-    // TODO(htuch): Half-close for reads.
   }
 
   // Data written by Envoy to the transport socket.

envoy/service/auth/v2/attribute_context.proto

@@ -22,6 +22,17 @@ import "google/protobuf/timestamp.proto";
 // Each attribute has a type and a name, which is logically defined as a proto message field
 // of the `AttributeContext`. The `AttributeContext` is a collection of individual attributes
 // supported by Envoy authorization system.
+// [#comment: The following items are left out of this proto
+// Request.Auth field for jwt tokens
+// Request.Api for api management
+// Origin peer that originated the request
+// Caching Protocol
+// request_context return values to inject back into the filter chain
+// peer.claims -- from X.509 extensions
+// Configuration
+// - field mask to send
+// - which return values from request_context are copied back
+// - which return values are copied into request_headers]
 message AttributeContext {
   // This message defines attributes for a node that handles a network request.
   // The node can be either a service or an application that sends, forwards,
@@ -63,8 +74,6 @@ message AttributeContext {
 
     // Represents an HTTP request or an HTTP-like request.
     HttpRequest http = 2;
-
-    // More request types are added here as necessary.
   }
 
   // This message defines attributes for an HTTP request.
@@ -137,15 +146,3 @@ message AttributeContext {
   // Dynamic metadata associated with the request.
   envoy.api.v2.core.Metadata metadata_context = 11;
 }
-
-// The following items are left out of this proto
-// Request.Auth field for jwt tokens
-// Request.Api for api management
-// Origin peer that originated the request
-// Caching Protocol
-// request_context return values to inject back into the filter chain
-// peer.claims -- from X.509 extensions
-// Configuration
-// - field mask to send
-// - which return values from request_context are copied back
-// - which return values are copied into request_headers

envoy/service/tap/v2alpha/common.proto

@@ -18,6 +18,8 @@ option java_package = "io.envoyproxy.envoy.service.tap.v2alpha";
 
 // Tap configuration.
 message TapConfig {
+  // [#comment:TODO(mattklein123): Rate limiting]
+
   // The match configuration. If the configuration matches the data source being tapped, a tap will
   // occur, with the result written to the configured output.
   MatchPredicate match_config = 1 [(validate.rules).message.required = true];
@@ -35,8 +37,6 @@ message TapConfig {
   //   This field defaults to 100/:ref:`HUNDRED
   //   <envoy_api_enum_type.FractionalPercent.DenominatorType>`.
   envoy.api.v2.core.RuntimeFractionalPercent tap_enabled = 3;
-
-  // [#comment:TODO(mattklein123): Rate limiting]
 }
 
 // Tap match configuration. This is a recursive structure which allows complex nested match