Add comments

Author: fabianfett

Diff for: Sources/AsyncHTTPClient/ConnectionPool/State Machine/HTTP1Connections.swift renamed to Sources/AsyncHTTPClient/ConnectionPool/State Machine/HTTPConnectionPool+HTTP1Connections.swift

@@ -15,6 +15,7 @@
 import NIOCore
 
 extension HTTPConnectionPool {
+    /// Represents the state of a single HTTP/1.1 connection
     private struct HTTP1ConnectionState {
         enum State {
             /// the connection is creating a connection. Valid transitions are to: .backingOff, .available and .failed
@@ -161,10 +162,23 @@ extension HTTPConnectionPool {
     }
 
     /// A structure to hold the currently active HTTP/1.1 connections.
+    ///
+    /// The general purpose connection pool (pool for requests that don't have special `EventLoop`
+    /// requirements) will grow up until `maximumConcurrentConnections`. If requests have
+    /// special `EventLoop` requirements overflow connections might be opened.
+    ///
+    /// All connections live in the same `connections` array. In the front are the general purpose
+    /// connections. In the back (starting with the `overflowIndex`) are the connections for
+    /// requests with special needs.
     struct HTTP1Connections {
+        /// The maximum number of connections in the general purpose pool.
         private let maximumConcurrentConnections: Int
+        /// A connectionID generator.
         private let generator: Connection.ID.Generator
+        /// The connections states
         private var connections: [HTTP1ConnectionState]
+        /// The index after which you will find the connections for requests with `EventLoop`
+        /// requirements in `connections`.
         private var overflowIndex: Array<HTTP1ConnectionState>.Index
 
         init(maximumConcurrentConnections: Int, generator: Connection.ID.Generator) {