docs: force all API protos to have a title (#9744)

Fixes https://github.com/envoyproxy/envoy/issues/8525

Signed-off-by: Matt Klein <mklein@lyft.com>

Mirrored from https://github.com/envoyproxy/envoy @ a2e0f7873a6257f459024c25309f8b7f76c24f60

envoy/admin/v2alpha/tap.proto

@@ -10,6 +10,8 @@ option java_package = "io.envoyproxy.envoy.admin.v2alpha";
 option java_outer_classname = "TapProto";
 option java_multiple_files = true;
 
+// [#protodoc-title: Tap]
+
 // The /tap admin request body that is used to configure an active tap session.
 message TapRequest {
   // The opaque configuration ID used to match the configuration to a loaded extension.

envoy/admin/v3/tap.proto

@@ -12,6 +12,8 @@ option java_package = "io.envoyproxy.envoy.admin.v3";
 option java_outer_classname = "TapProto";
 option java_multiple_files = true;
 
+// [#protodoc-title: Tap]
+
 // The /tap admin request body that is used to configure an active tap session.
 message TapRequest {
   option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v2alpha.TapRequest";

envoy/annotations/deprecation.proto

@@ -4,6 +4,7 @@ package envoy.annotations;
 
 import "google/protobuf/descriptor.proto";
 
+// [#protodoc-title: Deprecation]
 // Allows tagging proto fields as fatal by default. One Envoy release after
 // deprecation, deprecated fields will be disallowed by default, a state which
 // is reversible with :ref:`runtime overrides <config_runtime_deprecation>`.

envoy/annotations/resource.proto

@@ -4,6 +4,8 @@ package envoy.annotations;
 
 import "google/protobuf/descriptor.proto";
 
+// [#protodoc-title: Resource]
+
 // Magic number in this file derived from top 28bit of SHA256 digest of "envoy.annotation.resource".
 extend google.protobuf.ServiceOptions {
   ResourceAnnotation resource = 265073217;

envoy/api/v2/cluster/filter.proto

@@ -15,8 +15,8 @@ option ruby_package = "Envoy.Api.V2.ClusterNS";
 option (udpa.annotations.file_migrate).move_to_package = "envoy.config.cluster.v3";
 
 // [#protodoc-title: Upstream filters]
-//
 // Upstream filters apply to the connections to the upstream cluster hosts.
+
 message Filter {
   // The name of the filter to instantiate. The name must match a
   // :ref:`supported filter <config_network_filters>`.

envoy/config/cluster/v3/filter.proto

@@ -13,8 +13,8 @@ option java_outer_classname = "FilterProto";
 option java_multiple_files = true;
 
 // [#protodoc-title: Upstream filters]
-//
 // Upstream filters apply to the connections to the upstream cluster hosts.
+
 message Filter {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.cluster.Filter";
 

envoy/config/filter/network/mysql_proxy/v1alpha1/mysql_proxy.proto

@@ -14,6 +14,7 @@ option (udpa.annotations.file_migrate).move_to_package =
 // [#protodoc-title: MySQL proxy]
 // MySQL Proxy :ref:`configuration overview <config_network_filters_mysql_proxy>`.
 // [#extension: envoy.filters.network.mysql_proxy]
+
 message MySQLProxy {
   // The human readable prefix to use when emitting :ref:`statistics
   // <config_network_filters_mysql_proxy_stats>`.

envoy/config/filter/network/zookeeper_proxy/v1alpha1/zookeeper_proxy.proto

@@ -16,6 +16,7 @@ option (udpa.annotations.file_migrate).move_to_package =
 // [#protodoc-title: ZooKeeper proxy]
 // ZooKeeper Proxy :ref:`configuration overview <config_network_filters_zookeeper_proxy>`.
 // [#extension: envoy.filters.network.zookeeper_proxy]
+
 message ZooKeeperProxy {
   // The human readable prefix to use when emitting :ref:`statistics
   // <config_network_filters_zookeeper_proxy_stats>`.

envoy/config/listener/v2/api_listener.proto

@@ -11,6 +11,8 @@ option java_outer_classname = "ApiListenerProto";
 option java_multiple_files = true;
 option (udpa.annotations.file_migrate).move_to_package = "envoy.config.listener.v3";
 
+// [#protodoc-title: API listener]
+
 // Describes a type of API listener, which is used in non-proxy clients. The type of API
 // exposed to the non-proxy application depends on the type of API listener.
 message ApiListener {

envoy/config/listener/v3/api_listener.proto

@@ -10,6 +10,8 @@ option java_package = "io.envoyproxy.envoy.config.listener.v3";
 option java_outer_classname = "ApiListenerProto";
 option java_multiple_files = true;
 
+// [#protodoc-title: API listener]
+
 // Describes a type of API listener, which is used in non-proxy clients. The type of API
 // exposed to the non-proxy application depends on the type of API listener.
 message ApiListener {

envoy/config/retry/omit_canary_hosts/v2/omit_canary_hosts.proto

@@ -8,5 +8,6 @@ option java_multiple_files = true;
 
 // [#protodoc-title: Omit Canary Hosts Predicate]
 // [#extension: envoy.retry_host_predicates.omit_canary_hosts]
+
 message OmitCanaryHostsPredicate {
 }

envoy/config/retry/previous_hosts/v2/previous_hosts.proto

@@ -8,5 +8,6 @@ option java_multiple_files = true;
 
 // [#protodoc-title: Previous Hosts Predicate]
 // [#extension: envoy.retry_host_predicates.previous_hosts]
+
 message PreviousHostsPredicate {
 }

envoy/config/retry/previous_priorities/previous_priorities_config.proto

@@ -8,6 +8,8 @@ option java_package = "io.envoyproxy.envoy.config.retry.previous_priorities";
 option java_outer_classname = "PreviousPrioritiesConfigProto";
 option java_multiple_files = true;
 
+// [#protodoc-title: Previous priorities retry selector]
+
 // A retry host selector that attempts to spread retries between priorities, even if certain
 // priorities would not normally be attempted due to higher priorities being available.
 //

envoy/extensions/filters/network/mysql_proxy/v3/mysql_proxy.proto

@@ -13,6 +13,7 @@ option java_multiple_files = true;
 // [#protodoc-title: MySQL proxy]
 // MySQL Proxy :ref:`configuration overview <config_network_filters_mysql_proxy>`.
 // [#extension: envoy.filters.network.mysql_proxy]
+
 message MySQLProxy {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.filter.network.mysql_proxy.v1alpha1.MySQLProxy";

envoy/extensions/filters/network/zookeeper_proxy/v3/zookeeper_proxy.proto

@@ -15,6 +15,7 @@ option java_multiple_files = true;
 // [#protodoc-title: ZooKeeper proxy]
 // ZooKeeper Proxy :ref:`configuration overview <config_network_filters_zookeeper_proxy>`.
 // [#extension: envoy.filters.network.zookeeper_proxy]
+
 message ZooKeeperProxy {
   option (udpa.annotations.versioning).previous_message_type =
       "envoy.config.filter.network.zookeeper_proxy.v1alpha1.ZooKeeperProxy";

envoy/extensions/retry/priority/previous_priorities/v3/previous_priorities_config.proto

@@ -10,6 +10,8 @@ option java_package = "io.envoyproxy.envoy.extensions.retry.priority.previous_pr
 option java_outer_classname = "PreviousPrioritiesConfigProto";
 option java_multiple_files = true;
 
+// [#protodoc-title: Previous priorities retry selector]
+
 // A retry host selector that attempts to spread retries between priorities, even if certain
 // priorities would not normally be attempted due to higher priorities being available.
 //

envoy/service/discovery/v2/ads.proto

@@ -9,6 +9,8 @@ option java_outer_classname = "AdsProto";
 option java_multiple_files = true;
 option java_generic_services = true;
 
+// [#protodoc-title: Aggregated Discovery Service (ADS)]
+
 // [#not-implemented-hide:] Discovery services for endpoints, clusters, routes,
 // and listeners are retained in the package `envoy.api.v2` for backwards
 // compatibility with existing management servers. New development in discovery

envoy/service/discovery/v2/hds.proto

@@ -17,6 +17,8 @@ option java_multiple_files = true;
 option java_generic_services = true;
 option (udpa.annotations.file_migrate).move_to_package = "envoy.service.health.v3";
 
+// [#protodoc-title: Health Discovery Service (HDS)]
+
 // HDS is Health Discovery Service. It compliments Envoy’s health checking
 // service by designating this Envoy to be a healthchecker for a subset of hosts
 // in the cluster. The status of these health checks will be reported to the

envoy/service/discovery/v2/sds.proto

@@ -15,6 +15,8 @@ option java_multiple_files = true;
 option java_generic_services = true;
 option (udpa.annotations.file_migrate).move_to_package = "envoy.service.secret.v3";
 
+// [#protodoc-title: Secret Discovery Service (SDS)]
+
 service SecretDiscoveryService {
   option (envoy.annotations.resource).type = "envoy.api.v2.auth.Secret";
 

envoy/service/discovery/v3/ads.proto

@@ -11,6 +11,8 @@ option java_outer_classname = "AdsProto";
 option java_multiple_files = true;
 option java_generic_services = true;
 
+// [#protodoc-title: Aggregated Discovery Service (ADS)]
+
 // [#not-implemented-hide:] Discovery services for endpoints, clusters, routes,
 // and listeners are retained in the package `envoy.api.v2` for backwards
 // compatibility with existing management servers. New development in discovery

envoy/service/health/v3/hds.proto

@@ -16,6 +16,8 @@ option java_outer_classname = "HdsProto";
 option java_multiple_files = true;
 option java_generic_services = true;
 
+// [#protodoc-title: Health Discovery Service (HDS)]
+
 // HDS is Health Discovery Service. It compliments Envoy’s health checking
 // service by designating this Envoy to be a healthchecker for a subset of hosts
 // in the cluster. The status of these health checks will be reported to the

envoy/service/metrics/v2/metrics_service.proto

@@ -13,6 +13,8 @@ option java_outer_classname = "MetricsServiceProto";
 option java_multiple_files = true;
 option java_generic_services = true;
 
+// [#protodoc-title: Metrics service]
+
 // Service for streaming metrics to server that consumes the metrics data. It uses Prometheus metric
 // data model as a standard to represent metrics information.
 service MetricsService {

envoy/service/metrics/v3/metrics_service.proto

@@ -14,6 +14,8 @@ option java_outer_classname = "MetricsServiceProto";
 option java_multiple_files = true;
 option java_generic_services = true;
 
+// [#protodoc-title: Metrics service]
+
 // Service for streaming metrics to server that consumes the metrics data. It uses Prometheus metric
 // data model as a standard to represent metrics information.
 service MetricsService {

envoy/service/secret/v3/sds.proto

@@ -15,6 +15,8 @@ option java_outer_classname = "SdsProto";
 option java_multiple_files = true;
 option java_generic_services = true;
 
+// [#protodoc-title: Secret Discovery Service (SDS)]
+
 service SecretDiscoveryService {
   option (envoy.annotations.resource).type = "envoy.extensions.transport_sockets.tls.v3.Secret";
 

envoy/service/trace/v2/trace_service.proto

@@ -15,6 +15,8 @@ option java_outer_classname = "TraceServiceProto";
 option java_multiple_files = true;
 option java_generic_services = true;
 
+// [#protodoc-title: Trace service]
+
 // Service for streaming traces to server that consumes the trace data. It
 // uses OpenCensus data model as a standard to represent trace information.
 service TraceService {

envoy/service/trace/v3/trace_service.proto

@@ -16,6 +16,8 @@ option java_outer_classname = "TraceServiceProto";
 option java_multiple_files = true;
 option java_generic_services = true;
 
+// [#protodoc-title: Trace service]
+
 // Service for streaming traces to server that consumes the trace data. It
 // uses OpenCensus data model as a standard to represent trace information.
 service TraceService {

envoy/type/http.proto

@@ -6,6 +6,8 @@ option java_package = "io.envoyproxy.envoy.type";
 option java_outer_classname = "HttpProto";
 option java_multiple_files = true;
 
+// [#protodoc-title: HTTP]
+
 enum CodecClientType {
   HTTP1 = 0;
 

envoy/type/http_status.proto

@@ -8,6 +8,8 @@ option java_package = "io.envoyproxy.envoy.type";
 option java_outer_classname = "HttpStatusProto";
 option java_multiple_files = true;
 
+// [#protodoc-title: HTTP status codes]
+
 // HTTP response codes supported in Envoy.
 // For more details: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
 enum StatusCode {

envoy/type/v3/http.proto

@@ -6,6 +6,8 @@ option java_package = "io.envoyproxy.envoy.type.v3";
 option java_outer_classname = "HttpProto";
 option java_multiple_files = true;
 
+// [#protodoc-title: HTTP]
+
 enum CodecClientType {
   HTTP1 = 0;
 

envoy/type/v3/http_status.proto

@@ -10,6 +10,8 @@ option java_package = "io.envoyproxy.envoy.type.v3";
 option java_outer_classname = "HttpStatusProto";
 option java_multiple_files = true;
 
+// [#protodoc-title: HTTP status codes]
+
 // HTTP response codes supported in Envoy.
 // For more details: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
 enum StatusCode {