Spelling, grammar, punctuation, and docc warning fixes (#628)

Author: heckj

Sources/ConnectionPoolModule/ConnectionPool.swift

@@ -14,13 +14,13 @@ public struct ConnectionAndMetadata<Connection: PooledConnection>: Sendable {
 
 /// A connection that can be pooled in a ``ConnectionPool``
 public protocol PooledConnection: AnyObject, Sendable {
-    /// The connections identifier type.
+    /// The connection's identifier type.
     associatedtype ID: Hashable & Sendable
 
-    /// The connections identifier. The identifier is passed to
+    /// The connection's identifier. The identifier is passed to
     /// the connection factory method and must stay attached to
     /// the connection at all times. It must not change during
-    /// the connections lifetime.
+    /// the connection's lifetime.
     var id: ID { get }
 
     /// A method to register closures that are invoked when the
@@ -45,25 +45,25 @@ public protocol PooledConnection: AnyObject, Sendable {
     func close()
 }
 
-/// A connection id generator. Its returned connection IDs will
-/// be used when creating new ``PooledConnection``s
+/// A connection ID generator. Its returned connection IDs will
+/// be used when creating new ``PooledConnection``s.
 public protocol ConnectionIDGeneratorProtocol: Sendable {
-    /// The connections identifier type.
+    /// The connection's identifier type.
     associatedtype ID: Hashable & Sendable
 
     /// The next connection ID that shall be used.
     func next() -> ID
 }
 
-/// A keep alive behavior for connections maintained by the pool
+/// A keep-alive behavior for connections maintained by the pool.
 @available(macOS 13.0, iOS 16.0, tvOS 16.0, watchOS 9.0, *)
 public protocol ConnectionKeepAliveBehavior: Sendable {
-    /// the connection type
+    /// The connection type.
     associatedtype Connection: PooledConnection
 
     /// The time after which a keep-alive shall
     /// be triggered.
-    /// If nil is returned, keep-alive is deactivated
+    /// If `nil` is returned, keep-alive is deactivated.
     var keepAliveFrequency: Duration? { get }
 
     /// This method is invoked when the keep-alive shall be
@@ -75,7 +75,7 @@ public protocol ConnectionKeepAliveBehavior: Sendable {
 public protocol ConnectionRequestProtocol: Sendable {
     /// A connection lease request ID type.
     associatedtype ID: Hashable & Sendable
-    /// The leased connection type
+    /// The leased connection type.
     associatedtype Connection: PooledConnection
 
     /// A connection lease request ID. This ID must be generated
@@ -95,7 +95,7 @@ public protocol ConnectionRequestProtocol: Sendable {
 public struct ConnectionPoolConfiguration: Sendable {
     /// The minimum number of connections to preserve in the pool.
     ///
-    /// If the pool is mostly idle and the remote servers closes
+    /// If the pool is mostly idle and the remote server closes
     /// idle connections,
     /// the `ConnectionPool` will initiate new outbound
     /// connections proactively to avoid the number of available
@@ -111,23 +111,23 @@ public struct ConnectionPoolConfiguration: Sendable {
     /// The maximum number of connections for this pool, that can
     /// exist at any point in time. The pool can create _overflow_
     /// connections, if all connections are leased, and the
-    /// `maximumConnectionHardLimit` > `maximumConnectionSoftLimit `
+    /// `maximumConnectionHardLimit` > `maximumConnectionSoftLimit`.
     /// Overflow connections are closed immediately as soon as they
     /// become idle.
     public var maximumConnectionHardLimit: Int
 
-    /// The amount of time to pass between the first failed connection
+    /// The amount of time after the first failed connection attempt
     /// before triggering the circuit breaker.
     public var circuitBreakerTripAfter: Duration
 
     /// The time that a _preserved_ idle connection stays in the
     /// pool before it is closed.
     public var idleTimeout: Duration
 
-    /// Maximum number of in-progress new connection requests to run at any one time
+    /// Maximum number of in-progress new connection requests to run at any one time.
     public var maximumConcurrentConnectionRequests: Int
 
-    /// initializer
+    /// Creates a new connection pool configuration.
     public init() {
         self.minimumConnectionCount = 0
         self.maximumConnectionSoftLimit = 16
@@ -270,7 +270,7 @@ public final class ConnectionPool<
     }
 
     /// Mark a connection as going away. Connection implementors have to call this method if the connection
-    /// has received a close intent from the server. For example: an HTTP/2 GOWAY frame.
+    /// has received a close intent from the server. For example: an HTTP/2 GOAWAY frame.
     public func connectionWillClose(_ connection: Connection) {
 
     }

Sources/ConnectionPoolModule/ConnectionPoolError.swift

@@ -13,17 +13,17 @@ public struct ConnectionPoolError: Error, Hashable {
     @inlinable
     init(_ base: Base) { self.base = base }
 
-    /// The connection requests got cancelled
+    /// The connection request was cancelled.
     @inlinable
     public static var requestCancelled: Self {
         ConnectionPoolError(.requestCancelled)
     }
-    /// The connection requests can't be fulfilled as the pool has already been shutdown
+    /// The connection request can't be fulfilled because the pool has already been shut down.
     @inlinable
     public static var poolShutdown: Self {
         ConnectionPoolError(.poolShutdown)
     }
-    /// The connection pool has failed to make a connection after a defined time
+    /// The connection pool has failed to make a connection after a defined time.
     @inlinable
     public static var connectionCreationCircuitBreakerTripped: Self {
         ConnectionPoolError(.connectionCreationCircuitBreakerTripped)

Sources/ConnectionPoolModule/ConnectionPoolObservabilityDelegate.swift

@@ -16,7 +16,7 @@ public protocol ConnectionPoolObservabilityDelegate: Sendable {
     /// time and is reported via ````. The
     func connectSucceeded(id: ConnectionID, streamCapacity: UInt16)
 
-    /// The utlization of the connection changed; a stream may have been used, returned or the
+    /// The utilization of the connection changed; a stream may have been used, returned, or the
     /// maximum number of concurrent streams available on the connection changed.
     func connectionUtilizationChanged(id:ConnectionID, streamsUsed: UInt16, streamCapacity: UInt16)
 

Sources/ConnectionPoolModule/NIOLock.swift

@@ -138,7 +138,7 @@ final class LockStorage<Value>: ManagedBuffer<Value, LockPrimitive> {
         let buffer = Self.create(minimumCapacity: 1) { _ in
             value
         }
-        // Intentionally using a force cast here to avoid a miss compiliation in 5.10.
+        // Intentionally using a force cast here to avoid a miscompilation in 5.10.
         // This is as fast as an unsafeDownCast since ManagedBuffer is inlined and the optimizer
         // can eliminate the upcast/downcast pair
         let storage = buffer as! Self

Sources/ConnectionPoolModule/PoolStateMachine+ConnectionGroup.swift

@@ -73,7 +73,7 @@ extension PoolStateMachine {
         @usableFromInline
         let generator: ConnectionIDGenerator
 
-        /// The connections states
+        /// The connection states.
         @usableFromInline
         private(set) var connections: [ConnectionState]
 
@@ -126,8 +126,7 @@ extension PoolStateMachine {
         /// Information around an idle connection.
         @usableFromInline
         struct AvailableConnectionContext {
-            /// The connection's use. Either general purpose or for requests with `EventLoop`
-            /// requirements.
+            /// The connection's use: persisted, demand, or overflow.
             @usableFromInline
             var use: ConnectionUse
 
@@ -319,7 +318,7 @@ extension PoolStateMachine {
             }
 
             guard let index = self.findAvailableConnection() else {
-                preconditionFailure("Stats and actual count are of.")
+                preconditionFailure("Stats and actual count are off.")
             }
 
             return self.leaseConnection(at: index, streams: 1)
@@ -375,7 +374,7 @@ extension PoolStateMachine {
                 preconditionFailure("Overflow connections should never be parked.")
 
             default:
-                preconditionFailure("A connection index must not be equal or larger `self.maximumConcurrentConnectionHardLimit`")
+                preconditionFailure("A connection index must not be equal to or larger than `self.maximumConcurrentConnectionHardLimit`")
             }
 
             return self.connections[index].parkConnection(
@@ -573,7 +572,7 @@ extension PoolStateMachine {
             }
 
             if index < self.minimumConcurrentConnections {
-                // because of a race a connection might receive a idle timeout after it was moved into
+                // because of a race a connection might receive an idle timeout after it was moved into
                 // the persisted connections. If a connection is now persisted, we now need to ignore
                 // the trigger
                 return nil
@@ -590,7 +589,7 @@ extension PoolStateMachine {
                 return nil
             }
             if index < self.minimumConcurrentConnections {
-                // because of a race a connection might receive a idle timeout after it was moved into
+                // because of a race a connection might receive an idle timeout after it was moved into
                 // the persisted connections. If a connection is now persisted, we now need to ignore
                 // the trigger
                 return nil
@@ -784,7 +783,7 @@ extension PoolStateMachine {
                     return nil
 
                 default:
-                    preconditionFailure("A connection index must not be equal or larger `self.maximumConcurrentConnectionHardLimit`")
+                    preconditionFailure("A connection index must not be equal to or larger than `self.maximumConcurrentConnectionHardLimit`")
                 }
 
             case self.minimumConcurrentConnections..<self.maximumConcurrentConnectionSoftLimit:

Sources/ConnectionPoolModule/PoolStateMachine+ConnectionState.swift

@@ -44,7 +44,7 @@ extension PoolStateMachine {
     }
 
     @usableFromInline
-    /// An connection state machine about the pool's view on the connection.
+    /// A connection state machine for the pool's view on the connection.
     struct ConnectionState: Sendable {
         @usableFromInline
         enum State: Sendable {
@@ -107,14 +107,14 @@ extension PoolStateMachine {
                 }
             }
 
-            /// The pool is creating a connection. Valid transitions are to: `.backingOff`, `.idle`, and `.closed`
+            /// The pool is creating a connection. Valid transitions are to: `.backingOff`, `.idle`, and `.closed`.
             case starting
             /// The pool is waiting to retry establishing a connection. Valid transitions are to: `.closed`.
             /// This means, the connection can be removed from the connections without cancelling external
             /// state. The connection state can then be replaced by a new one.
             case backingOff(Timer)
-            /// The connection is `idle` and ready to execute a new query. Valid transitions to: `.pingpong`, `.leased`,
-            /// `.closing` and `.closed`
+            /// The connection is `idle` and ready to execute a new query. Valid transitions to: `.leased`,
+            /// `.closing`, and `.closed`.
             case idle(Connection, maxStreams: UInt16, keepAlive: KeepAlive, idleTimer: Timer?)
             /// The connection is leased and executing a query. Valid transitions to: `.idle` and `.closed`
             case leased(Connection, usedStreams: UInt16, maxStreams: UInt16, keepAlive: KeepAlive)

Sources/ConnectionPoolModule/PoolStateMachine.swift

@@ -11,13 +11,13 @@ import Musl
 struct PoolConfiguration: Sendable {
     /// The minimum number of connections to preserve in the pool.
     ///
-    /// If the pool is mostly idle and the remote servers closes idle connections,
+    /// If the pool is mostly idle and the remote server closes idle connections,
     /// the `ConnectionPool` will initiate new outbound connections proactively
     /// to avoid the number of available connections dropping below this number.
     @usableFromInline
     var minimumConnectionCount: Int = 0
 
-    /// The maximum number of connections to for this pool, to be preserved.
+    /// The maximum number of connections for this pool to be preserved.
     @usableFromInline
     var maximumConnectionSoftLimit: Int = 10
 
@@ -815,7 +815,7 @@ struct PoolStateMachine<
 extension PoolStateMachine {
     /// Calculates the delay for the next connection attempt after the given number of failed `attempts`.
     ///
-    /// Our backoff formula is: 100ms * 1.25^(attempts - 1) with 3% jitter that is capped of at 1 minute.
+    /// Our backoff formula is: 100ms * 1.25^(attempts - 1) with 3% jitter that is capped off at 1 minute.
     /// This means for:
     ///   -  1 failed attempt :  100ms
     ///   -  5 failed attempts: ~300ms
@@ -826,10 +826,10 @@ extension PoolStateMachine {
     ///   - 29 failed attempts: ~60s (max out)
     ///
     /// - Parameter attempts: number of failed attempts in a row
-    /// - Returns: time to wait until trying to establishing a new connection
+    /// - Returns: time to wait until trying to establish a new connection
     @usableFromInline
     static func calculateBackoff(failedAttempt attempts: Int) -> Duration {
-        // Our backoff formula is: 100ms * 1.25^(attempts - 1) that is capped of at 1minute
+        // Our backoff formula is: 100ms * 1.25^(attempts - 1) that is capped off at 1 minute
         // This means for:
         //   -  1 failed attempt :  100ms
         //   -  5 failed attempts: ~300ms

Sources/PostgresNIO/Connection/PostgresConnection+Configuration.swift

@@ -3,7 +3,7 @@ import NIOPosix // inet_pton() et al.
 import NIOSSL
 
 extension PostgresConnection {
-    /// A configuration object for a connection
+    /// A configuration object for a connection.
     public struct Configuration: Sendable {
 
         // MARK: - TLS
@@ -66,7 +66,7 @@ extension PostgresConnection {
         public struct Options: Sendable {
             /// A timeout for connection attempts. Defaults to ten seconds.
             ///
-            /// Ignored when using a preexisting communcation channel. (See
+            /// Ignored when using a preexisting communication channel. (See
             /// ``PostgresConnection/Configuration/init(establishedChannel:username:password:database:)``.)
             public var connectTimeout: TimeAmount
 
@@ -169,6 +169,9 @@ extension PostgresConnection {
         /// - Parameters:
         ///   - host: The hostname to connect to.
         ///   - port: The TCP port to connect to (defaults to 5432).
+        ///   - username: The username to authenticate with.
+        ///   - password: The password to authenticate with.
+        ///   - database: The database to open. If `nil`, the client connects to the server's default database.
         ///   - tls: The TLS mode to use.
         public init(host: String, port: Int = 5432, username: String, password: String?, database: String?, tls: TLS) {
             self.init(endpointInfo: .connectTCP(host: host, port: port), tls: tls, username: username, password: password, database: database)
@@ -177,8 +180,10 @@ extension PostgresConnection {
         /// Create a configuration for connecting to a server through a UNIX domain socket.
         ///
         /// - Parameters:
-        ///   - path: The filesystem path of the socket to connect to.
-        ///   - tls: The TLS mode to use. Defaults to ``TLS-swift.struct/disable``.
+        ///   - unixSocketPath: The filesystem path of the socket to connect to.
+        ///   - username: The username to authenticate with.
+        ///   - password: The password to authenticate with.
+        ///   - database: The database to open. If `nil`, the client connects to the server's default database.
         public init(unixSocketPath: String, username: String, password: String?, database: String?) {
             self.init(endpointInfo: .bindUnixDomainSocket(path: unixSocketPath), tls: .disable, username: username, password: password, database: database)
         }
@@ -193,6 +198,9 @@ extension PostgresConnection {
         ///   - channel: The `NIOCore/Channel` to use. The channel must already be active and connected to an
         ///     endpoint (i.e. `NIOCore/Channel/isActive` must be `true`).
         ///   - tls: The TLS mode to use.
+        ///   - username: The username to authenticate with.
+        ///   - password: The password to authenticate with.
+        ///   - database: The database to open. If `nil`, the client connects to the server's default database.
         public init(establishedChannel channel: any Channel, tls: PostgresConnection.Configuration.TLS, username: String, password: String?, database: String?) {
             self.init(endpointInfo: .configureChannel(channel), tls: tls, username: username, password: password, database: database)
         }
@@ -206,6 +214,9 @@ extension PostgresConnection {
         /// - Parameters:
         ///   - channel: The `NIOCore/Channel` to use. The channel must already be active and connected to an
         ///     endpoint (i.e. `NIOCore/Channel/isActive` must be `true`).
+        ///   - username: The username to authenticate with.
+        ///   - password: The password to authenticate with.
+        ///   - database: The database to open. If `nil`, the client connects to the server's default database.
         public init(establishedChannel channel: any Channel, username: String, password: String?, database: String?) {
             self.init(establishedChannel: channel, tls: .disable, username: username, password: password, database: database)
         }

Sources/PostgresNIO/Connection/PostgresConnection+CopyFrom.swift

@@ -31,8 +31,8 @@ public struct PostgresCopyFromWriter: Sendable {
 
     /// Send data for a `COPY ... FROM STDIN` operation to the backend.
     ///
-    /// - Throws: If an error occurs during the write of if the backend sent an `ErrorResponse` during the copy
-    ///   operation, eg. to indicate that a **previous** `write` call had an invalid format.
+    /// - Throws: If an error occurs during the write or if the backend sent an `ErrorResponse` during the copy
+    ///   operation, e.g. to indicate that a **previous** `write` call had an invalid format.
     public func write(_ byteBuffer: ByteBuffer) async throws {
         // Check for cancellation. This is cheap and makes sure that we regularly check for cancellation in the
         // `writeData` closure. It is likely that the user would forget to do so.
@@ -100,7 +100,7 @@ public struct PostgresCopyFromWriter: Sendable {
 
 /// Specifies the format in which data is transferred to the backend in a COPY operation.
 ///
-/// See the Postgres documentation at https://www.postgresql.org/docs/current/sql-copy.html for the option's meanings
+/// See the Postgres documentation at https://www.postgresql.org/docs/current/sql-copy.html for the options' meanings
 /// and their default values.
 public struct PostgresCopyFromFormat: Sendable {
     /// Options that can be used to modify the `text` format of a COPY operation.
@@ -168,6 +168,9 @@ extension PostgresConnection {
     ///   - table: The name of the table into which to copy the data.
     ///   - columns: The name of the columns to copy. If an empty array is passed, all columns are assumed to be copied.
     ///   - format: Options that specify the format of the data that is produced by `writeData`.
+    ///   - logger: The `Logger` to log into for the operation.
+    ///   - file: The file the operation was started in. Used for better error reporting.
+    ///   - line: The line the operation was started in. Used for better error reporting.
     ///   - writeData: Closure that produces the data for the table, to be streamed to the backend. Call `write` on the
     ///     writer provided by the closure to send data to the backend and return from the closure once all data is sent.
     ///     Throw an error from the closure to fail the data transfer. The error thrown by the closure will be rethrown