adds public api docs (#148)

Author: heckj

Sources/Valkey/Cluster/HashSlot.swift

@@ -52,7 +52,7 @@ public struct HashSlot: Hashable, Sendable {
     /// The minimum valid hash slot value (0).
     public static let min = HashSlot(.hashSlotMin)
 
-    /// The total number of hash slots in a Valkey cluster (16,384).
+    /// The total number of hash slots allowed in a Valkey cluster (16,384).
     public static let count: Int = 16384
 
     private var _raw: UInt16
@@ -69,23 +69,34 @@ extension HashSlot: Comparable {
 }
 
 extension HashSlot: RawRepresentable {
+    /// The type that represents the raw value of a hash slot.
     public typealias RawValue = UInt16
 
+    /// Creates a hash slot based on the raw value you provide for valid hash slot values.
+    /// - Parameter rawValue: The raw value of the hash slot.
     public init?(rawValue: UInt16) {
         guard rawValue <= HashSlot.max.rawValue else { return nil }
         self._raw = rawValue
     }
 
+    /// Creates a hash slot based on the raw value you provide for valid hash slot values, or returns nil if the raw value isn't within the valid range.
+    /// - Parameter rawValue: The raw value of the hash slot.
+    ///
+    /// The raw value must be within ``HashSlot/min`` (`0`) to ``HashSlot/max`` (`16383`) to initialize.
+    /// If you pass in an Int value beyond that range, the initializer returns `nil`.
     public init?(rawValue: Int) {
         guard HashSlot.min.rawValue <= rawValue, rawValue <= HashSlot.max.rawValue else { return nil }
         self._raw = UInt16(rawValue)
     }
 
+    /// Creates a hash slot based on the raw value you provide for valid hash slot values.
+    /// - Parameter rawValue: The raw value of the hash slot.
     public init?(rawValue: Int64) {
         guard HashSlot.min.rawValue <= rawValue, rawValue <= HashSlot.max.rawValue else { return nil }
         self._raw = UInt16(rawValue)
     }
 
+    /// The raw value of a hash slot.
     public var rawValue: UInt16 { self._raw }
 }
 
@@ -130,8 +141,8 @@ extension HashSlot {
     /// The algorithm calculates the CRC16 of either the entire key or a specific part of the key
     /// enclosed in curly braces (`{...}`), then performs modulo 16384 to get the slot number.
     ///
-    /// - Parameter key: The key used in a Valkey command
-    /// - Returns: A HashSlot representing where this key would be stored in the cluster
+    /// - Parameter key: The key used in a Valkey command.
+    /// - Returns: A HashSlot representing where this key would be stored in the cluster.
     @inlinable
     public init(key: some BidirectionalCollection<UInt8>) {
         // Banging is safe because the modulo ensures we are in range
@@ -140,8 +151,8 @@ extension HashSlot {
 
     /// Creates a hash slot for a Valkey key.
     ///
-    /// - Parameter key: The Valkey key for which to calculate the hash slot
-    /// - Returns: A HashSlot representing where this key would be stored in the cluster
+    /// - Parameter key: The Valkey key for which to calculate the hash slot.
+    /// - Returns: A HashSlot instance that represents where this key would be stored in the cluster.
     @inlinable
     public init(key: ValkeyKey) {
         switch key._storage {
@@ -157,12 +168,12 @@ extension HashSlot {
     /// Computes the portion of the key that should be used for hash slot calculation.
     ///
     /// Follows the Valkey hash tag specification:
-    /// - If the key contains a pattern like "{...}", only the content between the braces is used for hashing
-    /// - If the pattern is empty "{}", or doesn't exist, the entire key is used
-    /// - Only the first occurrence of "{...}" is considered
+    /// - If the key contains a pattern like "{...}", only the content between the braces is used for hashing.
+    /// - If the pattern is empty "{}", or doesn't exist, the entire key is used.
+    /// - Only the first occurrence of "{...}" is considered.
     ///
-    /// - Parameter keyUTF8View: The UTF8 view of key for your operation
-    /// - Returns: A substring UTF8 view that will be used in the CRC16 computation
+    /// - Parameter keyUTF8View: The UTF-8 view of key for your operation.
+    /// - Returns: A UTF-8 sequence  to use in the CRC16 computation to compute a hash slot.
     @inlinable
     package static func hashTag<Bytes: BidirectionalCollection<UInt8>>(forKey keyUTF8View: Bytes) -> Bytes.SubSequence {
         var firstOpenCurly: Bytes.Index?
@@ -278,8 +289,8 @@ extension HashSlot {
     ///
     /// This is the specific CRC16 implementation used by Valkey/Redis for hash slot calculation.
     ///
-    /// - Parameter bytes: A sequence of bytes to compute the CRC16 value for
-    /// - Returns: The computed CRC16 value
+    /// - Parameter bytes: A sequence of bytes used to compute the CRC16 value.
+    /// - Returns: The computed CRC16 value.
     @inlinable
     package static func crc16<Bytes: Sequence>(_ bytes: Bytes) -> UInt16 where Bytes.Element == UInt8 {
         var crc: UInt16 = 0

Sources/Valkey/Cluster/ValkeyClusterClient.swift

@@ -20,16 +20,16 @@ import Synchronization
 
 /// A client for interacting with a Valkey cluster.
 ///
-/// ``ValkeyClusterClient`` provides a high-level interface for communicating with a Valkey cluster.
+/// `ValkeyClusterClient` provides a high-level interface for communicating with a Valkey cluster.
 /// It handles cluster topology discovery, command routing, and automatic connection management
 /// across multiple Valkey server nodes.
 ///
 /// The client supports:
-/// - Automatic cluster topology discovery and maintenance
-/// - Command routing to the appropriate node based on key hash slots
-/// - Handling of MOVED responses for proper cluster resharding
-/// - Connection pooling and failover
-/// - Circuit breaking during cluster disruptions
+/// - Automatic cluster topology discovery and maintenance.
+/// - Command routing to the appropriate node based on key hash slots.
+/// - Handling of MOVED responses for proper cluster resharding.
+/// - Connection pooling and failover.
+/// - Circuit breaking during cluster disruptions.
 ///
 /// Example usage:
 /// ```swift

Sources/Valkey/Commands/Custom/ClusterCustomCommands.swift

@@ -41,12 +41,17 @@ package struct ValkeyClusterParseError: Error, Equatable {
     }
 }
 
+/// A description of a Valkey cluster.
+///
+/// A description is return when you call ``ValkeyConnectionProtocol/clusterShards()``.
 public struct ValkeyClusterDescription: Hashable, Sendable, RESPTokenDecodable {
-    /// Details for a node within a cluster shard
+    /// Details for a node within a cluster shard.
     public struct Node: Hashable, Sendable {
-        /// Replication role of a given node within a shard (primary or replica)
+        /// Replication role of a given node within a shard (primary or replica).
         public struct Role: Sendable, Hashable, RawRepresentable {
+            /// The node is primary.
             public static let primary = Role(base: .primary)
+            /// The node is a replica.
             public static let replica = Role(base: .replica)
 
             public init?(rawValue: String) {
@@ -75,8 +80,11 @@ public struct ValkeyClusterDescription: Hashable, Sendable, RESPTokenDecodable {
 
         /// Node's health status
         public struct Health: Sendable, Hashable, RawRepresentable {
+            /// The node is online.
             public static let online = Health(base: .online)
+            /// The node is in a failed state.
             public static let failed = Health(base: .failed)
+            /// The node is loading.
             public static let loading = Health(base: .loading)
 
             public init?(rawValue: String) {
@@ -103,16 +111,36 @@ public struct ValkeyClusterDescription: Hashable, Sendable, RESPTokenDecodable {
             }
         }
 
+        /// The ID of the node
         public var id: String
+        /// The port
         public var port: Int?
+        /// The TLS port
         public var tlsPort: Int?
+        /// The IP address
         public var ip: String
+        /// The hostname
         public var hostname: String?
+        /// The endpoint
         public var endpoint: String
+        /// The role of the node
         public var role: Role
+        /// The replication offset for the node
         public var replicationOffset: Int
+        /// The health of the node
         public var health: Health
 
+        /// Creates a new node
+        /// - Parameters:
+        ///   - id: The node ID
+        ///   - port: The port
+        ///   - tlsPort: The TLS port
+        ///   - ip: The IP address
+        ///   - hostname: The hostname
+        ///   - endpoint: The endpoint
+        ///   - role: The node role
+        ///   - replicationOffset: The replication offset
+        ///   - health: The node health
         public init(
             id: String,
             port: Int?,
@@ -136,18 +164,28 @@ public struct ValkeyClusterDescription: Hashable, Sendable, RESPTokenDecodable {
         }
     }
 
+    /// A portion of a valkey cluster
     public struct Shard: Hashable, Sendable {
+        /// The slots represented in the shard.
         public var slots: HashSlots
+        /// The nodes that make up the shard.
         public var nodes: [Node]
 
+        /// Create a new shard.
+        /// - Parameters:
+        ///   - slots: The slots in the shard.
+        ///   - nodes: The nodes in the shard.
         public init(slots: HashSlots, nodes: [Node]) {
             self.slots = slots
             self.nodes = nodes
         }
     }
 
+    /// The individual portions of a valkey cluster, known as shards.
     public var shards: [Shard]
 
+    /// Creates a cluster description from the response token you provide.
+    /// - Parameter respToken: The response token.
     public init(fromRESP respToken: RESPToken) throws {
         do {
             self = try Self.makeClusterDescription(respToken: respToken)
@@ -156,6 +194,8 @@ public struct ValkeyClusterDescription: Hashable, Sendable, RESPTokenDecodable {
         }
     }
 
+    /// Creates a cluster description from a list of shards you provide.
+    /// - Parameter shards: The shards that make up the cluster.
     public init(_ shards: [ValkeyClusterDescription.Shard]) {
         self.shards = shards
     }

Sources/Valkey/Connection/ValkeyConnectionConfiguration.swift

@@ -87,10 +87,12 @@ public struct ValkeyConnectionConfiguration: Sendable {
     }
 
     /// Optional authentication credentials for accessing the Valkey server.
+    ///
     /// Set this property when connecting to a server that requires authentication.
     public var authentication: Authentication?
 
     /// TLS configuration for the connection.
+    ///
     /// Use `.disable` for unencrypted connections or `.enable(...)` for secure connections.
     public var tls: TLS
 

Sources/Valkey/Documentation.docc/index.md

@@ -50,9 +50,10 @@ try await valkeyClient.withConnection { connection in
 
 - ``ValkeyClient``
 - ``ValkeyClientConfiguration``
+- ``ValkeyConnectionProtocol``
 - ``ValkeyServerAddress``
 - ``ValkeyConnection``
-- ``ValkeyConnectionProtocol``
+- ``ValkeyConnectionConfiguration``
 
 ### Commands
 

Sources/Valkey/RESP/RESPError.swift

@@ -22,6 +22,7 @@ import NIOCore
 ///   2. You are contacting an untrusted backend
 ///
 public struct RESPParsingError: Error {
+    /// The error code associated with an error parsing a response.
     public struct Code: Hashable, Sendable, CustomStringConvertible {
         private enum Base {
             case invalidLeadingByte
@@ -41,14 +42,23 @@ public struct RESPParsingError: Error {
             self.base = base
         }
 
+        /// The leading byte is invalid.
         public static let invalidLeadingByte = Self.init(.invalidLeadingByte)
+        /// The data is invalid.
         public static let invalidData = Self.init(.invalidData)
+        /// The nested aggregate types are too deeply nested.
         public static let tooDeeplyNestedAggregatedTypes = Self.init(.tooDeeplyNestedAggregatedTypes)
+        /// A colon is missing within a verbatim string
         public static let missingColonInVerbatimString = Self.init(.missingColonInVerbatimString)
+        /// Can't parse the data as an integer.
         public static let canNotParseInteger = Self.init(.canNotParseInteger)
+        /// Can't parse the data as a Double.
         public static let canNotParseDouble = Self.init(.canNotParseDouble)
+        /// Can't parse the data as a big number.
         public static let canNotParseBigNumber = Self.init(.canNotParseBigNumber)
+        /// The type is unexpected.
         public static let unexpectedType = Self.init(.unexpectedType)
+        /// There is an invalid element count.
         public static let invalidElementCount = Self.init(.invalidElementCount)
 
         public var description: String {
@@ -75,7 +85,10 @@ public struct RESPParsingError: Error {
         }
     }
 
+    /// The error code
     public var code: Code
+
+    /// The byte buffer that failed to parse.
     public var buffer: ByteBuffer
 
     @usableFromInline

Sources/Valkey/RESP/RESPRenderable.swift

@@ -14,7 +14,7 @@
 
 import NIOCore
 
-/// Type that can be rendered into a RESP buffer
+/// A type that can be rendered into a RESP buffer.
 public protocol RESPRenderable {
     var respEntries: Int { get }
 

Sources/Valkey/RESP/RESPStringRenderable.swift

@@ -20,7 +20,7 @@ import FoundationEssentials
 import Foundation
 #endif
 
-/// Type that can be rendered as a single bulk string
+/// A type that can be rendered as a single bulk string.
 public protocol RESPStringRenderable: Sendable, Hashable {
     func encode(into commandEncoder: inout ValkeyCommandEncoder)
 }

Sources/Valkey/RESP/RESPToken.swift

@@ -14,10 +14,15 @@
 
 import NIOCore
 
+/// The response from a Valkey server.
+///
+/// A response token is a type that provides a view into the underlying byte buffer returned from the Valkey server.
 public struct RESPToken: Hashable, Sendable {
+    /// A list of response tokens.
     public struct Array: Sequence, Sendable, Hashable {
         public typealias Element = RESPToken
 
+        /// The count of items in the list.
         public let count: Int
         let buffer: ByteBuffer
 
@@ -45,6 +50,7 @@ public struct RESPToken: Hashable, Sendable {
         }
     }
 
+    /// A dictionary of response tokens mapped by a response token.
     public struct Map: Sequence, Sendable, Hashable {
         public typealias Element = (key: RESPToken, value: RESPToken)
 
@@ -80,21 +86,37 @@ public struct RESPToken: Hashable, Sendable {
         }
     }
 
+    /// A response token value.
     public enum Value: Hashable, Sendable {
+        /// A simple string
         case simpleString(ByteBuffer)
+        /// A simple error
         case simpleError(ByteBuffer)
+        /// A bulk string
         case bulkString(ByteBuffer)
+        /// A bulk error
         case bulkError(ByteBuffer)
+        /// A verbatim string
         case verbatimString(ByteBuffer)
+        /// An integer number
         case number(Int64)
+        /// A floating point number
         case double(Double)
+        /// A Boolean value
         case boolean(Bool)
+        /// Null
         case null
+        /// A big number
         case bigNumber(ByteBuffer)
+        /// An array
         case array(Array)
+        /// An attribute
         case attribute(Map)
+        /// A map
         case map(Map)
+        /// A set
         case set(Array)
+        /// A pushed value
         case push(Array)
     }