docs/fixups

README.md

@@ -4,14 +4,14 @@ This repository contains high-performance HTTP/2 client and server transport
 implementations for [gRPC Swift][gh-grpc-swift-2] built on top of
 [SwiftNIO][gh-swift-nio].
 
-- 📚 **Documentation** is available on the [Swift Package Index][spi-grpc-swift-nio-transport]
+- 📚 **Documentation** is available on the [Swift Package Index][spi-grpc-swift-nio-transport].
 - 🎓 **Tutorials** are available in the documentation for `grpc/grpc-swift-2` on
   the [Swift Package Index][spi-grpc-swift-2].
 - 💻 **Examples** are available in the `Examples` directory of the
-  [`grpc/grpc-swift-2`][gh-grpc-swift-2] repository
-- 🚀 **Contributions** are welcome, please see [CONTRIBUTING.md](CONTRIBUTING.md)
-- 🪪 **License** is Apache 2.0, repeated in [LICENSE](License)
-- 🔒 **Security** issues should be reported via the process in [SECURITY.md](SECURITY.md)
+  [`grpc/grpc-swift-2`](https://github.com/grpc/grpc-swift-2) repository.
+- 🚀 **Contributions** are welcome, please see [CONTRIBUTING.md](CONTRIBUTING.md).
+- 🪪 **License** is Apache 2.0, repeated in [LICENSE](License).
+- 🔒 **Security** issues should be reported via the process in [SECURITY.md](SECURITY.md).
 
 [gh-swift-nio]: https://github.com/apple/swift-nio
 [gh-grpc-swift-2]: https://github.com/grpc/grpc-swift-2

SECURITY.md

@@ -1,4 +1,4 @@
 # Security
 
-Please refer to [SECURITY.md] in the
+Please refer to [SECURITY.md](https://github.com/grpc/grpc-swift-2/blob/main/SECURITY.md) in the
 [`grpc/grpc-swift-2`](https://github.com/grpc/grpc-swift-2) repository.

Sources/GRPCNIOTransportCore/Client/HTTP2ClientTransport.swift

@@ -29,6 +29,7 @@ extension HTTP2ClientTransport {
 
 @available(gRPCSwiftNIOTransport 2.0, *)
 extension HTTP2ClientTransport.Config {
+  /// Compression configuration for the client transport.
   public struct Compression: Sendable, Hashable {
     /// The default algorithm used for compressing outbound messages.
     ///
@@ -40,7 +41,7 @@ extension HTTP2ClientTransport.Config {
     /// - Note: `CompressionAlgorithm.none` is always supported, even if it isn't set here.
     public var enabledAlgorithms: CompressionAlgorithmSet
 
-    /// Creates a new compression configuration.
+    /// Creates a compression configuration.
     ///
     /// - SeeAlso: ``defaults``.
     public init(algorithm: CompressionAlgorithm, enabledAlgorithms: CompressionAlgorithmSet) {
@@ -54,6 +55,7 @@ extension HTTP2ClientTransport.Config {
     }
   }
 
+  /// Keepalive configuration for the client transport.
   public struct Keepalive: Sendable, Hashable {
     /// The amount of time to wait after reading data before sending a keepalive ping.
     ///
@@ -67,14 +69,15 @@ extension HTTP2ClientTransport.Config {
     /// Whether the client sends keepalive pings when there are no calls in progress.
     public var allowWithoutCalls: Bool
 
-    /// Creates a new keepalive configuration.
+    /// Creates a keepalive configuration.
     public init(time: Duration, timeout: Duration, allowWithoutCalls: Bool) {
       self.time = time
       self.timeout = timeout
       self.allowWithoutCalls = allowWithoutCalls
     }
   }
 
+  /// Connection management configuration for the client transport.
   public struct Connection: Sendable, Hashable {
     /// The maximum amount of time a connection may be idle before it's closed.
     ///
@@ -127,6 +130,7 @@ extension HTTP2ClientTransport.Config {
     }
   }
 
+  /// Configuration for the backoff used between connection attempts.
   public struct Backoff: Sendable, Hashable {
     /// The initial duration to wait before reattempting to establish a connection.
     public var initial: Duration
@@ -144,21 +148,24 @@ extension HTTP2ClientTransport.Config {
     /// The resulting backoff will therefore be between 8 seconds and 12 seconds.
     public var jitter: Double
 
-    /// Creates a new backoff configuration.
+    /// Creates a backoff configuration.
     public init(initial: Duration, max: Duration, multiplier: Double, jitter: Double) {
       self.initial = initial
       self.max = max
       self.multiplier = multiplier
       self.jitter = jitter
     }
 
-    /// Default values, initial backoff is one second and maximum back off is two minutes. The
-    /// multiplier is `1.6` and the jitter is set to `0.2`.
+    /// Default values for backoff.
+    ///
+    /// The initial backoff is one second, the maximum backoff is two minutes, the multiplier
+    /// is `1.6`, and the jitter is `0.2`.
     public static var defaults: Self {
       Self(initial: .seconds(1), max: .seconds(120), multiplier: 1.6, jitter: 0.2)
     }
   }
 
+  /// HTTP/2-level configuration for the client transport.
   public struct HTTP2: Sendable, Hashable {
     /// The max frame size, in bytes.
     ///
@@ -175,11 +182,11 @@ extension HTTP2ClientTransport.Config {
     ///
     /// Any value set here will unconditionally override any value derived from the target address.
     ///
-    /// The server authority is used in the ":authority" pseudoheader and in the TLS SNI
+    /// The server authority is used in the `:authority` pseudo-header and in the TLS SNI
     /// extension, if applicable.
     public var authority: String?
 
-    /// Creates a new HTTP/2 configuration.
+    /// Creates an HTTP/2 configuration.
     public init(maxFrameSize: Int, targetWindowSize: Int, authority: String?) {
       self.maxFrameSize = maxFrameSize
       self.targetWindowSize = targetWindowSize
@@ -206,6 +213,7 @@ extension HTTP2ClientTransport.Config {
     /// A callback invoked with each new HTTP/2 stream.
     public var onCreateHTTP2Stream: (@Sendable (_ channel: any Channel) -> EventLoopFuture<Void>)?
 
+    /// Creates a set of channel debugging callbacks.
     public init(
       onCreateTCPConnection: (@Sendable (_ channel: any Channel) -> EventLoopFuture<Void>)?,
       onCreateHTTP2Stream: (@Sendable (_ channel: any Channel) -> EventLoopFuture<Void>)?
@@ -229,7 +237,7 @@ extension HTTP2ClientTransport.Config.Connection {
   /// until one of the following conditions is met:
   /// 1. ``maxFlushDelay`` has elapsed since a flush was first requested,
   /// 2. At least ``maxBytes`` bytes have been written since the previous flush, or
-  /// 3. The channel becomes unwritable (i.e. the outbound buffer has hit the high-water mark).
+  /// 3. The channel becomes unwritable (that is, the outbound buffer has hit the high-water mark).
   ///
   /// This means that under high load, writes naturally accumulate and are flushed together in
   /// fewer, larger batches. This reduces per-write overhead and typically improves both throughput
@@ -250,15 +258,17 @@ extension HTTP2ClientTransport.Config.Connection {
     /// The number of bytes to buffer before a flush is emitted, regardless of the delay.
     public var maxBytes: Int
 
-    /// Creates a new flush coalescing configuration.
+    /// Creates a flush coalescing configuration.
     ///
     /// - SeeAlso: ``defaults``.
     public init(maxFlushDelay: Duration, maxBytes: Int) {
       self.maxFlushDelay = maxFlushDelay
       self.maxBytes = maxBytes
     }
 
-    /// Default values. The max flush delay is 100μs and the max bytes is 64KiB.
+    /// The default flush delay and byte count for the client transport.
+    ///
+    /// The max flush delay is 100μs and the max bytes is 64KiB.
     public static var defaults: Self {
       Self(maxFlushDelay: .microseconds(100), maxBytes: 64 * 1024)
     }

Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+DNS.swift

@@ -31,7 +31,8 @@ extension ResolvableTargets {
     /// If no port is specified then 443 is used.
     public var port: Int?
 
-    /// Create a new DNS target.
+    /// Creates a DNS target.
+    ///
     /// - Parameters:
     ///   - host: The host to resolve via DNS.
     ///   - port: The port to use with resolved addresses.
@@ -44,7 +45,8 @@ extension ResolvableTargets {
 
 @available(gRPCSwiftNIOTransport 2.0, *)
 extension ResolvableTarget where Self == ResolvableTargets.DNS {
-  /// Creates a new resolvable DNS target.
+  /// Creates a resolvable DNS target.
+  ///
   /// - Parameters:
   ///   - host: The host address to resolve.
   ///   - port: The port to use for each resolved address. 443 will be used if unspecified.
@@ -56,13 +58,19 @@ extension ResolvableTarget where Self == ResolvableTargets.DNS {
 
 @available(gRPCSwiftNIOTransport 2.0, *)
 extension NameResolvers {
-  /// A ``NameResolverFactory`` for ``ResolvableTargets/DNS`` targets.
+  /// A name resolver factory for DNS targets.
+  ///
+  /// Creates resolvers for ``ResolvableTargets/DNS`` targets.
   public struct DNS: NameResolverFactory, Sendable {
+    /// The type of target that this factory creates resolvers for.
+    ///
+    /// For this factory, the target type is ``ResolvableTargets/DNS``.
     public typealias Target = ResolvableTargets.DNS
 
-    /// Create a new DNS name resolver factory.
+    /// Creates a DNS name resolver factory.
     public init() {}
 
+    /// Creates a resolver for the given DNS target.
     public func resolver(for target: Target) -> NameResolver {
       let resolver = Self.Resolver(target: target)
       // Only append the port if explicitly set. If it's nil the default port of 443 is used

Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv4.swift

@@ -29,7 +29,8 @@ extension ResolvableTargets {
     /// This array must not be empty.
     public var addresses: [SocketAddress.IPv4]
 
-    /// Create a new IPv4 target.
+    /// Creates an IPv4 target.
+    ///
     /// - Parameter addresses: The IPv4 addresses. Must not be empty.
     public init(addresses: [SocketAddress.IPv4]) {
       debugOnly {
@@ -57,7 +58,8 @@ extension ResolvableTargets {
 
 @available(gRPCSwiftNIOTransport 2.0, *)
 extension ResolvableTarget where Self == ResolvableTargets.IPv4 {
-  /// Creates a new resolvable IPv4 target for a single address.
+  /// Creates a resolvable IPv4 target for a single address.
+  ///
   /// - Parameters:
   ///   - host: The resolved host address.
   ///   - port: The port on the host.
@@ -68,7 +70,8 @@ extension ResolvableTarget where Self == ResolvableTargets.IPv4 {
     return Self(addresses: [address])
   }
 
-  /// Creates a new resolvable IPv4 target for a single address.
+  /// Creates a resolvable IPv4 target for a single address.
+  ///
   /// - Parameters:
   ///   - address: The resolved host address.
   ///   - port: The port on the host.
@@ -79,7 +82,7 @@ extension ResolvableTarget where Self == ResolvableTargets.IPv4 {
     return Self(addresses: [address])
   }
 
-  /// Creates a new resolvable IPv4 target from the provided host-port pairs.
+  /// Creates a resolvable IPv4 target from the provided host-port pairs.
   ///
   /// - Parameter pairs: An array of host-port pairs.
   /// - Returns: A ``ResolvableTarget``.
@@ -91,16 +94,21 @@ extension ResolvableTarget where Self == ResolvableTargets.IPv4 {
 
 @available(gRPCSwiftNIOTransport 2.0, *)
 extension NameResolvers {
-  /// A ``NameResolverFactory`` for ``ResolvableTargets/IPv4`` targets.
+  /// A name resolver factory for IPv4 targets.
   ///
-  /// The name resolver for a given target always produces the same values, with one endpoint per
+  /// Creates resolvers for ``ResolvableTargets/IPv4`` targets. The name resolver for a given
+  /// target always produces the same values, with one endpoint per
   /// address in the target. This resolver doesn't support fetching service configuration.
   public struct IPv4: NameResolverFactory, Sendable {
+    /// The type of target that this factory creates resolvers for.
+    ///
+    /// For this factory, the target type is ``ResolvableTargets/IPv4``.
     public typealias Target = ResolvableTargets.IPv4
 
-    /// Create a new IPv4 resolver factory.
+    /// Creates an IPv4 resolver factory.
     public init() {}
 
+    /// Creates a resolver for the given IPv4 target.
     public func resolver(for target: Target) -> NameResolver {
       let endpoints = target.addresses.map { Endpoint(addresses: [.ipv4($0)]) }
       let resolutionResult = NameResolutionResult(endpoints: endpoints, serviceConfig: nil)

Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+IPv6.swift

@@ -29,7 +29,8 @@ extension ResolvableTargets {
     /// This array must not be empty.
     public var addresses: [SocketAddress.IPv6]
 
-    /// Create a new IPv6 target.
+    /// Creates an IPv6 target.
+    ///
     /// - Parameter addresses: The IPv6 addresses. Must not be empty.
     public init(addresses: [SocketAddress.IPv6]) {
       debugOnly {
@@ -56,7 +57,8 @@ extension ResolvableTargets {
 
 @available(gRPCSwiftNIOTransport 2.0, *)
 extension ResolvableTarget where Self == ResolvableTargets.IPv6 {
-  /// Creates a new resolvable IPv6 target for a single address.
+  /// Creates a resolvable IPv6 target for a single address.
+  ///
   /// - Parameters:
   ///   - host: The resolved host address.
   ///   - port: The port on the host.
@@ -67,7 +69,8 @@ extension ResolvableTarget where Self == ResolvableTargets.IPv6 {
     return Self(addresses: [address])
   }
 
-  /// Creates a new resolvable IPv6 target for a single address.
+  /// Creates a resolvable IPv6 target for a single address.
+  ///
   /// - Parameters:
   ///   - address: The resolved host address.
   ///   - port: The port on the host.
@@ -78,7 +81,7 @@ extension ResolvableTarget where Self == ResolvableTargets.IPv6 {
     return Self(addresses: [address])
   }
 
-  /// Creates a new resolvable IPv6 target from the provided host-port pairs.
+  /// Creates a resolvable IPv6 target from the provided host-port pairs.
   ///
   /// - Parameter pairs: An array of host-port pairs.
   /// - Returns: A ``ResolvableTarget``.
@@ -90,16 +93,21 @@ extension ResolvableTarget where Self == ResolvableTargets.IPv6 {
 
 @available(gRPCSwiftNIOTransport 2.0, *)
 extension NameResolvers {
-  /// A ``NameResolverFactory`` for ``ResolvableTargets/IPv6`` targets.
+  /// A name resolver factory for IPv6 targets.
   ///
-  /// The name resolver for a given target always produces the same values, with one endpoint per
+  /// Creates resolvers for ``ResolvableTargets/IPv6`` targets. The name resolver for a given
+  /// target always produces the same values, with one endpoint per
   /// address in the target. This resolver doesn't support fetching service configuration.
   public struct IPv6: NameResolverFactory, Sendable {
+    /// The type of target that this factory creates resolvers for.
+    ///
+    /// For this factory, the target type is ``ResolvableTargets/IPv6``.
     public typealias Target = ResolvableTargets.IPv6
 
-    /// Create a new IPv6 resolver factory.
+    /// Creates an IPv6 resolver factory.
     public init() {}
 
+    /// Creates a resolver for the given IPv6 target.
     public func resolver(for target: Target) -> NameResolver {
       let endpoints = target.addresses.map { Endpoint(addresses: [.ipv6($0)]) }
       let resolutionResult = NameResolutionResult(endpoints: endpoints, serviceConfig: nil)

Sources/GRPCNIOTransportCore/Client/Resolver/NameResolver+UDS.swift

@@ -18,10 +18,10 @@ internal import GRPCCore
 
 @available(gRPCSwiftNIOTransport 2.0, *)
 extension ResolvableTargets {
-  /// A resolvable target for Unix Domain Socket address.
+  /// A resolvable target for a Unix Domain Socket address.
   ///
   /// ``UnixDomainSocket`` addresses can be resolved by the ``NameResolvers/UnixDomainSocket``
-  /// resolver which creates a single ``Endpoint`` for target address.
+  /// resolver which creates a single ``Endpoint`` for the target address.
   public struct UnixDomainSocket: ResolvableTarget, Sendable {
     /// The Unix Domain Socket address.
     public var address: SocketAddress.UnixDomainSocket
@@ -31,7 +31,7 @@ extension ResolvableTargets {
     /// If unset then the path of the address will be used.
     public var authority: String?
 
-    /// Create a new Unix Domain Socket address.
+    /// Creates a Unix Domain Socket target.
     public init(address: SocketAddress.UnixDomainSocket, authority: String?) {
       self.address = address
       self.authority = authority
@@ -41,8 +41,9 @@ extension ResolvableTargets {
 
 @available(gRPCSwiftNIOTransport 2.0, *)
 extension ResolvableTarget where Self == ResolvableTargets.UnixDomainSocket {
-  /// Creates a new resolvable Unix Domain Socket target.
-  /// - Parameters
+  /// Creates a resolvable Unix Domain Socket target.
+  ///
+  /// - Parameters:
   ///   - path: The path of the socket.
   ///   - authority: The service authority.
   public static func unixDomainSocket(
@@ -58,15 +59,21 @@ extension ResolvableTarget where Self == ResolvableTargets.UnixDomainSocket {
 
 @available(gRPCSwiftNIOTransport 2.0, *)
 extension NameResolvers {
-  /// A ``NameResolverFactory`` for ``ResolvableTargets/UnixDomainSocket`` targets.
+  /// A name resolver factory for Unix Domain Socket targets.
   ///
-  /// The name resolver for a given target always produces the same values, with a single endpoint.
+  /// Creates resolvers for ``ResolvableTargets/UnixDomainSocket`` targets. The name resolver
+  /// for a given target always produces the same values, with a single endpoint.
   /// This resolver doesn't support fetching service configuration.
   public struct UnixDomainSocket: NameResolverFactory, Sendable {
+    /// The type of target that this factory creates resolvers for.
+    ///
+    /// For this factory, the target type is ``ResolvableTargets/UnixDomainSocket``.
     public typealias Target = ResolvableTargets.UnixDomainSocket
 
+    /// Creates a Unix Domain Socket resolver factory.
     public init() {}
 
+    /// Creates a resolver for the given Unix Domain Socket target.
     public func resolver(for target: Target) -> NameResolver {
       let endpoint = Endpoint(addresses: [.unixDomainSocket(target.address)])
       let resolutionResult = NameResolutionResult(endpoints: [endpoint], serviceConfig: nil)