cleanup: clarify Cluster.filters and Dispatcher::createClientConnecti…

…on (#8186)

Signed-off-by: Fred Douglas <[email protected]>

api/envoy/api/v2/cds.proto

@@ -647,9 +647,9 @@ message Cluster {
   // checking before removing it from the cluster.
   bool drain_connections_on_host_removal = 32;
 
-  // An optional list of network filters that make up the filter chain for
-  // outgoing connections made by the cluster. Order matters as the filters are
-  // processed sequentially as connection events happen.
+  // An (optional) network filter chain, listed in the order the filters should be applied.
+  // The chain will be applied to all outgoing connections that Envoy makes to the upstream
+  // servers of this cluster.
   repeated cluster.Filter filters = 40;
 
   // [#not-implemented-hide:] New mechanism for LB policy configuration. Used only if the

api/envoy/api/v3alpha/cds.proto

@@ -634,9 +634,9 @@ message Cluster {
   // checking before removing it from the cluster.
   bool drain_connections_on_host_removal = 32;
 
-  // An optional list of network filters that make up the filter chain for
-  // outgoing connections made by the cluster. Order matters as the filters are
-  // processed sequentially as connection events happen.
+  // An (optional) network filter chain, listed in the order the filters should be applied.
+  // The chain will be applied to all outgoing connections that Envoy makes to the upstream
+  // servers of this cluster.
   repeated cluster.Filter filters = 40;
 }
 

include/envoy/event/dispatcher.h

@@ -59,7 +59,7 @@ class Dispatcher {
   virtual TimeSource& timeSource() PURE;
 
   /**
-   * Initialize stats for this dispatcher. Note that this can't generally be done at construction
+   * Initializes stats for this dispatcher. Note that this can't generally be done at construction
    * time, since the main and worker thread dispatchers are constructed before
    * ThreadLocalStoreImpl::initializeThreading.
    * @param scope the scope to contain the new per-dispatcher stats created here.
@@ -68,12 +68,12 @@ class Dispatcher {
   virtual void initializeStats(Stats::Scope& scope, const std::string& prefix) PURE;
 
   /**
-   * Clear any items in the deferred deletion queue.
+   * Clears any items in the deferred deletion queue.
    */
   virtual void clearDeferredDeleteList() PURE;
 
   /**
-   * Create a server connection.
+   * Wraps an already-accepted socket in an instance of Envoy's server Network::Connection.
    * @param socket supplies an open file descriptor and connection metadata to use for the
    *        connection. Takes ownership of the socket.
    * @param transport_socket supplies a transport socket to be used by the connection.
@@ -84,7 +84,8 @@ class Dispatcher {
                          Network::TransportSocketPtr&& transport_socket) PURE;
 
   /**
-   * Create a client connection.
+   * Creates an instance of Envoy's Network::ClientConnection. Does NOT initiate the connection;
+   * the caller must then call connect() on the returned Network::ClientConnection.
    * @param address supplies the address to connect to.
    * @param source_address supplies an address to bind to or nullptr if no bind is necessary.
    * @param transport_socket supplies a transport socket to be used by the connection.
@@ -99,7 +100,7 @@ class Dispatcher {
                          const Network::ConnectionSocket::OptionsSharedPtr& options) PURE;
 
   /**
-   * Create an async DNS resolver. The resolver should only be used on the thread that runs this
+   * Creates an async DNS resolver. The resolver should only be used on the thread that runs this
    * dispatcher.
    * @param resolvers supplies the addresses of DNS resolvers that this resolver should use. If left
    * empty, it will not use any specific resolvers, but use defaults (/etc/resolv.conf)
@@ -109,7 +110,7 @@ class Dispatcher {
   createDnsResolver(const std::vector<Network::Address::InstanceConstSharedPtr>& resolvers) PURE;
 
   /**
-   * Create a file event that will signal when a file is readable or writable. On UNIX systems this
+   * Creates a file event that will signal when a file is readable or writable. On UNIX systems this
    * can be used for any file like interface (files, sockets, etc.).
    * @param fd supplies the fd to watch.
    * @param cb supplies the callback to fire when the file is ready.
@@ -126,7 +127,7 @@ class Dispatcher {
   virtual Filesystem::WatcherPtr createFilesystemWatcher() PURE;
 
   /**
-   * Create a listener on a specific port.
+   * Creates a listener on a specific port.
    * @param socket supplies the socket to listen on.
    * @param cb supplies the callbacks to invoke for listener events.
    * @param bind_to_port controls whether the listener binds to a transport port or not.
@@ -139,31 +140,31 @@ class Dispatcher {
                                               bool hand_off_restored_destination_connections) PURE;
 
   /**
-   * Create a logical udp listener on a specific port.
+   * Creates a logical udp listener on a specific port.
    * @param socket supplies the socket to listen on.
    * @param cb supplies the udp listener callbacks to invoke for listener events.
    * @return Network::ListenerPtr a new listener that is owned by the caller.
    */
   virtual Network::ListenerPtr createUdpListener(Network::Socket& socket,
                                                  Network::UdpListenerCallbacks& cb) PURE;
   /**
-   * Allocate a timer. @see Timer for docs on how to use the timer.
+   * Allocates a timer. @see Timer for docs on how to use the timer.
    * @param cb supplies the callback to invoke when the timer fires.
    */
   virtual Event::TimerPtr createTimer(TimerCb cb) PURE;
 
   /**
-   * Submit an item for deferred delete. @see DeferredDeletable.
+   * Submits an item for deferred delete. @see DeferredDeletable.
    */
   virtual void deferredDelete(DeferredDeletablePtr&& to_delete) PURE;
 
   /**
-   * Exit the event loop.
+   * Exits the event loop.
    */
   virtual void exit() PURE;
 
   /**
-   * Listen for a signal event. Only a single dispatcher in the process can listen for signals.
+   * Listens for a signal event. Only a single dispatcher in the process can listen for signals.
    * If more than one dispatcher calls this routine in the process the behavior is undefined.
    *
    * @param signal_num supplies the signal to listen on.
@@ -173,13 +174,13 @@ class Dispatcher {
   virtual SignalEventPtr listenForSignal(int signal_num, SignalCb cb) PURE;
 
   /**
-   * Post a functor to the dispatcher. This is safe cross thread. The functor runs in the context
+   * Posts a functor to the dispatcher. This is safe cross thread. The functor runs in the context
    * of the dispatcher event loop which may be on a different thread than the caller.
    */
   virtual void post(PostCb callback) PURE;
 
   /**
-   * Run the event loop. This will not return until exit() is called either from within a callback
+   * Runs the event loop. This will not return until exit() is called either from within a callback
    * or from a different thread.
    * @param type specifies whether to run in blocking mode (run() will not return until exit() is
    *              called) or non-blocking mode where only active events will be executed and then