docs: minor edits for clarity (#305)

Links xDS earlier in API v2 overview. Removes line numbers from github xDS proto links.

Modifies xDS protocol doc to more clearly define xDS at the start.

Signed-off-by: Stephan Zuercher <stephan@turbinelabs.io>

XDS_PROTOCOL.md

@@ -1,9 +1,11 @@
 # xDS REST and gRPC protocol
 
-Envoy discovers its various dynamic xDS resources via the filesystem or by querying
-one or more management servers. Resources are requested via _subscriptions_, by
-either specifying a filesystem path to watch, initiating gRPC streams or
-REST-JSON polling. The latter two methods involve sending requests with a
+Envoy discovers its various dynamic resources via the filesystem or by querying
+one or more management servers. Collectively, these discovery services and their
+corresponding APIs are referred to as _xDS_. Resources are requested via
+_subscriptions_, by specifying a filesystem path to watch, initiating gRPC
+streams or polling a REST-JSON URL. The latter two methods involve sending
+requests with a
 [`DiscoveryRequest`](https://github.com/envoyproxy/data-plane-api/blob/1388a257bbeb423cadd3d8270ad6913849188283/api/discovery.proto#L24)
 proto payload. Resources are delivered in a
 [`DiscoveryResponse`](https://github.com/envoyproxy/data-plane-api/blob/1388a257bbeb423cadd3d8270ad6913849188283/api/discovery.proto#L53)
@@ -39,7 +41,7 @@ control of sequencing is required.
 #### Type URLs
 
 Each xDS API is concerned with resources of a given type. There is a 1:1
-correspondence between xDS API and a resource type. That is:
+correspondence between an xDS API and a resource type. That is:
 
 * [LDS: `envoy.api.v2.Listener`](api/lds.proto)
 * [RDS: `envoy.api.v2.RouteConfiguration`](api/rds.proto)
@@ -128,7 +130,7 @@ each response. An absent `Listener` or `Cluster` will be deleted.
 
 For EDS/RDS, the management server does not need to supply every requested
 resource and may also supply additional, unrequested resources, `resource_names`
-is only a hint.  Envoy will silently ignore any superfluous resources. When a
+is only a hint. Envoy will silently ignore any superfluous resources. When a
 requested resource is missing in a RDS or EDS update, Envoy will retain the last
 known value for this resource. The management server may be able to infer all
 the required EDS/RDS resources from the `node` identification in the
@@ -181,7 +183,7 @@ The management server should not send a `DiscoveryResponse` for any
 newer nonce being presented to Envoy in a `DiscoveryResponse`. A management
 server does not need to send an update until it determines a new version is
 available. Earlier requests at a version then also become stale. It may process
-multiple`DiscoveryRequests` at a version until a new version is ready.
+multiple `DiscoveryRequests` at a version until a new version is ready.
 
 ![Requests become stale](diagrams/stale-requests.svg)
 
@@ -271,5 +273,5 @@ persistent stream is maintained to the management server. It is expected that
 there is only a single outstanding request at any point in time, and as a result
 the response nonce is optional in REST-JSON. The [JSON canonical transform of
 proto3](https://developers.google.com/protocol-buffers/docs/proto3#json) is used
-to encode `DiscoveryRequest` and `DiscoveryResponse` messages.  ADS is not
+to encode `DiscoveryRequest` and `DiscoveryResponse` messages. ADS is not
 available for REST-JSON polling.

docs/root/configuration/overview/v2_overview.rst

@@ -7,10 +7,10 @@ The Envoy v2 APIs are defined as `proto3
 <https://developers.google.com/protocol-buffers/docs/proto3>`_ `Protocol Buffers
 <https://developers.google.com/protocol-buffers/>`_ in the `data plane API
 repository <https://github.com/envoyproxy/data-plane-api/tree/master/api>`_. They evolve the
-existing :ref:`v1 xDS APIs and concepts <config_overview_v1>` to support:
+existing :ref:`v1 APIs and concepts <config_overview_v1>` to support:
 
-* Streaming delivery of xDS API updates via gRPC. This reduces resource requirements and can
-  lower the update latency.
+* Streaming delivery of `xDS <https://github.com/envoyproxy/data-plane-api/blob/master/XDS_PROTOCOL.md>`_
+  API updates via gRPC. This reduces resource requirements and can lower the update latency.
 * A new REST-JSON API in which the JSON/YAML formats are derived mechanically via the `proto3
   canonical JSON mapping
   <https://developers.google.com/protocol-buffers/docs/proto3#json>`_.
@@ -47,11 +47,11 @@ debug experience when configuration parsing fails.
 The :ref:`Bootstrap <envoy_api_msg_Bootstrap>` message is the root of the
 configuration. A key concept in the :ref:`Bootstrap <envoy_api_msg_Bootstrap>`
 message is the distinction between static and dynamic resouces.  Resources such
-as a :ref:`Listener <config_listeners>` or :ref:`Cluster
-<config_cluster_manager_cluster>` may be supplied either statically in
+as a :ref:`Listener <envoy_api_msg_Listener>` or :ref:`Cluster
+<envoy_api_msg_Cluster>` may be supplied either statically in
 :ref:`static_resources <envoy_api_field_Bootstrap.static_resources>` or have
 an xDS service such as :ref:`LDS
-<config_overview_lds>` or :ref:`CDS <config_cluster_manager_cds>` configured in
+<config_listeners_lds>` or :ref:`CDS <config_cluster_manager_cds>` configured in
 :ref:`dynamic_resources <envoy_api_field_Bootstrap.dynamic_resources>`.
 
 Example
@@ -305,7 +305,7 @@ gRPC streaming endpoints
 .. http:post:: /envoy.api.v2.ClusterDiscoveryService/StreamClusters
 
 See `cds.proto
-<https://github.com/envoyproxy/data-plane-api/blob/master/api/cds.proto#L18>`_
+<https://github.com/envoyproxy/data-plane-api/blob/master/api/cds.proto>`_
 for the service definition. This is used by Envoy as a client when
 
 .. code-block:: yaml
@@ -322,7 +322,7 @@ is set in the :ref:`dynamic_resources
 .. http:post:: /envoy.api.v2.EndpointDiscoveryService/StreamEndpoints
 
 See `eds.proto
-<https://github.com/envoyproxy/data-plane-api/blob/master/api/eds.proto#L13>`_
+<https://github.com/envoyproxy/data-plane-api/blob/master/api/eds.proto>`_
 for the service definition. This is used by Envoy as a client when
 
 .. code-block:: yaml
@@ -339,7 +339,7 @@ is set in the :ref:`eds_cluster_config
 .. http:post:: /envoy.api.v2.ListenerDiscoveryService/StreamListeners
 
 See `lds.proto
-<https://github.com/envoyproxy/data-plane-api/blob/master/api/lds.proto#L22>`_
+<https://github.com/envoyproxy/data-plane-api/blob/master/api/lds.proto>`_
 for the service definition. This is used by Envoy as a client when
 
 .. code-block:: yaml
@@ -356,7 +356,7 @@ is set in the :ref:`dynamic_resources
 .. http:post:: /envoy.api.v2.RouteDiscoveryService/StreamRoutes
 
 See `rds.proto
-<https://github.com/envoyproxy/data-plane-api/blob/master/api/rds.proto#L22>`_
+<https://github.com/envoyproxy/data-plane-api/blob/master/api/rds.proto>`_
 for the service definition. This is used by Envoy as a client when
 
 .. code-block:: yaml
@@ -377,7 +377,7 @@ REST endpoints
 .. http:post:: /v2/discovery:clusters
 
 See `cds.proto
-<https://github.com/envoyproxy/data-plane-api/blob/master/api/cds.proto#L18>`_
+<https://github.com/envoyproxy/data-plane-api/blob/master/api/cds.proto>`_
 for the service definition. This is used by Envoy as a client when
 
 .. code-block:: yaml
@@ -394,7 +394,7 @@ is set in the :ref:`dynamic_resources
 .. http:post:: /v2/discovery:endpoints
 
 See `eds.proto
-<https://github.com/envoyproxy/data-plane-api/blob/master/api/eds.proto#L13>`_
+<https://github.com/envoyproxy/data-plane-api/blob/master/api/eds.proto>`_
 for the service definition. This is used by Envoy as a client when
 
 .. code-block:: yaml
@@ -411,7 +411,7 @@ is set in the :ref:`eds_cluster_config
 .. http:post:: /v2/discovery:listeners
 
 See `lds.proto
-<https://github.com/envoyproxy/data-plane-api/blob/master/api/lds.proto#L22>`_
+<https://github.com/envoyproxy/data-plane-api/blob/master/api/lds.proto>`_
 for the service definition. This is used by Envoy as a client when
 
 .. code-block:: yaml
@@ -428,7 +428,7 @@ is set in the :ref:`dynamic_resources
 .. http:post:: /v2/discovery:routes
 
 See `rds.proto
-<https://github.com/envoyproxy/data-plane-api/blob/master/api/rds.proto#L22>`_
+<https://github.com/envoyproxy/data-plane-api/blob/master/api/rds.proto>`_
 for the service definition. This is used by Envoy as a client when
 
 .. code-block:: yaml
@@ -448,13 +448,13 @@ is set in the :ref:`rds
 Aggregated Discovery Service
 ----------------------------
 
-While fundamentally Envoy employs an eventual consistency model, ADS provides an
+While Envoy fundamentally employs an eventual consistency model, ADS provides an
 opportunity to sequence API update pushes and ensure affinity of a single
 management server for an Envoy node for API updates. ADS allows one or more APIs
-to be delivered on a single gRPC bidi stream by the management server, and
-within an API to have all resources aggregated onto a single stream. Without
-this, some APIs such as RDS and EDS may require the management of multiple
-streams and connections to distinct management servers.
+and their resources to be delivered on a single, bidirectional gRPC stream by
+the management server. Without this, some APIs such as RDS and EDS may require
+the management of multiple streams and connections to distinct management
+servers.
 
 ADS will allow for hitless updates of configuration by appropriate sequencing.
 For example, suppose *foo.com* was mappped to cluster *X*. We wish to change the
@@ -478,7 +478,7 @@ document.  The gRPC endpoint is:
 .. http:post:: /envoy.api.v2.AggregatedDiscoveryService/StreamAggregatedResources
 
 See `discovery.proto
-<https://github.com/envoyproxy/data-plane-api/blob/master/api/discovery.proto#L15>`_
+<https://github.com/envoyproxy/data-plane-api/blob/master/api/discovery.proto>`_
 for the service definition. This is used by Envoy as a client when
 
 .. code-block:: yaml