documentation updates (#160)

* documentation updates

- breaks out the getting started pieces into its own article, and adds detail on how to add the package
  to your project
- a pass through the top-level types to make their descriptions more consisent, and full sentences.
- loosely curate the new (public) geographical types into the current structure

Signed-off-by: Joe Heck <[email protected]>

* shifting based on feedback

Signed-off-by: Joe Heck <[email protected]>

* updating the RESPRenderable protocol descriptions

Signed-off-by: Joe Heck <[email protected]>

* grammar fix

Signed-off-by: Joe Heck <[email protected]>

* hiding the geo response types

Signed-off-by: Joe Heck <[email protected]>

* Update Sources/Valkey/RESP/RESPStringRenderable.swift

Co-authored-by: Adam Fowler <[email protected]>
Signed-off-by: Joseph Heck <[email protected]>

* Update Sources/Valkey/RESP/RESPRenderable.swift

Co-authored-by: Adam Fowler <[email protected]>
Signed-off-by: Joseph Heck <[email protected]>

* Update Sources/Valkey/Documentation.docc/getting-started.md

Co-authored-by: Adam Fowler <[email protected]>
Signed-off-by: Joseph Heck <[email protected]>

* Update Sources/Valkey/RESP/RESPError.swift

Co-authored-by: Adam Fowler <[email protected]>
Signed-off-by: Joseph Heck <[email protected]>

---------

Signed-off-by: Joe Heck <[email protected]>
Signed-off-by: Joseph Heck <[email protected]>
Co-authored-by: Adam Fowler <[email protected]>

Author: heckj

Sources/Valkey/Cluster/ValkeyNodeDiscovery.swift

@@ -12,7 +12,7 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// Allows the cluster client to initially find at least one node in the cluster or find the
+/// A type that allows the cluster client to initially find at least one node in the cluster, or find the
 /// nodes again if connection to them has been lost.
 public protocol ValkeyNodeDiscovery: Sendable {
     /// A type that describes a single node in a valkey cluster

Sources/Valkey/Commands/Custom/GeoCustomCommands.swift

@@ -12,6 +12,8 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// A type that represents geographic coordinates.
+@_documentation(visibility: internal)
 public struct GeoCoordinates: RESPTokenDecodable, Sendable {
     public let longitude: Double
     public let latitude: Double
@@ -21,6 +23,8 @@ public struct GeoCoordinates: RESPTokenDecodable, Sendable {
     }
 }
 
+/// A type that represents a coordinate value for a geographic location.
+@_documentation(visibility: internal)
 public typealias GEODISTResponse = Double?
 extension GEODIST {
     public typealias Response = GEODISTResponse

Sources/Valkey/Connection/ValkeyConnection.swift

@@ -23,7 +23,7 @@ import Network
 import NIOTransportServices
 #endif
 
-/// Single connection to a Valkey database
+/// A single connection to a Valkey database.
 @available(valkeySwift 1.0, *)
 public final actor ValkeyConnection: ValkeyClientProtocol, Sendable {
     nonisolated public let unownedExecutor: UnownedSerialExecutor

Sources/Valkey/Connection/ValkeyConnectionProtocol.swift

@@ -12,7 +12,7 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// Protocol for a Valkey connection that can send a command and get a response
+/// A type that provides the ability to send a Valkey command and get a response.
 public protocol ValkeyClientProtocol {
     /// Send RESP command to Valkey connection
     /// - Parameter command: ValkeyCommand structure

Sources/Valkey/Connection/ValkeyServerAddress.swift

@@ -14,7 +14,7 @@
 
 import NIOCore
 
-/// Server address to connect to
+/// A Valkey server address to connect to.
 public struct ValkeyServerAddress: Sendable, Equatable {
     enum _Internal: Equatable {
         case hostname(_ host: String, port: Int)

Sources/Valkey/Documentation.docc/Pipelining.md

@@ -1,8 +1,9 @@
 # Pipelining
 
-Send multiple commands at once without waiting for the response of each command.
+Sending multiple commands at once without waiting for the response of each command.
 
 ## Overview
+=======
 
 Valkey pipelining is a technique for improving performance by issuing multiple commands at once without waiting for the response to each individual command. Pipelining not only reduces the latency cost of waiting for the result of each command it also reduces the cost to the server as it reduces I/O costs. Multiple commands can be read with a single syscall, and multiple results are delivered with a single syscall. 
 
@@ -48,7 +49,6 @@ async let asyncResult = connection.lpush("fooList", elements: ["bar"])
 let result = try await asyncResult
 ```
 
-Be careful when using a single connection across multiple Tasks though. The result of a command only becomes available when the server makes available the result of the command previously queued. Because of this, a command that either blocks the connection or takes a long time can affect the response time of commands that follow it.
-
-You can find out more about pipelining of commands in the [Valkey documentation](https://valkey.io/topics/pipelining/).
-
+Be careful when using a single connection across multiple Tasks though. 
+The result of a command will only become available when the result of any previous command queued has been made available. 
+So a command that either blocks the connection or takes a long time could affect the response time of commands that follow it.

Sources/Valkey/Documentation.docc/getting-started.md

@@ -0,0 +1,104 @@
+# Getting started using Valkey
+
+Add Valkey to your project, manage the connections, and send commands.
+
+## Overview
+
+### Adding Valkey as a dependency
+
+Add Valkey-Swift as a dependency to your project and targets that use it.
+
+You can use the `add-dependency` command:
+
+```bash
+swift package add-dependency \
+    https://github.com/valkey-io/valkey-swift --branch main
+```
+<!-- switch above to `--from: 0.1.0` after tagging an initial release -->
+
+or edit Package.swift directly:
+```swift
+dependencies: [
+    .package(url: "https://github.com/valkey-io/valkey-swift",
+             branch: "main"),
+]
+```
+<!-- switch above to `from: "0.1.0"` after tagging an initial release -->
+
+And for the relevant target or targets.
+The following example shows how to add to Valkey as a dependency to the target `MyApp`:
+
+```bash
+swift package add-target-dependency \
+    Valkey MyApp --package valkey-swift
+```
+
+You can also edit the dependencies for that target directly in Package.swift:
+```swift
+dependencies: [
+    .product(name: "Valkey", package: "valkey-swift"),
+]
+```
+
+> Note: If you are building an executable for macOS, Valkey has a minimum platform dependency you need to accomodate.
+> For example, you may want to add a minimum platform requirement to your project:
+>
+> ```swift
+> platforms: [.macOS(.v15)],
+> ```
+
+Import Valkey in the swift files to use it:
+
+```swift
+import Valkey
+```
+
+### Enabling connections to a Valkey server
+
+``ValkeyClient`` and ``ValkeyClusterClient`` use a connection pool that requires a background root task to run all the maintenance work required to establish connections and maintain the cluster state.
+You can either run them using a Task group, for example:
+
+```swift
+let valkeyClient = ValkeyClient(.hostname("localhost", port: 6379), logger: logger)
+try await withThrowingTaskgroup(of: Void.self) { group in
+    group.addTask {
+        // run connection pool in the background
+        try await valkeyClient.run()
+    }
+    // use valkey client
+}
+```
+
+Or you can use [swift-service-lifecycle](https://github.com/swift-server/swift-service-lifecycle) to manage the connection manager.
+
+```swift
+let valkeyClient = ValkeyClient(.hostname("localhost", port: 6379), logger: logger)
+
+let services: [Service] = [valkeyClient, webserver, other-service]
+let serviceGroup = ServiceGroup(
+    services: services,
+    gracefulShutdownSignals: [.sigint],
+    cancellationSignals: [.sigterm],
+    logger: logger
+)
+try await serviceGroup.run()
+```
+
+### Sending commands
+
+Once you have your connection pool up and running the client is ready to use, you can call commands on the client.
+Valkey-client uses a connection from the connection pool for each call:
+
+```swift
+try await valkeyClient.set(key: "foo", value: "bar")
+let value = try await valkeyClient.get(key: "foo")
+```
+
+You can ask for a single connection and run multiple commands using it:
+
+```swift
+try await valkeyClient.withConnection { connection in
+    try await connection.set(key: "foo", value: "bar")
+    let value = try await connection.get(key: "foo")
+}
+```

Sources/Valkey/Documentation.docc/index.md

@@ -6,44 +6,11 @@ A Swift client library for Valkey.
 
 Valkey-swift is a swift based client for Valkey, the high-performance key/value datastore. It supports all the Valkey commands, pipelining, transactions, subscriptions and Valkey clusters.
 
-### Setup
-
-``ValkeyClient`` and ``ValkeyClusterClient`` use a connection pool that requires a background root task to run all the maintenance work required to establish connections and maintain the cluster state. You can either run them using a Task group
-
-```swift
-let valkeyClient = ValkeyClient(.hostname("localhost", port: 6379), logger: logger)
-try await withThrowingTaskgroup(of: Void.self) { group in
-    group.addTask {
-        // run connection pool in the background
-        try await valkeyClient.run()
-    }
-    // use valkey client
-}
-```
-
-Or you can use [swift-service-lifecycle](https://github.com/swift-server/swift-service-lifecycle) to manage the connection manager.
-
-### Sending commands
-
-Once you have your connection pool up and running the client is ready to use. Commands can be called straight from the client. Each call will ask for a connection from the connection pool
-
-```swift
-try await valkeyClient.set(key: "foo", value: "bar")
-let value = try await valkeyClient.get(key: "foo")
-```
-
-Or you can ask for a single connection and run multiple commands using that one connection
-```swift
-try await valkeyClient.withConnection { connection in
-    try await connection.set(key: "foo", value: "bar")
-    let value = try await connection.get(key: "foo")
-}
-```
-
 ## Topics
 
 ### Articles
 
+- <doc:getting-started>
 - <doc:Pipelining>
 - <doc:Pubsub>
 - <doc:Transactions>

Sources/Valkey/RESP/RESPError.swift

@@ -14,12 +14,12 @@
 
 import NIOCore
 
-/// This error is thrown if a RESP3 package could not be decoded.
+/// An error that Valkey client throws if a RESP3 packet can't be decoded.
 ///
 /// If you see this error, there a two potential reasons this might happen:
 ///
-///   1. The Swift RESP3 implementation is wrong
-///   2. You are contacting an untrusted backend
+///   1. The Swift RESP3 implementation is wrong.
+///   2. You are contacting an untrusted backend.
 ///
 public struct RESPParsingError: Error {
     /// The error code associated with an error parsing a response.

Sources/Valkey/RESP/RESPRenderable.swift

@@ -14,7 +14,7 @@
 
 import NIOCore
 
-/// A type that can be rendered into a RESP buffer.
+/// A type that the command encoder can render as part of a Valkey command.
 public protocol RESPRenderable {
     var respEntries: Int { get }