Updated comments to match docc syntax (WIP).

Sources/AblyChat/ChatClient.swift

@@ -88,7 +88,7 @@ public struct ClientOptions: Sendable {
     /**
      * The minimum log level at which messages will be logged.
      *
-     * By default, LogLevel.error will be used.
+     * By default, ``LogLevel/error`` will be used.
      */
     public var logLevel: LogLevel?
 

Sources/AblyChat/Headers.swift

@@ -16,7 +16,7 @@ public enum HeadersValue: Sendable, Codable, Equatable {
  *
  * The headers are a flat key-value map and are sent as part of the realtime
  * message's extras inside the `headers` property. They can serve similar
- * purposes as Metadata but as opposed to Metadata they are read by Ably and
+ * purposes as ``Metadata`` but as opposed to `Metadata` they are read by Ably and
  * can be used for features such as
  * [subscription filters](https://faqs.ably.com/subscription-filters).
  *

Sources/AblyChat/Logging.swift

@@ -5,9 +5,11 @@ public typealias LogContext = [String: any Sendable]
 public protocol LogHandler: AnyObject, Sendable {
     /**
      * A function that can be used to handle log messages.
-     * @param message The message to log.
-     * @param level The log level of the message.
-     * @param context The context of the log message as key-value pairs.
+     *
+     * - Parameters:
+     *   - message: The message to log.
+     *   - level: The log level of the message.
+     *   - context: The context of the log message as key-value pairs.
      */
     func log(message: String, level: LogLevel, context: LogContext?)
 }

Sources/AblyChat/Message.swift

@@ -1,12 +1,12 @@
 import Foundation
 
 /**
- * {@link Headers} type for chat messages.
+ * ``Headers`` type for chat messages.
  */
 public typealias MessageHeaders = Headers
 
 /**
- * {@link Metadata} type for chat messages.
+ * ``Metadata`` type for chat messages.
  */
 public typealias MessageMetadata = Metadata
 
@@ -67,7 +67,7 @@ public struct Message: Sendable, Codable, Identifiable, Equatable {
      * time of a livestream video or flagging this message as important or pinned.
      *
      * Headers are part of the Ably realtime message extras.headers and they can be used
-     * for Filtered Subscriptions and similar.
+     * for [Filtered Subscriptions](https://faqs.ably.com/subscription-filters) and similar.
      *
      * This value is always set. If there are no headers, this is an empty object.
      *

Sources/AblyChat/Messages.swift

@@ -4,7 +4,7 @@ import Ably
  * This interface is used to interact with messages in a chat room: subscribing
  * to new messages, fetching history, or sending messages.
  *
- * Get an instance via {@link Room.messages}.
+ * Get an instance via ``Room/messages``.
  */
 public protocol Messages: AnyObject, Sendable, EmitsDiscontinuities {
     /**
@@ -22,9 +22,10 @@ public protocol Messages: AnyObject, Sendable, EmitsDiscontinuities {
     /**
      * Get messages that have been previously sent to the chat room, based on the provided options.
      *
-     * @param options Options for the query.
-     * @returns A promise that resolves with the paginated result of messages. This paginated result can
-     * be used to fetch more messages if available.
+     * - Parameters:
+     *   - options: Options for the query.
+     *
+     * - Returns: A paginated result object that can be used to fetch more messages if available.
      */
     func get(options: QueryOptions) async throws -> any PaginatedResult<Message>
 
@@ -33,20 +34,21 @@ public protocol Messages: AnyObject, Sendable, EmitsDiscontinuities {
      *
      * This method uses the Ably Chat API endpoint for sending messages.
      *
-     * Note that the Promise may resolve before OR after the message is received
-     * from the realtime channel. This means you may see the message that was just
-     * sent in a callback to `subscribe` before the returned promise resolves.
+     * Note that this function may return before OR after the message is received
+     * from the realtime channel. This means you may see in your ``MessageSubscription``
+     * the message that was just sent before this function returns.
+     *
+     * - Parameters:
+     *   - params: An object containing ``text``, ``headers``, ``metadata`` for the message.
      *
-     * @param params an object containing {text, headers, metadata} for the message
-     * to be sent. Text is required, metadata and headers are optional.
-     * @returns A promise that resolves when the message was published.
+     * - Returns: The published message.
      */
     func send(params: SendMessageParams) async throws -> Message
 
     /**
      * Get the underlying Ably realtime channel used for the messages in this chat room.
      *
-     * @returns The realtime channel.
+     * - Returns: The realtime channel.
      */
     var channel: RealtimeChannelProtocol { get }
 }
@@ -117,32 +119,31 @@ public struct QueryOptions: Sendable {
      * The start of the time window to query from. If provided, the response will include
      * messages with timestamps equal to or greater than this value.
      *
-     * @defaultValue The beginning of time
+     * Defaults to the beginning of time.
      */
     public var start: Date?
 
     /**
      * The end of the time window to query from. If provided, the response will include
      * messages with timestamps less than this value.
      *
-     * @defaultValue Now
+     * Defaults to the current time.
      */
     public var end: Date?
 
     /**
      * The maximum number of messages to return in the response.
      *
-     * @defaultValue 100
+     * Defaults to 100.
      */
     public var limit: Int?
 
     /**
      * The direction to query messages in.
-     * If `forwards`, the response will include messages from the start of the time window to the end.
-     * If `backwards`, the response will include messages from the end of the time window to the start.
-     * If not provided, the default is `forwards`.
+     * If ``ResultOrder/oldestFirst``, the response will include messages from the start of the time window to the end.
+     * If ``ResultOrder/newestFirst``, the response will include messages from the end of the time window to the start.
      *
-     * @defaultValue forwards
+     * Defaults to `oldestFirst`.
      */
     public var orderBy: ResultOrder?
 

Sources/AblyChat/Metadata.swift

@@ -17,6 +17,5 @@ public enum MetadataValue: Sendable, Codable, Equatable {
  *
  * Do not use metadata for authoritative information. There is no server-side
  * validation. When reading the metadata treat it like user input.
- *
  */
 public typealias Metadata = [String: MetadataValue?]

Sources/AblyChat/Occupancy.swift

@@ -23,14 +23,14 @@ public protocol Occupancy: AnyObject, Sendable, EmitsDiscontinuities {
     /**
      * Get the current occupancy of the chat room.
      *
-     * @returns A promise that resolves to the current occupancy of the chat room.
+     * - Returns: A current occupancy of the chat room.
      */
     func get() async throws -> OccupancyEvent
 
     /**
      * Get underlying Ably channel for occupancy events.
      *
-     * @returns The underlying Ably channel for occupancy events.
+     * - Returns: The underlying Ably channel for occupancy events.
      */
     var channel: RealtimeChannelProtocol { get }
 }

Sources/AblyChat/Presence.swift

@@ -36,7 +36,7 @@ public enum PresenceCustomData: Sendable, Codable, Equatable {
 }
 
 /**
- * Type for PresenceData. Any JSON serializable data type.
+ * Type for ``PresenceData``. Any JSON serializable data type.
  */
 public typealias UserCustomData = [String: PresenceCustomData]
 
@@ -80,9 +80,9 @@ internal extension PresenceData {
 
 /**
  * This interface is used to interact with presence in a chat room: subscribing to presence events,
- * fetching presence members, or sending presence events (join,update,leave).
+ * fetching presence members, or sending presence events (`enter`, `update`, `leave`).
  *
- * Get an instance via {@link Room.presence}.
+ * Get an instance via ``Room/presence``.
  */
 public protocol Presence: AnyObject, Sendable, EmitsDiscontinuities {
     /**
@@ -92,36 +92,55 @@ public protocol Presence: AnyObject, Sendable, EmitsDiscontinuities {
 
     /**
      * Method to get list of the current online users and returns the latest presence messages associated to it.
-     * @param {Ably.RealtimePresenceParams} params - Parameters that control how the presence set is retrieved.
-     * @returns {Promise<PresenceMessage[]>} or upon failure, the promise will be rejected with an {@link Ably.ErrorInfo} object which explains the error.
+     *
+     * - Parameters:
+     *   - params: ``PresenceQuery`` that control how the presence set is retrieved.
+     *
+     * - Returns: An array of ``PresenceMember``s.
+     *
+     * - Throws: An ``ARTErrorInfo``.
      */
     func get(params: PresenceQuery) async throws -> [PresenceMember]
 
     /**
-     * Method to check if user with supplied clientId is online
-     * @param {string} clientId - The client ID to check if it is present in the room.
-     * @returns {Promise<{boolean}>} or upon failure, the promise will be rejected with an {@link Ably.ErrorInfo} object which explains the error.
+     * Method to check if user with supplied clientId is online.
+     *
+     * - Parameters:
+     *   - clientId: The client ID to check if it is present in the room.
+     *
+     * - Returns: A boolean value indicating whether the user is present in the room.
+     *
+     * - Throws: An ``ARTErrorInfo``.
      */
     func isUserPresent(clientID: String) async throws -> Bool
 
     /**
      * Method to join room presence, will emit an enter event to all subscribers. Repeat calls will trigger more enter events.
-     * @param {PresenceData} data - The users data, a JSON serializable object that will be sent to all subscribers.
-     * @returns {Promise<void>} or upon failure, the promise will be rejected with an {@link Ably.ErrorInfo} object which explains the error.
+     *
+     * - Parameters:
+     *   - data: The users data, a JSON serializable object that will be sent to all subscribers.
+     *
+     * - Throws: An ``ARTErrorInfo``.
      */
     func enter(data: PresenceData?) async throws
 
     /**
      * Method to update room presence, will emit an update event to all subscribers. If the user is not present, it will be treated as a join event.
-     * @param {PresenceData} data - The users data, a JSON serializable object that will be sent to all subscribers.
-     * @returns {Promise<void>} or upon failure, the promise will be rejected with an {@link Ably.ErrorInfo} object which explains the error.
+     *
+     * - Parameters:
+     *   - data: The users data, a JSON serializable object that will be sent to all subscribers.
+     *
+     * - Throws: An ``ARTErrorInfo``.
      */
     func update(data: PresenceData?) async throws
 
     /**
      * Method to leave room presence, will emit a leave event to all subscribers. If the user is not present, it will be treated as a no-op.
-     * @param {PresenceData} data - The users data, a JSON serializable object that will be sent to all subscribers.
-     * @returns {Promise<void>} or upon failure, the promise will be rejected with an {@link Ably.ErrorInfo} object which explains the error.
+     *
+     * - Parameters:
+     *   - data: The users data, a JSON serializable object that will be sent to all subscribers.
+     *
+     * - Throws: An ``ARTErrorInfo``.
      */
     func leave(data: PresenceData?) async throws
 

Sources/AblyChat/Reaction.swift

@@ -1,12 +1,12 @@
 import Foundation
 
 /**
- * {@link Headers} type for chat messages.
+ * ``Headers`` type for chat reactions.
  */
 public typealias ReactionHeaders = Headers
 
 /**
- * {@link Metadata} type for chat messages.
+ * ``Metadata`` type for chat reactions.
  */
 public typealias ReactionMetadata = Metadata
 

Sources/AblyChat/Room.swift

@@ -6,52 +6,57 @@ import Ably
 public protocol Room: AnyObject, Sendable {
     /**
      * The unique identifier of the room.
-     * @returns The room identifier.
+     * - Returns: The room identifier.
      */
     var roomID: String { get }
 
     /**
      * Allows you to send, subscribe-to and query messages in the room.
-     * @returns The messages instance for the room.
+     *
+     * - Returns: The messages instance for the room.
      */
     var messages: any Messages { get }
 
     /**
      * Allows you to subscribe to presence events in the room.
      *
-     * @throws {@link ErrorInfo}} if presence is not enabled for the room.
-     * @returns The presence instance for the room.
+     * - Note: To access this property if presence is not enabled for the room is a programmer error, and will lead to `fatalError` being called.
+     *
+     * - Returns: The presence instance for the room.
      */
     var presence: any Presence { get }
 
     /**
      * Allows you to interact with room-level reactions.
      *
-     * @throws {@link ErrorInfo} if reactions are not enabled for the room.
-     * @returns The room reactions instance for the room.
+     * - Note: To access this property if presence is not enabled for the room is a programmer error, and will lead to `fatalError` being called.
+     *
+     * - Returns: The room reactions instance for the room.
      */
     var reactions: any RoomReactions { get }
 
     /**
      * Allows you to interact with typing events in the room.
      *
-     * @throws {@link ErrorInfo} if typing is not enabled for the room.
-     * @returns The typing instance for the room.
+     * - Note: To access this property if presence is not enabled for the room is a programmer error, and will lead to `fatalError` being called.
+     *
+     * - Returns: The typing instance for the room.
      */
     var typing: any Typing { get }
 
     /**
      * Allows you to interact with occupancy metrics for the room.
      *
-     * @throws {@link ErrorInfo} if occupancy is not enabled for the room.
-     * @returns The occupancy instance for the room.
+     * - Note: To access this property if presence is not enabled for the room is a programmer error, and will lead to `fatalError` being called.
+     *
+     * - Returns: The occupancy instance for the room.
      */
     var occupancy: any Occupancy { get }
 
     /**
      * The current status of the room.
      *
-     * @returns The current status.
+     * - Returns: The current room status.
      */
     var status: RoomStatus { get async }
 
@@ -77,21 +82,21 @@ public protocol Room: AnyObject, Sendable {
      * If the room enters the suspended state, then the call to attach will reject with the {@link ErrorInfo} that caused the suspension. However,
      * the room will automatically retry attaching after a delay.
      *
-     * @returns A promise that resolves when the room is attached.
+     * - Returns: A promise that resolves when the room is attached.
      */
     func attach() async throws
 
     /**
      * Detaches from the room to stop receiving events in realtime.
      *
-     * @returns A promise that resolves when the room is detached.
+     * - Returns: A promise that resolves when the room is detached.
      */
     func detach() async throws
 
     /**
      * Returns the room options.
      *
-     * @returns A copy of the options used to create the room.
+     * - Returns: A copy of the options used to create the room.
      */
     var options: RoomOptions { get }
 }