Docc pipelining article (#126)

* Rename Returns to Response in function headers to avoid docc warnings

Signed-off-by: Adam Fowler <[email protected]>

* Add pipelining article, update index and README

Signed-off-by: Adam Fowler <[email protected]>

* PR comment

Signed-off-by: Adam Fowler <[email protected]>

* Update Sources/Valkey/Documentation.docc/index.md

Co-authored-by: Fabian Fett <[email protected]>
Signed-off-by: Adam Fowler <[email protected]>

* Add async let section

Signed-off-by: Adam Fowler <[email protected]>

---------

Signed-off-by: Adam Fowler <[email protected]>
Co-authored-by: Fabian Fett <[email protected]>

Author: adam-fowler

README.md

@@ -1,6 +1,6 @@
 # valkey-swift
 
-Valkey client 
+A Swift client library for Valkey.
 
 ## Usage
 
@@ -19,30 +19,32 @@ try await withThrowingTaskgroup(of: Void.self) { group in
 
 Or you can use ValkeyClient with [swift-service-lifecycle](https://github.com/swift-server/swift-service-lifecycle).
 
-Once you have a valkey client setup and running you can create connections to your Valkey database using `ValkeyClient.withConnection()`.
+Once you have a valkey client setup and running you can call valkey commands directly from the `ValkeyClient`.
 
 ```swift
-try await valkeyClient.withConnection { connection in
-    try await doValkeyStuff()
-}
+try await valkeyClient.set(key: "foo", value: "bar")
 ```
-
-All the Valkey commands are in the Commands folder of the Valkey target. These are generated from the model files Valkey supplies in [valkey](https://github.com/valkey-io/valkey/src/commands). In many cases where it was possible to ascertain the return type of a command these functions will return that expected type. In situations where this is not possible (or we are returning a String) a `RESPToken` is returned and you'll need to convert it manually.
+Or you can create a connection and run multiple commands from that connection using `ValkeyClient.withConnection()`.
 
 ```swift
-try await connection.set(key: "MyKey", value: "TestString")
-let value = try await connection.get(key: "MyKey").decode(as: String.self)
+try await valkeyClient.withConnection { connection in
+    try await connection.set(key: "foo1", value: "bar")
+    try await connection.set(key: "foo2", value: "baz")
+}
 ```
 
+All the Valkey commands are in the Commands folder of the Valkey target. These are generated from the model files Valkey supplies in [valkey](https://github.com/valkey-io/valkey/src/commands). In many cases where it was possible to ascertain the return type of a command these functions will return that expected type. In situations where this is not possible we have either added a custom return type or a `RESPToken` is returned and you'll need to convert it manually.
+
 ### Pipelining commands
 
 In some cases it is desirable to send multiple commands at one time, without waiting for the response after each command. This is called pipelining. You can do this using the function `pipeline(_:)`. This takes a parameter pack of commands and returns a parameter pack with the responses once all the commands have executed.
 
 ```swift
-let (setResponse, getResponse) = try await connection.pipeline(
+let (setResponse, getResponse) = await connection.pipeline(
     SET(key: "MyKey", value: "TestString"),
     GET(key: "MyKey")
 )
+let value = try getResponse.get()
 ```
 
 ## Redis compatibilty

Sources/Valkey/Commands/BitmapCommands.swift

@@ -471,24 +471,24 @@ public struct SETBIT: ValkeyCommand {
 extension ValkeyConnectionProtocol {
     /// Counts the number of set bits (population counting) in a string.
     ///
-    /// - Documentation: [BITCOUNT](https:/valkey.io/commands/bitcount)
+    /// - Documentation: [BITCOUNT](https://valkey.io/commands/bitcount)
     /// - Available: 2.6.0
     /// - History:
     ///     * 7.0.0: Added the `BYTE|BIT` option.
     ///     * 8.0.0: `end` made optional; when called without argument the command reports the last BYTE.
     /// - Complexity: O(N)
-    /// - Returns: [Integer]: The number of bits set to 1.
+    /// - Response: [Integer]: The number of bits set to 1.
     @inlinable
     public func bitcount(key: ValkeyKey, range: BITCOUNT.Range? = nil) async throws -> Int {
         try await send(command: BITCOUNT(key: key, range: range))
     }
 
     /// Performs arbitrary bitfield integer operations on strings.
     ///
-    /// - Documentation: [BITFIELD](https:/valkey.io/commands/bitfield)
+    /// - Documentation: [BITFIELD](https://valkey.io/commands/bitfield)
     /// - Available: 3.2.0
     /// - Complexity: O(1) for each subcommand specified
-    /// - Returns: One of the following
+    /// - Response: One of the following
     ///     * [Array]: The result of the subcommand at the same position
     ///     * [Array]: In case OVERFLOW FAIL was given and overflows or underflows detected
     @inlinable
@@ -498,34 +498,34 @@ extension ValkeyConnectionProtocol {
 
     /// Performs arbitrary read-only bitfield integer operations on strings.
     ///
-    /// - Documentation: [BITFIELD_RO](https:/valkey.io/commands/bitfield_ro)
+    /// - Documentation: [BITFIELD_RO](https://valkey.io/commands/bitfield_ro)
     /// - Available: 6.0.0
     /// - Complexity: O(1) for each subcommand specified
-    /// - Returns: [Array]: The result of the subcommand at the same position
+    /// - Response: [Array]: The result of the subcommand at the same position
     @inlinable
     public func bitfieldRo(key: ValkeyKey, getBlock: [BITFIELDRO.GetBlock] = []) async throws -> [Int] {
         try await send(command: BITFIELDRO(key: key, getBlock: getBlock))
     }
 
     /// Performs bitwise operations on multiple strings, and stores the result.
     ///
-    /// - Documentation: [BITOP](https:/valkey.io/commands/bitop)
+    /// - Documentation: [BITOP](https://valkey.io/commands/bitop)
     /// - Available: 2.6.0
     /// - Complexity: O(N)
-    /// - Returns: [Integer]: The size of the string stored in the destination key, that is equal to the size of the longest input string.
+    /// - Response: [Integer]: The size of the string stored in the destination key, that is equal to the size of the longest input string.
     @inlinable
     public func bitop(operation: BITOP.Operation, destkey: ValkeyKey, key: [ValkeyKey]) async throws -> Int {
         try await send(command: BITOP(operation: operation, destkey: destkey, key: key))
     }
 
     /// Finds the first set (1) or clear (0) bit in a string.
     ///
-    /// - Documentation: [BITPOS](https:/valkey.io/commands/bitpos)
+    /// - Documentation: [BITPOS](https://valkey.io/commands/bitpos)
     /// - Available: 2.8.7
     /// - History:
     ///     * 7.0.0: Added the `BYTE|BIT` option.
     /// - Complexity: O(N)
-    /// - Returns: One of the following
+    /// - Response: One of the following
     ///     * [Integer]: The position of the first bit set to 1 or 0 according to the request.
     ///     * -1: In case the `bit` argument is 1 and the string is empty or composed of just zero bytes.
     @inlinable
@@ -535,21 +535,21 @@ extension ValkeyConnectionProtocol {
 
     /// Returns a bit value by offset.
     ///
-    /// - Documentation: [GETBIT](https:/valkey.io/commands/getbit)
+    /// - Documentation: [GETBIT](https://valkey.io/commands/getbit)
     /// - Available: 2.2.0
     /// - Complexity: O(1)
-    /// - Returns: The bit value stored at offset.
+    /// - Response: The bit value stored at offset.
     @inlinable
     public func getbit(key: ValkeyKey, offset: Int) async throws -> Int {
         try await send(command: GETBIT(key: key, offset: offset))
     }
 
     /// Sets or clears the bit at offset of the string value. Creates the key if it doesn't exist.
     ///
-    /// - Documentation: [SETBIT](https:/valkey.io/commands/setbit)
+    /// - Documentation: [SETBIT](https://valkey.io/commands/setbit)
     /// - Available: 2.2.0
     /// - Complexity: O(1)
-    /// - Returns: The original bit value stored at offset.
+    /// - Response: The original bit value stored at offset.
     @inlinable
     public func setbit(key: ValkeyKey, offset: Int, value: Int) async throws -> Int {
         try await send(command: SETBIT(key: key, offset: offset, value: value))