docs: clarify IP vs hostname rules for SocketAddress (#3612)

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

Mirrored from https://github.com/envoyproxy/envoy @ 1e33007267745873dff7b41b2c8e2cb2d3bca709

envoy/api/v2/core/address.proto

@@ -28,14 +28,16 @@ message SocketAddress {
   }
   Protocol protocol = 1 [(validate.rules).enum.defined_only = true];
   // The address for this socket. :ref:`Listeners <config_listeners>` will bind
-  // to the address or outbound connections will be made. An empty address is
-  // not allowed, specify ``0.0.0.0`` or ``::`` to bind any. It's still possible to
-  // distinguish on an address via the prefix/suffix matching in
-  // FilterChainMatch after connection. For :ref:`clusters
-  // <config_cluster_manager_cluster>`, an address may be either an IP or
-  // hostname to be resolved via DNS. If it is a hostname, :ref:`resolver_name
-  // <envoy_api_field_core.SocketAddress.resolver_name>` should be set unless default
-  // (i.e. DNS) resolution is expected.
+  // to the address. An empty address is not allowed. Specify ``0.0.0.0`` or ``::``
+  // to bind to any address. [#comment:TODO(zuercher) reinstate when implemented:
+  // It is possible to distinguish a Listener address via the prefix/suffix matching
+  // in :ref:`FilterChainMatch <envoy_api_msg_listener.FilterChainMatch>`.] When used
+  // within an upstream :ref:`BindConfig <envoy_api_msg_core.BindConfig>`, the address
+  // controls the source address of outbound connections. For :ref:`clusters
+  // <config_cluster_manager_cluster>`, the cluster type determines whether the
+  // address must be an IP (*STATIC* or *EDS* clusters) or a hostname resolved by DNS
+  // (*STRICT_DNS* or *LOGICAL_DNS* clusters). Address resolution can be customized
+  // via :ref:`resolver_name <envoy_api_field_core.SocketAddress.resolver_name>`.
   string address = 2 [(validate.rules).string.min_bytes = 1];
   oneof port_specifier {
     option (validate.required) = true;

envoy/api/v2/endpoint/endpoint.proto

@@ -22,7 +22,7 @@ message Endpoint {
   //
   // .. attention::
   //
-  //   The form of host address depends on the given cluster type. For STATIC,
+  //   The form of host address depends on the given cluster type. For STATIC or EDS,
   //   it is expected to be a direct IP address (or something resolvable by the
   //   specified :ref:`resolver <envoy_api_field_core.SocketAddress.resolver_name>`
   //   in the Address). For LOGICAL or STRICT DNS, it is expected to be hostname,