[ECO-4915] (WIP) Add documentation comments

.github/workflows/check.yaml

@@ -139,6 +139,21 @@ jobs:
       - name: Build example app
         run: swift run BuildTool build-example-app --platform ${{ matrix.platform }}
 
+  check-documentation:
+    runs-on: macos-15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      # This step can be removed once the runners’ default version of Xcode is 16 or above
+      - uses: maxim-lobanov/setup-xcode@v1
+        with:
+          xcode-version: 16
+
+      - name: Build documentation
+        run: swift run BuildTool build-documentation
+
   # We use this job as a marker that all of the required checks have completed.
   # This allows us to configure a single required status check in our branch
   # protection rules instead of having to type loads of different check names
@@ -152,6 +167,7 @@ jobs:
       - check-spm
       - check-xcode
       - check-example-app
+      - check-documentation
 
     steps:
       - name: No-op

AblyChat.xcworkspace/xcshareddata/swiftpm/Package.resolved

@@ -1,5 +1,5 @@
 {
-  "originHash" : "1ad2d7338668d15feccbf564582941161acd47349bfca8f34374e11c69677ae8",
+  "originHash" : "1547951218aae39e26117fe3ca69bba0858841246ead50ef24e9592cdbcfa481",
   "pins" : [
     {
       "identity" : "ably-cocoa",
@@ -55,6 +55,24 @@
         "version" : "1.1.2"
       }
     },
+    {
+      "identity" : "swift-docc-plugin",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-docc-plugin",
+      "state" : {
+        "revision" : "85e4bb4e1cd62cec64a4b8e769dcefdf0c5b9d64",
+        "version" : "1.4.3"
+      }
+    },
+    {
+      "identity" : "swift-docc-symbolkit",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/swiftlang/swift-docc-symbolkit",
+      "state" : {
+        "revision" : "b45d1f2ed151d057b54504d653e0da5552844e34",
+        "version" : "1.0.0"
+      }
+    },
     {
       "identity" : "table",
       "kind" : "remoteSourceControl",

Package.resolved

@@ -1,5 +1,5 @@
 {
-  "originHash" : "b6d25f160b01b473629481d68d4fe734b3981fcd87079531f784c2ade3afdc4d",
+  "originHash" : "19ff3d71167d4ac328655c520d3210baa89ea2c1b0900fb1b5ac5c770b42fa28",
   "pins" : [
     {
       "identity" : "ably-cocoa",
@@ -55,6 +55,24 @@
         "version" : "1.1.2"
       }
     },
+    {
+      "identity" : "swift-docc-plugin",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-docc-plugin",
+      "state" : {
+        "revision" : "85e4bb4e1cd62cec64a4b8e769dcefdf0c5b9d64",
+        "version" : "1.4.3"
+      }
+    },
+    {
+      "identity" : "swift-docc-symbolkit",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/swiftlang/swift-docc-symbolkit",
+      "state" : {
+        "revision" : "b45d1f2ed151d057b54504d653e0da5552844e34",
+        "version" : "1.0.0"
+      }
+    },
     {
       "identity" : "table",
       "kind" : "remoteSourceControl",

Package.swift

@@ -35,6 +35,10 @@ let package = Package(
             url: "https://github.com/JanGorman/Table.git",
             from: "1.1.1"
         ),
+        .package(
+            url: "https://github.com/apple/swift-docc-plugin",
+            from: "1.0.0"
+        ),
     ],
     targets: [
         .target(

Sources/AblyChat/ChatClient.swift

@@ -1,15 +1,48 @@
 import Ably
 
 public protocol ChatClient: AnyObject, Sendable {
+    /**
+     * Returns the rooms object, which provides access to chat rooms.
+     *
+     * - Returns: The rooms object.
+     */
     var rooms: any Rooms { get }
+
+    /**
+     * Returns the underlying connection to Ably, which can be used to monitor the clients
+     * connection to Ably servers.
+     *
+     * - Returns: The connection object.
+     */
     var connection: any Connection { get }
+
+    /**
+     * Returns the clientId of the current client.
+     *
+     * - Returns: The clientId.
+     */
     var clientID: String { get }
+
+    /**
+     * Returns the underlying Ably Realtime client.
+     *
+     * - Returns: The Ably Realtime client.
+     */
     var realtime: RealtimeClient { get }
+
+    /**
+     * Returns the resolved client options for the client, including any defaults that have been set.
+     *
+     * - Returns: The client options.
+     */
     var clientOptions: ClientOptions { get }
 }
 
 public typealias RealtimeClient = any RealtimeClientProtocol
 
+/**
+ * This is the core client for Ably chat. It provides access to chat rooms.
+ */
 public actor DefaultChatClient: ChatClient {
     public let realtime: RealtimeClient
     public nonisolated let clientOptions: ClientOptions
@@ -20,6 +53,13 @@ public actor DefaultChatClient: ChatClient {
     // (CHA-CS4) The chat client must allow its connection status to be observed by clients.
     public nonisolated let connection: any Connection
 
+    /**
+     * Constructor for Chat
+     *
+     * - Parameters:
+     *   - realtime: The Ably Realtime client.
+     *   - clientOptions: The client options.
+     */
     public init(realtime: RealtimeClient, clientOptions: ClientOptions?) {
         self.realtime = realtime
         self.clientOptions = clientOptions ?? .init()
@@ -34,8 +74,22 @@ public actor DefaultChatClient: ChatClient {
     }
 }
 
+/**
+ * Configuration options for the chat client.
+ */
 public struct ClientOptions: Sendable {
+    /**
+     * A custom log handler that will be used to log messages from the client.
+     *
+     * By default, the client will log messages to the console.
+     */
     public var logHandler: LogHandler?
+
+    /**
+     * The minimum log level at which messages will be logged.
+     *
+     * By default, LogLevel.error will be used.
+     */
     public var logLevel: LogLevel?
 
     public init(logHandler: (any LogHandler)? = nil, logLevel: LogLevel? = nil) {

Sources/AblyChat/Connection.swift

@@ -1,24 +1,72 @@
 import Ably
 
+/**
+ * Represents a connection to Ably.
+ */
 public protocol Connection: AnyObject, Sendable {
+    /**
+     * The current status of the connection.
+     */
     var status: ConnectionStatus { get async }
+
     // TODO: (https://github.com/ably-labs/ably-chat-swift/issues/12): consider how to avoid the need for an unwrap
+    /**
+     * The current error, if any, that caused the connection to enter the current status.
+     */
     var error: ARTErrorInfo? { get async }
+
+    /**
+     * Registers a listener that will be called whenever the connection status changes.
+     * @param listener The function to call when the status changes.
+     * @returns An object that can be used to unregister the listener.
+     */
     func onStatusChange(bufferingPolicy: BufferingPolicy) -> Subscription<ConnectionStatusChange>
 }
 
+/**
+ * The different states that the connection can be in through its lifecycle.
+ */
 public enum ConnectionStatus: Sendable {
     // (CHA-CS1a) The INITIALIZED status is a default status when the realtime client is first initialized. This value will only (likely) be seen if the realtime client doesn’t have autoconnect turned on.
+
+    /**
+     * A temporary state for when the library is first initialized.
+     */
     case initialized
+
     // (CHA-CS1b) The CONNECTING status is used when the client is in the process of connecting to Ably servers.
+
+    /**
+     * The library is currently connecting to Ably.
+     */
     case connecting
+
     // (CHA-CS1c) The CONNECTED status is used when the client connected to Ably servers.
+
+    /**
+     * The library is currently connected to Ably.
+     */
     case connected
+
     // (CHA-CS1d) The DISCONNECTED status is used when the client is not currently connected to Ably servers. This state may be temporary as the underlying Realtime SDK seeks to reconnect.
+
+    /**
+     * The library is currently disconnected from Ably, but will attempt to reconnect.
+     */
     case disconnected
+
     // (CHA-CS1e) The SUSPENDED status is used when the client is in an extended state of disconnection, but will attempt to reconnect.
+
+    /**
+     * The library is in an extended state of disconnection, but will attempt to reconnect.
+     */
     case suspended
+
     // (CHA-CS1f) The FAILED status is used when the client is disconnected from the Ably servers due to some non-retriable failure such as authentication failure. It will not attempt to reconnect.
+
+    /**
+     * The library is currently disconnected from Ably and will not attempt to reconnect.
+     */
     case failed
 
     internal init(from realtimeConnectionState: ARTRealtimeConnectionState) {
@@ -41,11 +89,30 @@ public enum ConnectionStatus: Sendable {
     }
 }
 
+/**
+ * Represents a change in the status of the connection.
+ */
 public struct ConnectionStatusChange: Sendable {
+    /**
+     * The new status of the connection.
+     */
     public var current: ConnectionStatus
+
+    /**
+     * The previous status of the connection.
+     */
     public var previous: ConnectionStatus
+
     // TODO: (https://github.com/ably-labs/ably-chat-swift/issues/12): consider how to avoid the need for an unwrap
+    /**
+     * An error that provides a reason why the connection has
+     * entered the new status, if applicable.
+     */
     public var error: ARTErrorInfo?
+
+    /**
+     * The time in milliseconds that the client will wait before attempting to reconnect.
+     */
     public var retryIn: TimeInterval
 
     public init(current: ConnectionStatus, previous: ConnectionStatus, error: ARTErrorInfo? = nil, retryIn: TimeInterval) {

Sources/AblyChat/DefaultMessages.swift

@@ -234,10 +234,11 @@ internal final class DefaultMessages: Messages, EmitsDiscontinuities {
                 case .failed, .suspended:
                     // TODO: Revisit as part of https://github.com/ably-labs/ably-chat-swift/issues/32
                     logger.log(message: "Channel failed to attach", level: .error)
+                    let errorCodeCase = ErrorCode.CaseThatImpliesFixedStatusCode.messagesAttachmentFailed
                     nillableContinuation?.resume(
                         throwing: ARTErrorInfo.create(
-                            withCode: ErrorCode.messagesAttachmentFailed.rawValue,
-                            status: ErrorCode.messagesAttachmentFailed.statusCode,
+                            withCode: errorCodeCase.toNumericErrorCode.rawValue,
+                            status: errorCodeCase.statusCode,
                             message: "Channel failed to attach"
                         )
                     )

Sources/AblyChat/Dependencies.swift

@@ -14,15 +14,15 @@ public protocol RealtimeClientProtocol: ARTRealtimeProtocol, Sendable {
     var connection: Connection { get }
 }
 
-/// Expresses the requirements of the object returned by ``RealtimeClientProtocol.channels``.
+/// Expresses the requirements of the object returned by ``RealtimeClientProtocol/channels``.
 public protocol RealtimeChannelsProtocol: ARTRealtimeChannelsProtocol, Sendable {
     associatedtype Channel: RealtimeChannelProtocol
 
     // It’s not clear to me why ARTRealtimeChannelsProtocol doesn’t include this function (https://github.com/ably/ably-cocoa/issues/1968).
     func get(_ name: String, options: ARTRealtimeChannelOptions) -> Channel
 }
 
-/// Expresses the requirements of the object returned by ``RealtimeChannelsProtocol.get(_:)``.
+/// Expresses the requirements of the object returned by ``RealtimeChannelsProtocol/get(_:options:)``.
 public protocol RealtimeChannelProtocol: ARTRealtimeChannelProtocol, Sendable {}
 
 public protocol ConnectionProtocol: ARTConnectionProtocol, Sendable {}