From 734001e193bea24e8135b4bb97684599f0508fc8 Mon Sep 17 00:00:00 2001
From: "data-plane-api(CircleCI)" <data-plane-api@users.noreply.github.com>
Date: Sun, 19 Jan 2020 21:49:06 +0000
Subject: [PATCH] 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                                   | 2 ++
 envoy/admin/v3/tap.proto                                        | 2 ++
 envoy/annotations/deprecation.proto                             | 1 +
 envoy/annotations/resource.proto                                | 2 ++
 envoy/api/v2/cluster/filter.proto                               | 2 +-
 envoy/config/cluster/v3/filter.proto                            | 2 +-
 .../filter/network/mysql_proxy/v1alpha1/mysql_proxy.proto       | 1 +
 .../network/zookeeper_proxy/v1alpha1/zookeeper_proxy.proto      | 1 +
 envoy/config/listener/v2/api_listener.proto                     | 2 ++
 envoy/config/listener/v3/api_listener.proto                     | 2 ++
 envoy/config/retry/omit_canary_hosts/v2/omit_canary_hosts.proto | 1 +
 envoy/config/retry/previous_hosts/v2/previous_hosts.proto       | 1 +
 .../retry/previous_priorities/previous_priorities_config.proto  | 2 ++
 .../extensions/filters/network/mysql_proxy/v3/mysql_proxy.proto | 1 +
 .../filters/network/zookeeper_proxy/v3/zookeeper_proxy.proto    | 1 +
 .../previous_priorities/v3/previous_priorities_config.proto     | 2 ++
 envoy/service/discovery/v2/ads.proto                            | 2 ++
 envoy/service/discovery/v2/hds.proto                            | 2 ++
 envoy/service/discovery/v2/sds.proto                            | 2 ++
 envoy/service/discovery/v3/ads.proto                            | 2 ++
 envoy/service/health/v3/hds.proto                               | 2 ++
 envoy/service/metrics/v2/metrics_service.proto                  | 2 ++
 envoy/service/metrics/v3/metrics_service.proto                  | 2 ++
 envoy/service/secret/v3/sds.proto                               | 2 ++
 envoy/service/trace/v2/trace_service.proto                      | 2 ++
 envoy/service/trace/v3/trace_service.proto                      | 2 ++
 envoy/type/http.proto                                           | 2 ++
 envoy/type/http_status.proto                                    | 2 ++
 envoy/type/v3/http.proto                                        | 2 ++
 envoy/type/v3/http_status.proto                                 | 2 ++
 30 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/envoy/admin/v2alpha/tap.proto b/envoy/admin/v2alpha/tap.proto
index 428fe8cd..d16ffdd7 100644
--- a/envoy/admin/v2alpha/tap.proto
+++ b/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.
diff --git a/envoy/admin/v3/tap.proto b/envoy/admin/v3/tap.proto
index 723b2bda..094753a6 100644
--- a/envoy/admin/v3/tap.proto
+++ b/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";
diff --git a/envoy/annotations/deprecation.proto b/envoy/annotations/deprecation.proto
index 813f1050..7f9b64e3 100644
--- a/envoy/annotations/deprecation.proto
+++ b/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>`.
diff --git a/envoy/annotations/resource.proto b/envoy/annotations/resource.proto
index b9dcf658..bd794c68 100644
--- a/envoy/annotations/resource.proto
+++ b/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;
diff --git a/envoy/api/v2/cluster/filter.proto b/envoy/api/v2/cluster/filter.proto
index 13600c43..67f3c3ba 100644
--- a/envoy/api/v2/cluster/filter.proto
+++ b/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>`.
diff --git a/envoy/config/cluster/v3/filter.proto b/envoy/config/cluster/v3/filter.proto
index 8f196cb0..9ded0fbb 100644
--- a/envoy/config/cluster/v3/filter.proto
+++ b/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";
 
