diff --git a/Sources/AblyChat/ChatClient.swift b/Sources/AblyChat/ChatClient.swift index 8dfa7c2..f880dd7 100644 --- a/Sources/AblyChat/ChatClient.swift +++ b/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? diff --git a/Sources/AblyChat/Headers.swift b/Sources/AblyChat/Headers.swift index 3824cbb..7fbd9a5 100644 --- a/Sources/AblyChat/Headers.swift +++ b/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). * diff --git a/Sources/AblyChat/Logging.swift b/Sources/AblyChat/Logging.swift index a6e3a9d..2d6c7d6 100644 --- a/Sources/AblyChat/Logging.swift +++ b/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?) } diff --git a/Sources/AblyChat/Message.swift b/Sources/AblyChat/Message.swift index 2faa18a..71d94c5 100644 --- a/Sources/AblyChat/Message.swift +++ b/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. * diff --git a/Sources/AblyChat/Messages.swift b/Sources/AblyChat/Messages.swift index 9696869..2ea8f11 100644 --- a/Sources/AblyChat/Messages.swift +++ b/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 @@ -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,7 +119,7 @@ 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? @@ -125,24 +127,23 @@ public struct QueryOptions: Sendable { * 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? diff --git a/Sources/AblyChat/Metadata.swift b/Sources/AblyChat/Metadata.swift index 5348496..dfeba28 100644 --- a/Sources/AblyChat/Metadata.swift +++ b/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?] diff --git a/Sources/AblyChat/Occupancy.swift b/Sources/AblyChat/Occupancy.swift index e9d508f..e856c01 100644 --- a/Sources/AblyChat/Occupancy.swift +++ b/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 } } diff --git a/Sources/AblyChat/Presence.swift b/Sources/AblyChat/Presence.swift index 7f78b36..6b2a2cf 100644 --- a/Sources/AblyChat/Presence.swift +++ b/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} 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} 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} 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} 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 diff --git a/Sources/AblyChat/Reaction.swift b/Sources/AblyChat/Reaction.swift index 4e9f9ce..dde293c 100644 --- a/Sources/AblyChat/Reaction.swift +++ b/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 diff --git a/Sources/AblyChat/Room.swift b/Sources/AblyChat/Room.swift index ed3d11d..cdf3664 100644 --- a/Sources/AblyChat/Room.swift +++ b/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 } }