Fix Swift inline docs (#25)

Author: jguz-pubnub

Sources/Chat+AsyncAwait.swift

@@ -137,7 +137,7 @@ public extension Chat {
   ///   - custom: Any custom properties or metadata associated with the user in the form of a `[String: JSONCodableScalar]`
   ///   - status: Tag that lets you categorize your app users by their current state. The tag choice is entirely up to you and depends on your use case
   ///   - type: Tag that lets you categorize your app users by their functional roles. The tag choice is entirely up to you and depends on your use case
-  /// - Returns: Updated user
+  /// - Returns: The updated ``User`` instance
   func updateUser(
     id: String,
     name: String? = nil,
@@ -287,7 +287,7 @@ public extension Chat {
   ///   - description: Channel description
   ///   - status: Tag that lets you categorize your app users by their current state. The tag choice is entirely up to you and depends on your use case
   ///   - type: Tag that lets you categorize your app users by their functional roles. The tag choice is entirely up to you and depends on your use case
-  /// - Returns: A value containing an updated channel and its metadata
+  /// - Returns: A value containing an updated ``Channel`` and its metadata
   func updateChannel(
     id: String,
     name: String? = nil,
@@ -378,10 +378,12 @@ public extension Chat {
 
   /// Creates a public channel that let users engage in open conversations with many people. Unlike group chats, anyone can join public channels.
   ///
+  /// If you don't provide the name, the channel will get the same name as id (value of `channelId`)
+  ///
   /// - Parameters:
   ///   - channelId: ID of the public channel. The channel ID is created automatically using the UUID generator. You can override it by providing your own ID
   ///   - channelName: Display name for the channel
-  ///   - channelDescription: If you don't provide the name, the channel will get the same name as id (value of `channelId`)
+  ///   - channelDescription: Additional details about the channel
   ///   - channelCustom: Any custom properties or metadata associated with the channel in the form of a map of key-value pairs
   ///   - channelStatus: Current status of the channel, like online, offline, or archived
   /// - Returns: A value containing details about created ``Channel``

Sources/Chat.swift

@@ -44,7 +44,7 @@ public protocol Chat: AnyObject {
 
   /// An object for manipulating the list of muted users.
   ///
-  /// The list is local to this instance of Chat (it is not persisted anywhere) unless ``ChatConfiguration/syncMutedUsers`` is enabled, in which case it will be synced
+  /// The list is local to this instance of ``Chat`` (it is not persisted anywhere) unless ``ChatConfiguration/syncMutedUsers`` is enabled, in which case it will be synced
   /// using App Context for the current user.
   ///
   /// Please note that this is not a server-side moderation mechanism, but rather a way to ignore messages from certain users on the client.
@@ -75,7 +75,7 @@ public protocol Chat: AnyObject {
   ///   - status: Tag that lets you categorize your app users by their current state. The tag choice is entirely up to you and depends on your use case
   ///   - type: Tag that lets you categorize your app users by their functional roles. The tag choice is entirely up to you and depends on your use case
   ///   - completion: The async `Result` of the method call
-  ///     - **Success**: The user was successfully created and returns the created user
+  ///     - **Success**: The ``User`` was successfully created and returns the created user
   ///     - **Failure**: An `Error` describing the failure
   func createUser(
     id: String,
@@ -94,7 +94,7 @@ public protocol Chat: AnyObject {
   /// - Parameters:
   ///   - userId: Unique user identifier (up to 92 UTF-8 characters).
   ///   - completion: The async `Result` of the method call
-  ///     - **Success**: The user was successfully returned
+  ///     - **Success**: The ``User`` was successfully returned
   ///     - **Failure**: An `Error` describing the failure
   func getUser(
     userId: String,
@@ -190,7 +190,7 @@ public protocol Chat: AnyObject {
   /// - Parameters:
   ///   - channelId: Unique channel identifier (up to 92 UTF-8 byte sequences)
   ///   - completion: The async `Result` of the method call
-  ///     - **Success**: A value containing a channel object with its metadata
+  ///     - **Success**: A value containing a ``Channel`` object with its metadata
   ///     - **Failure**: An `Error` describing the failure
   func getChannel(
     channelId: String,
@@ -225,7 +225,7 @@ public protocol Chat: AnyObject {
   ///   - status: Tag that lets you categorize your app users by their current state. The tag choice is entirely up to you and depends on your use case
   ///   - type: Tag that lets you categorize your app users by their functional roles. The tag choice is entirely up to you and depends on your use case
   ///   - completion: The async `Result` of the method call
-  ///     - **Success**: A value containing an updated channel and its metadata
+  ///     - **Success**: A value containing an updated ``Channel`` and its metadata
   ///     - **Failure**: An `Error` describing the failure
   func updateChannel(
     id: String,
@@ -281,10 +281,12 @@ public protocol Chat: AnyObject {
 
   /// Creates a public channel that let users engage in open conversations with many people. Unlike group chats, anyone can join public channels.
   ///
+  /// If you don't provide the name, the channel will get the same name as id (value of `channelId`)
+  ///
   /// - Parameters:
   ///   - channelId: ID of the public channel. The channel ID is created automatically using the UUID generator. You can override it by providing your own ID
   ///   - channelName: Display name for the channel
-  ///   - channelDescription: If you don't provide the name, the channel will get the same name as id (value of `channelId`)
+  ///   - channelDescription: Additional details about the channel
   ///   - channelCustom: Any custom properties or metadata associated with the channel in the form of a map of key-value pairs
   ///   - channelStatus: Current status of the channel, like online, offline, or archived
   ///   - completion: The async `Result` of the method call
@@ -360,7 +362,7 @@ public protocol Chat: AnyObject {
   ///   - channelId: Channel to listen for new events
   ///   - customMethod: An optional custom method for emitting events
   ///   - callback: A function that is called with an ``EventWrapper`` as its parameter. It defines the custom behavior to be executed whenever an event is detected on the specified channel
-  /// - Returns: ``AutoCloseable`` interface you can call to stop listening for new events and clean up resources when they re no longer needed by invoking the `close()` method
+  /// - Returns: ``AutoCloseable`` interface you can call to stop listening for new events and clean up resources when they re no longer needed by invoking the ``AutoCloseable/close()`` method
   func listenForEvents<T: EventContent>(
     type: T.Type,
     channelId: String,

Sources/Entities/Channel+AsyncAwait.swift

@@ -38,7 +38,7 @@ public extension Channel {
   ///   - description: Additional details about the channel
   ///   - status: Current status of the channel, like online, offline, or archived
   ///   - type: Represents the type of channel
-  /// - Returns: The updated channel object with its metadata
+  /// - Returns: The updated ``Channel`` object with its metadata
   func update(
     name: String? = nil,
     custom: [String: JSONCodableScalar]? = nil,
@@ -103,7 +103,7 @@ public extension Channel {
   /// Activates a typing indicator on a given channel.
   ///
   /// The method sets a flag (typingSent) to indicate that a typing signal is in progress and adds a timer to reset
-  /// the flag after a specified timeout. You can change the default typing timeout and set your own value during the Chat SDK configuration (init() method)
+  /// the flag after a specified timeout. You can change the default typing timeout and set your own value during the Chat SDK configuration initialization
   /// using the `typingTimeout` parameter
   ///
   /// - Returns: A `Timetoken` indicating the action timestamp
@@ -277,7 +277,7 @@ public extension Channel {
   ///
   /// - Parameters:
   ///   - users: List of users you want to invite to the ``Channel``. You can invite up to 100 users in one call
-  ///   - completion: List of ``Membership`` of invited users
+  /// - Returns: List of ``Membership`` of invited users
   @discardableResult
   func inviteMultiple(users: [ChatType.ChatUserType]) async throws -> [ChatType.ChatMembershipType] {
     try await withCheckedThrowingContinuation { continuation in
@@ -299,7 +299,7 @@ public extension Channel {
   ///   - page: Object used for pagination to define which previous or next result page you want to fetch
   ///   - filter: Expression used to filter the results. Returns only these members whose properties satisfy the given expression
   ///   - sort: A collection to specify the sort order. Available options are id, name, and updated
-  ///   - completion: A `Tuple` containing an array of the members of the channel, and the next pagination `PubNubHashedPage` (if one exists)
+  /// - Returns: A `Tuple` containing an array of the members of the channel, and the next pagination `PubNubHashedPage` (if one exists)
   func getMembers(
     limit: Int? = nil,
     page: PubNubHashedPage? = nil,
@@ -320,7 +320,6 @@ public extension Channel {
 
   /// Watch the ``Channel`` content without a need to join the ``Channel``.
   ///
-  /// - Parameter callback: Defines the custom behavior to be executed whenever a message is received on the ``Channel``
   /// - Returns: An asynchronous stream that produces a new value every time a new message is published on the current channel
   func connect() -> AsyncStream<ChatType.ChatMessageType> {
     AsyncStream { continuation in
@@ -474,7 +473,7 @@ public extension Channel {
 
   /// Receives updates on a single ``Channel`` object.
   ///
-  /// - Returns: An asynchronous stream that produces updates when the current Channel is edited or removed.
+  /// - Returns: An asynchronous stream that produces updates when the current ``Channel`` is edited or removed.
   func streamUpdates() -> AsyncStream<ChatType.ChatChannelType?> {
     AsyncStream { continuation in
       let autoCloseable = streamUpdates {
@@ -581,9 +580,7 @@ public extension Channel {
   ///   - startTimetoken: The start timetoken for fetching the history of reported messages, which allows specifying the point in time where the history retrieval should begin
   ///   - endTimetoken: The end time token for fetching the history of reported messages, which allows specifying the point in time where the history retrieval should end
   ///   - count: The number of reported message events to fetch from the history
-  ///   - completion: The async `Result` of the method call
-  ///     - **Success**: A `Tuple` containing an array of `EventWrapper<EventContent>`, and a boolean indicating whether there are more messages available beyond the current result set
-  ///     - **Failure**: An `Error` describing the failure
+  /// - Returns: A `Tuple` containing an array of `EventWrapper<EventContent>`, and a boolean indicating whether there are more messages available beyond the current result set
   func getMessageReportsHistory(
     startTimetoken: Timetoken? = nil,
     endTimetoken: Timetoken? = nil,

Sources/Entities/Channel.swift

@@ -42,7 +42,7 @@ public protocol Channel: CustomStringConvertible {
   /// - Parameters:
   ///   - channels: Collection containing the channels to watch for updates
   ///   - callback: Defines the custom behavior to be executed when detecting channels changes
-  /// - Returns: An ``AutoCloseable`` that you can use to stop receiving objects events by invoking its `close()` method
+  /// - Returns: An ``AutoCloseable`` that you can use to stop receiving objects events by invoking its ``AutoCloseable/close()`` method
   static func streamUpdatesOn(
     channels: [Self],
     callback: @escaping (([Self]) -> Void)
@@ -57,7 +57,7 @@ public protocol Channel: CustomStringConvertible {
   ///   - status: Current status of the channel, like online, offline, or archived
   ///   - type: Represents the type of channel
   ///   - completion: The async `Result` of the method call
-  ///     - **Success**: The updated channel object with its metadata
+  ///     - **Success**: The updated ``Channel`` object with its metadata
   ///     - **Failure**: An `Error` describing the failure
   func update(
     name: String?,
@@ -95,7 +95,7 @@ public protocol Channel: CustomStringConvertible {
   /// Activates a typing indicator on a given channel.
   ///
   /// The method sets a flag (typingSent) to indicate that a typing signal is in progress and adds a timer to reset
-  /// the flag after a specified timeout. You can change the default typing timeout and set your own value during the Chat SDK configuration (init() method)
+  /// the flag after a specified timeout. You can change the default typing timeout and set your own value during the Chat SDK configuration initialization
   /// using the `typingTimeout` parameter
   ///
   /// - Parameters:
@@ -183,6 +183,7 @@ public protocol Channel: CustomStringConvertible {
   ///   - textLinks: Returned list of text links that are shown as text in the message
   ///   - quotedMessage: Object added to a message when you quote another message
   ///   - files: One or multiple files attached to the text message
+  ///   - customPushData: Additional key-value pairs that will be added to the FCM and/or APNS push messages for the message itself and any user mentions
   ///   - completion: The async `Result` of the method callnel
   ///     - **Success**: The timetoken of the sent message
   ///     - **Failure**: An `Error` describing the failure
@@ -330,7 +331,7 @@ public protocol Channel: CustomStringConvertible {
   /// - Parameters:
   ///   - timetoken: Timetoken of the message you want to retrieve from Message Persistence
   ///   - completion: The async `Result` of the method call
-  ///     - **Success**: A message object (if any)
+  ///     - **Success**: A ``Message`` object (if any)
   ///     - **Failure**: An `Error` describing the failure
   func getMessage(
     timetoken: Timetoken,
@@ -375,7 +376,7 @@ public protocol Channel: CustomStringConvertible {
   ///
   /// - Parameters:
   ///   - completion: The async `Result` of the method call
-  ///     - **Success**: A channel with updated `custom` field
+  ///     - **Success**: A ``Channel`` with updated ``Channel/custom`` field
   ///     - **Failure**: An `Error` describing the failure
   func unpinMessage(
     completion: ((Swift.Result<Self, Error>) -> Void)?

Sources/Entities/Membership+AsyncAwait.swift

@@ -99,7 +99,7 @@ public extension Membership {
 
   /// You can receive updates when specific user-channel Membership object(s) are added, edited, or removed.
   ///
-  /// - Returns: An asynchronous stream that produces updates when the current Membership is edited or removed.
+  /// - Returns: An asynchronous stream that produces updates when the current ``Membership`` is edited or removed.
   func streamUpdates() -> AsyncStream<ChatType.ChatMembershipType?> {
     AsyncStream { continuation in
       let autoCloseable = streamUpdates {

Sources/Entities/Membership.swift

@@ -42,7 +42,7 @@ public protocol Membership: CustomStringConvertible {
   /// - Parameters:
   ///   - memberships: Collection containing the ``Membership`` to watch for updates
   ///   - callback: Defines the custom behavior to be executed when detecting membership changes
-  /// - Returns: An ``AutoCloseable`` that you can use to stop receiving objects events by invoking its `close()` method
+  /// - Returns: An ``AutoCloseable`` that you can use to stop receiving objects events by invoking its ``AutoCloseable/close()`` method
   static func streamUpdatesOn(
     memberships: [Self],
     callback: @escaping (([Self]) -> Void)
@@ -100,7 +100,7 @@ public protocol Membership: CustomStringConvertible {
   /// the stream will be canceled, and no further items will be produced. You can also stop receiving updates manually by calling ``AutoCloseable/close()``.
   ///
   /// - Parameter callback: Defines the custom behavior to be executed when detecting membership changes
-  /// - Returns: An ``AutoCloseable`` that you can use to stop receiving objects events by invoking its `close()` method
+  /// - Returns: An ``AutoCloseable`` that you can use to stop receiving objects events by invoking its ``AutoCloseable/close()`` method
   func streamUpdates(
     callback: @escaping ((ChatType.ChatMembershipType?) -> Void)
   ) -> AutoCloseable

Sources/Entities/Message+AsyncAwait.swift

@@ -106,7 +106,7 @@ public extension Message {
 
   /// Attach this message to its channel.
   ///
-  /// - Returns: The updated Channel metadata
+  /// - Returns: The updated ``Channel`` metadata
   @discardableResult
   func pin() async throws -> ChatType.ChatChannelType {
     try await withCheckedThrowingContinuation { continuation in
@@ -205,7 +205,7 @@ public extension Message {
 
   /// Removes a thread (channel) for a selected message.
   ///
-  /// - Returns: The updated channel object after the removal of the thread
+  /// - Returns: The updated ``Channel`` object after the removal of the thread
   func removeThread() async throws -> ChatType.ChatChannelType? {
     try await withCheckedThrowingContinuation { continuation in
       removeThread {
@@ -241,8 +241,7 @@ public extension Message {
 
   /// You can receive updates when this message and related message reactions are added, edited, or removed.
   ///
-  /// - Parameter completion: Function that takes a single Message object. It defines the custom behavior to be executed when detecting message or message reaction changes
-  /// - Returns: An asynchronous stream that produces updates when the current Message is edited or removed.
+  /// - Returns: An asynchronous stream that produces updates when the current ``Message`` is edited.
   func streamUpdates() -> AsyncStream<Self> {
     AsyncStream { continuation in
       let autoCloseable = streamUpdates {
@@ -254,7 +253,7 @@ public extension Message {
     }
   }
 
-  /// If you delete a message, you can restore its content together with the attached files using the `restore()` method.
+  /// If you delete a message, you can restore its content together with the attached files using the ``restore()`` method.
   ///
   /// This is possible, however, only if the message you want to restore was soft deleted (the soft parameter was set to true when deleting it). Hard deleted messages cannot be restored as their data
   /// is no longer available in Message Persistence. This method also requires Message Persistence configuration. To manage messages, you must enable Message Persistence for your app's keyset