docs: clean up discovery docs and make it consistent (#39913)

## Description

This PR have some cleanup in Discovery Proto for consistency. We are
using the backticks inconsistently throughout right now and there are
many places where we could convert the items in a list format rather
than keeping it in the form of a paragraph.

---

**Commit Message:** docs: clean up discovery docs and make it consistent
**Additional Description:** Minor clean up for added clarity on the
discovery docs.
**Risk Level:** N/A
**Testing:** N/A
**Docs Changes:** N/A
**Release Notes:** N/A

Signed-off-by: Rohit Agrawal <[email protected]>

Mirrored from https://github.com/envoyproxy/envoy @ 51184341e5abf0a6e5f6b531f88425729226a506

Author: update-envoy[bot]

envoy/service/discovery/v3/discovery.proto

@@ -58,12 +58,12 @@ message ResourceError {
 message DiscoveryRequest {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.DiscoveryRequest";
 
-  // The version_info provided in the request messages will be the version_info
+  // The ``version_info`` provided in the request messages will be the ``version_info``
   // received with the most recent successfully processed response or empty on
   // the first request. It is expected that no new request is sent after a
   // response is received until the Envoy instance is ready to ACK/NACK the new
   // configuration. ACK/NACK takes place by returning the new API config version
-  // as applied or the previous API config version respectively. Each type_url
+  // as applied or the previous API config version respectively. Each ``type_url``
   // (see below) has an independent version associated with it.
   string version_info = 1;
 
@@ -72,32 +72,38 @@ message DiscoveryRequest {
 
   // List of resources to subscribe to, e.g. list of cluster names or a route
   // configuration name. If this is empty, all resources for the API are
-  // returned. LDS/CDS may have empty resource_names, which will cause all
+  // returned. LDS/CDS may have empty ``resource_names``, which will cause all
   // resources for the Envoy instance to be returned. The LDS and CDS responses
   // will then imply a number of resources that need to be fetched via EDS/RDS,
-  // which will be explicitly enumerated in resource_names.
+  // which will be explicitly enumerated in ``resource_names``.
   repeated string resource_names = 3;
 
   // [#not-implemented-hide:]
   // Alternative to ``resource_names`` field that allows specifying dynamic
   // parameters along with each resource name. Clients that populate this
   // field must be able to handle responses from the server where resources
   // are wrapped in a Resource message.
-  // Note that it is legal for a request to have some resources listed
-  // in ``resource_names`` and others in ``resource_locators``.
+  //
+  // .. note::
+  //   It is legal for a request to have some resources listed
+  //   in ``resource_names`` and others in ``resource_locators``.
+  //
   repeated ResourceLocator resource_locators = 7;
 
   // Type of the resource that is being requested, e.g.
-  // "type.googleapis.com/envoy.api.v2.ClusterLoadAssignment". This is implicit
+  // ``type.googleapis.com/envoy.api.v2.ClusterLoadAssignment``. This is implicit
   // in requests made via singleton xDS APIs such as CDS, LDS, etc. but is
   // required for ADS.
   string type_url = 4;
 
-  // nonce corresponding to DiscoveryResponse being ACK/NACKed. See above
-  // discussion on version_info and the DiscoveryResponse nonce comment. This
-  // may be empty only if 1) this is a non-persistent-stream xDS such as HTTP,
-  // or 2) the client has not yet accepted an update in this xDS stream (unlike
-  // delta, where it is populated only for new explicit ACKs).
+  // nonce corresponding to ``DiscoveryResponse`` being ACK/NACKed. See above
+  // discussion on ``version_info`` and the ``DiscoveryResponse`` nonce comment. This
+  // may be empty only if:
+  //
+  // * This is a non-persistent-stream xDS such as HTTP, or
+  // * The client has not yet accepted an update in this xDS stream (unlike
+  //   delta, where it is populated only for new explicit ACKs).
+  //
   string response_nonce = 5;
 
   // This is populated when the previous :ref:`DiscoveryResponse <envoy_v3_api_msg_service.discovery.v3.DiscoveryResponse>`
@@ -120,30 +126,34 @@ message DiscoveryResponse {
   // [#not-implemented-hide:]
   // Canary is used to support two Envoy command line flags:
   //
-  // * --terminate-on-canary-transition-failure. When set, Envoy is able to
+  // * ``--terminate-on-canary-transition-failure``. When set, Envoy is able to
   //   terminate if it detects that configuration is stuck at canary. Consider
   //   this example sequence of updates:
-  //   - Management server applies a canary config successfully.
-  //   - Management server rolls back to a production config.
-  //   - Envoy rejects the new production config.
+  //
+  //   * Management server applies a canary config successfully.
+  //   * Management server rolls back to a production config.
+  //   * Envoy rejects the new production config.
+  //
   //   Since there is no sensible way to continue receiving configuration
   //   updates, Envoy will then terminate and apply production config from a
   //   clean slate.
-  // * --dry-run-canary. When set, a canary response will never be applied, only
+  //
+  // * ``--dry-run-canary``. When set, a canary response will never be applied, only
   //   validated via a dry run.
+  //
   bool canary = 3;
 
   // Type URL for resources. Identifies the xDS API when muxing over ADS.
-  // Must be consistent with the type_url in the 'resources' repeated Any (if non-empty).
+  // Must be consistent with the ``type_url`` in the 'resources' repeated Any (if non-empty).
   string type_url = 4;
 
   // For gRPC based subscriptions, the nonce provides a way to explicitly ack a
-  // specific DiscoveryResponse in a following DiscoveryRequest. Additional
+  // specific ``DiscoveryResponse`` in a following ``DiscoveryRequest``. Additional
   // messages may have been sent by Envoy to the management server for the
-  // previous version on the stream prior to this DiscoveryResponse, that were
+  // previous version on the stream prior to this ``DiscoveryResponse``, that were
   // unprocessed at response send time. The nonce allows the management server
-  // to ignore any further DiscoveryRequests for the previous version until a
-  // DiscoveryRequest bearing the nonce. The nonce is optional and is not
+  // to ignore any further ``DiscoveryRequests`` for the previous version until a
+  // ``DiscoveryRequest`` bearing the nonce. The nonce is optional and is not
   // required for non-stream based xDS implementations.
   string nonce = 5;
 
@@ -171,25 +181,28 @@ message DiscoveryResponse {
 // connected to it.
 //
 // In Delta xDS the nonce field is required and used to pair
-// DeltaDiscoveryResponse to a DeltaDiscoveryRequest ACK or NACK.
-// Optionally, a response message level system_version_info is present for
+// ``DeltaDiscoveryResponse`` to a ``DeltaDiscoveryRequest`` ACK or NACK.
+// Optionally, a response message level ``system_version_info`` is present for
 // debugging purposes only.
 //
-// DeltaDiscoveryRequest plays two independent roles. Any DeltaDiscoveryRequest
-// can be either or both of: [1] informing the server of what resources the
-// client has gained/lost interest in (using resource_names_subscribe and
-// resource_names_unsubscribe), or [2] (N)ACKing an earlier resource update from
-// the server (using response_nonce, with presence of error_detail making it a NACK).
-// Additionally, the first message (for a given type_url) of a reconnected gRPC stream
+// ``DeltaDiscoveryRequest`` plays two independent roles. Any ``DeltaDiscoveryRequest``
+// can be either or both of:
+//
+// * Informing the server of what resources the client has gained/lost interest in
+//   (using ``resource_names_subscribe`` and ``resource_names_unsubscribe``), or
+// * (N)ACKing an earlier resource update from the server (using ``response_nonce``,
+//   with presence of ``error_detail`` making it a NACK).
+//
+// Additionally, the first message (for a given ``type_url``) of a reconnected gRPC stream
 // has a third role: informing the server of the resources (and their versions)
-// that the client already possesses, using the initial_resource_versions field.
+// that the client already possesses, using the ``initial_resource_versions`` field.
 //
 // As with state-of-the-world, when multiple resource types are multiplexed (ADS),
-// all requests/acknowledgments/updates are logically walled off by type_url:
+// all requests/acknowledgments/updates are logically walled off by ``type_url``:
 // a Cluster ACK exists in a completely separate world from a prior Route NACK.
-// In particular, initial_resource_versions being sent at the "start" of every
-// gRPC stream actually entails a message for each type_url, each with its own
-// initial_resource_versions.
+// In particular, ``initial_resource_versions`` being sent at the "start" of every
+// gRPC stream actually entails a message for each ``type_url``, each with its own
+// ``initial_resource_versions``.
 // [#next-free-field: 10]
 message DeltaDiscoveryRequest {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.DeltaDiscoveryRequest";
@@ -205,23 +218,24 @@ message DeltaDiscoveryRequest {
 
   // DeltaDiscoveryRequests allow the client to add or remove individual
   // resources to the set of tracked resources in the context of a stream.
-  // All resource names in the resource_names_subscribe list are added to the
-  // set of tracked resources and all resource names in the resource_names_unsubscribe
+  // All resource names in the ``resource_names_subscribe`` list are added to the
+  // set of tracked resources and all resource names in the ``resource_names_unsubscribe``
   // list are removed from the set of tracked resources.
   //
-  // *Unlike* state-of-the-world xDS, an empty resource_names_subscribe or
-  // resource_names_unsubscribe list simply means that no resources are to be
+  // *Unlike* state-of-the-world xDS, an empty ``resource_names_subscribe`` or
+  // ``resource_names_unsubscribe`` list simply means that no resources are to be
   // added or removed to the resource list.
   // *Like* state-of-the-world xDS, the server must send updates for all tracked
   // resources, but can also send updates for resources the client has not subscribed to.
   //
-  // NOTE: the server must respond with all resources listed in resource_names_subscribe,
-  // even if it believes the client has the most recent version of them. The reason:
-  // the client may have dropped them, but then regained interest before it had a chance
-  // to send the unsubscribe message. See DeltaSubscriptionStateTest.RemoveThenAdd.
+  // .. note::
+  //   The server must respond with all resources listed in ``resource_names_subscribe``,
+  //   even if it believes the client has the most recent version of them. The reason:
+  //   the client may have dropped them, but then regained interest before it had a chance
+  //   to send the unsubscribe message. See DeltaSubscriptionStateTest.RemoveThenAdd.
   //
-  // These two fields can be set in any DeltaDiscoveryRequest, including ACKs
-  // and initial_resource_versions.
+  // These two fields can be set in any ``DeltaDiscoveryRequest``, including ACKs
+  // and ``initial_resource_versions``.
   //
   // A list of Resource names to add to the list of tracked resources.
   repeated string resource_names_subscribe = 3;
@@ -232,31 +246,40 @@ message DeltaDiscoveryRequest {
   // [#not-implemented-hide:]
   // Alternative to ``resource_names_subscribe`` field that allows specifying dynamic parameters
   // along with each resource name.
-  // Note that it is legal for a request to have some resources listed
-  // in ``resource_names_subscribe`` and others in ``resource_locators_subscribe``.
+  //
+  // .. note::
+  //   It is legal for a request to have some resources listed
+  //   in ``resource_names_subscribe`` and others in ``resource_locators_subscribe``.
+  //
   repeated ResourceLocator resource_locators_subscribe = 8;
 
   // [#not-implemented-hide:]
   // Alternative to ``resource_names_unsubscribe`` field that allows specifying dynamic parameters
   // along with each resource name.
-  // Note that it is legal for a request to have some resources listed
-  // in ``resource_names_unsubscribe`` and others in ``resource_locators_unsubscribe``.
+  //
+  // .. note::
+  //   It is legal for a request to have some resources listed
+  //   in ``resource_names_unsubscribe`` and others in ``resource_locators_unsubscribe``.
+  //
   repeated ResourceLocator resource_locators_unsubscribe = 9;
 
   // Informs the server of the versions of the resources the xDS client knows of, to enable the
   // client to continue the same logical xDS session even in the face of gRPC stream reconnection.
-  // It will not be populated: [1] in the very first stream of a session, since the client will
-  // not yet have any resources,  [2] in any message after the first in a stream (for a given
-  // type_url), since the server will already be correctly tracking the client's state.
-  // (In ADS, the first message *of each type_url* of a reconnected stream populates this map.)
+  // It will not be populated:
+  //
+  // * In the very first stream of a session, since the client will not yet have any resources.
+  // * In any message after the first in a stream (for a given ``type_url``), since the server will
+  //   already be correctly tracking the client's state.
+  //
+  // (In ADS, the first message ``of each type_url`` of a reconnected stream populates this map.)
   // The map's keys are names of xDS resources known to the xDS client.
   // The map's values are opaque resource versions.
   map<string, string> initial_resource_versions = 5;
 
-  // When the DeltaDiscoveryRequest is a ACK or NACK message in response
-  // to a previous DeltaDiscoveryResponse, the response_nonce must be the
-  // nonce in the DeltaDiscoveryResponse.
-  // Otherwise (unlike in DiscoveryRequest) response_nonce must be omitted.
+  // When the ``DeltaDiscoveryRequest`` is a ACK or NACK message in response
+  // to a previous ``DeltaDiscoveryResponse``, the ``response_nonce`` must be the
+  // nonce in the ``DeltaDiscoveryResponse``.
+  // Otherwise (unlike in ``DiscoveryRequest``) ``response_nonce`` must be omitted.
   string response_nonce = 6;
 
   // This is populated when the previous :ref:`DiscoveryResponse <envoy_v3_api_msg_service.discovery.v3.DiscoveryResponse>`
@@ -274,44 +297,46 @@ message DeltaDiscoveryResponse {
   string system_version_info = 1;
 
   // The response resources. These are typed resources, whose types must match
-  // the type_url field.
+  // the ``type_url`` field.
   repeated Resource resources = 2;
 
   // field id 3 IS available!
 
   // Type URL for resources. Identifies the xDS API when muxing over ADS.
-  // Must be consistent with the type_url in the Any within 'resources' if 'resources' is non-empty.
+  // Must be consistent with the ``type_url`` in the Any within 'resources' if 'resources' is non-empty.
   string type_url = 4;
 
-  // Resources names of resources that have be deleted and to be removed from the xDS Client.
+  // Resource names of resources that have been deleted and to be removed from the xDS Client.
   // Removed resources for missing resources can be ignored.
   repeated string removed_resources = 6;
 
-  // Alternative to removed_resources that allows specifying which variant of
+  // Alternative to ``removed_resources`` that allows specifying which variant of
   // a resource is being removed. This variant must be used for any resource
   // for which dynamic parameter constraints were sent to the client.
   repeated ResourceName removed_resource_names = 8;
 
-  // The nonce provides a way for DeltaDiscoveryRequests to uniquely
-  // reference a DeltaDiscoveryResponse when (N)ACKing. The nonce is required.
+  // The nonce provides a way for ``DeltaDiscoveryRequests`` to uniquely
+  // reference a ``DeltaDiscoveryResponse`` when (N)ACKing. The nonce is required.
   string nonce = 5;
 
   // [#not-implemented-hide:]
   // The control plane instance that sent the response.
   config.core.v3.ControlPlane control_plane = 7;
 
   // [#not-implemented-hide:]
-  // Errors associated with specific resources. Note that a resource in
-  // this field with a status of NOT_FOUND should be treated the same as
-  // a resource listed in the 'removed_resources' or 'removed_resource_names'
-  // fields.
+  // Errors associated with specific resources.
+  //
+  // .. note::
+  //   A resource in this field with a status of NOT_FOUND should be treated the same as
+  //   a resource listed in the ``removed_resources`` or ``removed_resource_names`` fields.
+  //
   repeated ResourceError resource_errors = 9;
 }
 
 // A set of dynamic parameter constraints associated with a variant of an individual xDS resource.
 // These constraints determine whether the resource matches a subscription based on the set of
 // dynamic parameters in the subscription, as specified in the
-// :ref:`ResourceLocator.dynamic_parameters<envoy_v3_api_field_service.discovery.v3.ResourceLocator.dynamic_parameters>`
+// :ref:`ResourceLocator.dynamic_parameters <envoy_v3_api_field_service.discovery.v3.ResourceLocator.dynamic_parameters>`
 // field. This allows xDS implementations (clients, servers, and caching proxies) to determine
 // which variant of a resource is appropriate for a given client.
 message DynamicParameterConstraints {
@@ -365,8 +390,11 @@ message Resource {
   // [#not-implemented-hide:]
   message CacheControl {
     // If true, xDS proxies may not cache this resource.
-    // Note that this does not apply to clients other than xDS proxies, which must cache resources
-    // for their own use, regardless of the value of this field.
+    //
+    // .. note::
+    //   This does not apply to clients other than xDS proxies, which must cache resources
+    //   for their own use, regardless of the value of this field.
+    //
     bool do_not_cache = 1;
   }
 
@@ -396,7 +424,7 @@ message Resource {
   // configuration for the resource will be removed.
   //
   // The TTL can be refreshed or changed by sending a response that doesn't change the resource
-  // version. In this case the resource field does not need to be populated, which allows for
+  // version. In this case the ``resource`` field does not need to be populated, which allows for
   // light-weight "heartbeat" updates to keep a resource with a TTL alive.
   //
   // The TTL feature is meant to support configurations that should be removed in the event of