Diagrams for client connection and client call pipelines. (#445)

* Diagrams for client connection and client call pipelines.

* Fix typo

Sources/SwiftGRPCNIO/ClientCalls/BaseClientCall.swift

@@ -22,6 +22,30 @@ import SwiftProtobuf
 /// This class provides much of the boilerplate for the four types of gRPC call objects returned to framework
 /// users.
 ///
+/// Each call will be configured on a multiplexed channel on the given connection. The multiplexed
+/// channel will be configured as such:
+///
+///                           ┌───────────────────────────┐
+///                           │ GRPCClientChannelHandler  │
+///                           └─▲───────────────────────┬─┘
+///   GRPCClientResponsePart<T1>│                       │GRPCClientRequestPart<T2>
+///                           ┌─┴───────────────────────▼─┐
+///                           │       GRPCClientCodec     │
+///                           └─▲───────────────────────┬─┘
+///    RawGRPCClientResponsePart│                       │RawGRPCClientRequestPart
+///                           ┌─┴───────────────────────▼─┐
+///                           │ HTTP1ToRawGRPCClientCodec │
+///                           └─▲───────────────────────┬─┘
+///       HTTPClientResponsePart│                       │HTTPClientRequestPart
+///                           ┌─┴───────────────────────▼─┐
+///                           │  HTTP2ToHTTP1ClientCodec  │
+///                           └─▲───────────────────────┬─┘
+///                   HTTP2Frame│                       │HTTP2Frame
+///                             |                       |
+///
+/// Note: below the `HTTP2ToHTTP1ClientCodec` is the "main" pipeline provided by the channel in
+/// `GRPCClientConnection`.
+///
 /// Setup includes:
 /// - creation of an HTTP/2 stream for the call to execute on,
 /// - configuration of the NIO channel handlers for the stream, and

Sources/SwiftGRPCNIO/GRPCClientConnection.swift

@@ -22,6 +22,35 @@ import NIOTLS
 /// Underlying channel and HTTP/2 stream multiplexer.
 ///
 /// Different service clients implementing `GRPCClient` may share an instance of this class.
+///
+/// The connection is initially setup with a handler to verify that TLS was established
+/// successfully (assuming TLS is being used).
+///
+///                          ▲                       |
+///                HTTP2Frame│                       │HTTP2Frame
+///                        ┌─┴───────────────────────▼─┐
+///                        │   HTTP2StreamMultiplexer  |
+///                        └─▲───────────────────────┬─┘
+///                HTTP2Frame│                       │HTTP2Frame
+///                        ┌─┴───────────────────────▼─┐
+///                        │       NIOHTTP2Handler     │
+///                        └─▲───────────────────────┬─┘
+///                ByteBuffer│                       │ByteBuffer
+///                        ┌─┴───────────────────────▼─┐
+///                        │ GRPCTLSVerificationHandler│
+///                        └─▲───────────────────────┬─┘
+///                ByteBuffer│                       │ByteBuffer
+///                        ┌─┴───────────────────────▼─┐
+///                        │       NIOSSLHandler       │
+///                        └─▲───────────────────────┬─┘
+///                ByteBuffer│                       │ByteBuffer
+///                          │                       ▼
+///
+/// The `GRPCTLSVerificationHandler` observes the outcome of the SSL handshake and determines
+/// whether a `GRPCClientConnection` should be returned to the user. In either eventuality, the
+/// handler removes itself from the pipeline once TLS has been verified.
+///
+/// See `BaseClientCall` for a description of the remainder of the client pipeline.
 open class GRPCClientConnection {
   /// Starts a connection to the given host and port.
   ///