diff --git a/envoy/config/filter/network/mysql_proxy/v1alpha1/mysql_proxy.proto b/envoy/config/filter/network/mysql_proxy/v1alpha1/mysql_proxy.proto
index 0d321985..ea63da92 100644
--- a/envoy/config/filter/network/mysql_proxy/v1alpha1/mysql_proxy.proto
+++ b/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>`.
diff --git a/envoy/config/filter/network/zookeeper_proxy/v1alpha1/zookeeper_proxy.proto b/envoy/config/filter/network/zookeeper_proxy/v1alpha1/zookeeper_proxy.proto
index cfe47dad..b802bbb0 100644
--- a/envoy/config/filter/network/zookeeper_proxy/v1alpha1/zookeeper_proxy.proto
+++ b/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>`.
diff --git a/envoy/config/listener/v2/api_listener.proto b/envoy/config/listener/v2/api_listener.proto
index 0cdcd091..3f974cad 100644
--- a/envoy/config/listener/v2/api_listener.proto
+++ b/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 {
diff --git a/envoy/config/listener/v3/api_listener.proto b/envoy/config/listener/v3/api_listener.proto
index 196d0c7b..c8c3ea11 100644
--- a/envoy/config/listener/v3/api_listener.proto
+++ b/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 {
diff --git a/envoy/config/retry/omit_canary_hosts/v2/omit_canary_hosts.proto b/envoy/config/retry/omit_canary_hosts/v2/omit_canary_hosts.proto
index 58c84d1a..b4cf8c0c 100644
--- a/envoy/config/retry/omit_canary_hosts/v2/omit_canary_hosts.proto
+++ b/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 {
 }
diff --git a/envoy/config/retry/previous_hosts/v2/previous_hosts.proto b/envoy/config/retry/previous_hosts/v2/previous_hosts.proto
index 3b4add3e..75532397 100644
--- a/envoy/config/retry/previous_hosts/v2/previous_hosts.proto
+++ b/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 {
 }
diff --git a/envoy/config/retry/previous_priorities/previous_priorities_config.proto b/envoy/config/retry/previous_priorities/previous_priorities_config.proto
index ead70bad..4e1703cd 100644
--- a/envoy/config/retry/previous_priorities/previous_priorities_config.proto
+++ b/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.
 //
diff --git a/envoy/extensions/filters/network/mysql_proxy/v3/mysql_proxy.proto b/envoy/extensions/filters/network/mysql_proxy/v3/mysql_proxy.proto
index b775ea44..08058740 100644
--- a/envoy/extensions/filters/network/mysql_proxy/v3/mysql_proxy.proto
+++ b/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";
diff --git a/envoy/extensions/filters/network/zookeeper_proxy/v3/zookeeper_proxy.proto b/envoy/extensions/filters/network/zookeeper_proxy/v3/zookeeper_proxy.proto
index 0abb9b28..863c43ee 100644
--- a/envoy/extensions/filters/network/zookeeper_proxy/v3/zookeeper_proxy.proto
+++ b/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";
diff --git a/envoy/extensions/retry/priority/previous_priorities/v3/previous_priorities_config.proto b/envoy/extensions/retry/priority/previous_priorities/v3/previous_priorities_config.proto
index 7b40882a..7d1edfbc 100644
--- a/envoy/extensions/retry/priority/previous_priorities/v3/previous_priorities_config.proto
+++ b/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.
 //
diff --git a/envoy/service/discovery/v2/ads.proto b/envoy/service/discovery/v2/ads.proto
index e2002ecf..01759e5f 100644
--- a/envoy/service/discovery/v2/ads.proto
+++ b/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
diff --git a/envoy/service/discovery/v2/hds.proto b/envoy/service/discovery/v2/hds.proto
index 39853d11..a0211685 100644
--- a/envoy/service/discovery/v2/hds.proto
+++ b/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
diff --git a/envoy/service/discovery/v2/sds.proto b/envoy/service/discovery/v2/sds.proto
index 7d790524..6a131ad4 100644
--- a/envoy/service/discovery/v2/sds.proto
+++ b/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";
 
diff --git a/envoy/service/discovery/v3/ads.proto b/envoy/service/discovery/v3/ads.proto
index 7f123859..beaae93b 100644
--- a/envoy/service/discovery/v3/ads.proto
+++ b/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
diff --git a/envoy/service/health/v3/hds.proto b/envoy/service/health/v3/hds.proto
index ed21a51b..af126ced 100644
--- a/envoy/service/health/v3/hds.proto
+++ b/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
diff --git a/envoy/service/metrics/v2/metrics_service.proto b/envoy/service/metrics/v2/metrics_service.proto
index bfe97097..5c9a039c 100644
--- a/envoy/service/metrics/v2/metrics_service.proto
+++ b/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 {
diff --git a/envoy/service/metrics/v3/metrics_service.proto b/envoy/service/metrics/v3/metrics_service.proto
index a432d4c5..16b4279e 100644
--- a/envoy/service/metrics/v3/metrics_service.proto
+++ b/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 {
diff --git a/envoy/service/secret/v3/sds.proto b/envoy/service/secret/v3/sds.proto
index e0a79eb7..e541ca98 100644
--- a/envoy/service/secret/v3/sds.proto
+++ b/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";
 
diff --git a/envoy/service/trace/v2/trace_service.proto b/envoy/service/trace/v2/trace_service.proto
index 76732038..81449dab 100644
--- a/envoy/service/trace/v2/trace_service.proto
+++ b/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 {
diff --git a/envoy/service/trace/v3/trace_service.proto b/envoy/service/trace/v3/trace_service.proto
index e82bf097..b33d3af7 100644
--- a/envoy/service/trace/v3/trace_service.proto
+++ b/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 {
diff --git a/envoy/type/http.proto b/envoy/type/http.proto
index 89944fd2..12160c63 100644
--- a/envoy/type/http.proto
+++ b/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;
 
diff --git a/envoy/type/http_status.proto b/envoy/type/http_status.proto
index 1f8ed6f8..e81c4f9d 100644
--- a/envoy/type/http_status.proto
+++ b/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 {
diff --git a/envoy/type/v3/http.proto b/envoy/type/v3/http.proto
index aa66a64f..2018b8a1 100644
--- a/envoy/type/v3/http.proto
+++ b/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;
 
diff --git a/envoy/type/v3/http_status.proto b/envoy/type/v3/http_status.proto
index 169c3460..ca990b17 100644
--- a/envoy/type/v3/http_status.proto
+++ b/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 {