Clarify streamUpdatesOn and streamUpdates behavior

Author: jguz-pubnub

Sources/Entities/Channel+AsyncAwait.swift

@@ -15,7 +15,9 @@ import PubNubSDK
 /// Extension providing `async-await` support for ``Channel``.
 ///
 public extension Channel {
-  /// Receive updates when specific channels are added, edited or removed.
+  /// Receive updates when specific channels are updated or removed.
+  ///
+  /// Returns the complete list of monitored channels whenever any one of them changes, excluding any that were removed.
   ///
   /// - Parameter channels: Collection containing the channels to watch for updates
   /// - Returns: An asynchronous stream that produces updates when any item in the `channels` collection is updated
@@ -473,7 +475,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 `nil` if the channel was removed.
   func streamUpdates() -> AsyncStream<ChatType.ChatChannelType?> {
     AsyncStream { continuation in
       let autoCloseable = streamUpdates {

Sources/Entities/Channel.swift

@@ -34,14 +34,16 @@ public protocol Channel: CustomStringConvertible {
   /// Represents the type of the given ``Channel``
   var type: ChannelType? { get }
 
-  /// Receive updates when specific channels are added, edited or removed.
+  /// Receive updates when specific channels are updated or removed.
+  ///
+  /// Returns the complete list of monitored channels whenever any one of them changes, excluding any that were removed.
   ///
   /// - Important: Keep a strong reference to the returned ``AutoCloseable`` object as long as you want to receive updates. If ``AutoCloseable`` is deallocated,
   /// the stream will be canceled, and no further items will be produced. You can also stop receiving updates manually by calling ``AutoCloseable/close()``.
   ///
   /// - Parameters:
   ///   - channels: Collection containing the channels to watch for updates
-  ///   - callback: Defines the custom behavior to be executed when detecting channels changes
+  ///   - callback: A closure to be executed when detecting channel changes
   /// - Returns: An ``AutoCloseable`` that you can use to stop receiving objects events by invoking its ``AutoCloseable/close()`` method
   static func streamUpdatesOn(
     channels: [Self],
@@ -387,7 +389,7 @@ public protocol Channel: CustomStringConvertible {
   /// - Important: Keep a strong reference to the returned ``AutoCloseable`` object as long as you want to receive updates. If ``AutoCloseable`` is deallocated,
   /// 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: Function that takes a single Channel object. It defines the custom behavior to be executed when detecting channel changes
+  /// - Parameter callback: A closure to be executed when detecting channel changes. Takes a single Channel object or `nil` if the channel was removed
   /// - Returns: ``AutoCloseable`` interface that lets you stop receiving channel-related updates (objects events) and clean up resources by invoking the `close()` method
   func streamUpdates(
     callback: @escaping ((ChatType.ChatChannelType)?) -> Void

Sources/Entities/Membership+AsyncAwait.swift

@@ -15,7 +15,9 @@ import PubNubSDK
 /// Extension providing `async-await` support for ``Membership``.
 ///
 public extension Membership {
-  /// Receive updates when specific memberships are added, edited or removed.
+  /// Receive updates when specific memberships are updated or removed.
+  ///
+  /// Returns the complete list of monitored memberships whenever any one of them changes, excluding any that were removed.
   ///
   /// - Parameter memberships: Collection containing the ``Membership`` to watch for updates
   /// - Returns: An asynchronous stream that produces updates when any item in the `memberships` collection is updated
@@ -97,9 +99,9 @@ public extension Membership {
     }
   }
 
-  /// You can receive updates when specific user-channel Membership object(s) are added, edited, or removed.
+  /// You can receive updates when this user-channel Membership object is updated 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 updated or `nil` if the membership was removed.
   func streamUpdates() -> AsyncStream<ChatType.ChatMembershipType?> {
     AsyncStream { continuation in
       let autoCloseable = streamUpdates {

Sources/Entities/Membership.swift

@@ -34,14 +34,16 @@ public protocol Membership: CustomStringConvertible {
   /// Timetoken of the last message a user read on a given channel
   var lastReadMessageTimetoken: Timetoken? { get }
 
-  /// Receive updates when specific memberships are added, edited or removed.
+  /// Receive updates when specific memberships are updated or removed.
+  ///
+  /// Returns the complete list of monitored memberships whenever any one of them changes, excluding any that were removed.
   ///
   /// - Important: Keep a strong reference to the returned ``AutoCloseable`` object as long as you want to receive updates. If ``AutoCloseable`` is deallocated,
   /// the stream will be canceled, and no further items will be produced. You can also stop receiving updates manually by calling ``AutoCloseable/close()``.
   ///
   /// - Parameters:
   ///   - memberships: Collection containing the ``Membership`` to watch for updates
-  ///   - callback: Defines the custom behavior to be executed when detecting membership changes
+  ///   - callback: A closure to be executed when detecting membership changes
   /// - Returns: An ``AutoCloseable`` that you can use to stop receiving objects events by invoking its ``AutoCloseable/close()`` method
   static func streamUpdatesOn(
     memberships: [Self],
@@ -94,12 +96,12 @@ public protocol Membership: CustomStringConvertible {
     completion: ((Swift.Result<UInt64?, Error>) -> Void)?
   )
 
-  /// You can receive updates when specific user-channel Membership object(s) are added, edited, or removed.
+  /// You can receive updates when this user-channel Membership object is updated or removed.
   ///
   /// - Important: Keep a strong reference to the returned ``AutoCloseable`` object as long as you want to receive updates. If ``AutoCloseable`` is deallocated,
   /// 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
+  /// - Parameter callback: A closure to be executed when detecting membership changes. Takes a Membership object or `nil` if the membership was removed
   /// - 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)

Sources/Entities/Message+AsyncAwait.swift

@@ -15,7 +15,9 @@ import PubNubSDK
 /// Extension providing `async-await` support for ``Message``.
 ///
 public extension Message {
-  /// Receive updates when specific messages and related message reactions are added, edited, or removed.
+  /// Receive updates when specific messages and related message reactions are updated or removed.
+  ///
+  /// Returns the complete list of monitored messages whenever any one of them changes, excluding any that were removed.
   ///
   /// - Parameter messages: A collection of ``Message`` objects for which you want to get updates on changed messages
   /// - Returns: An asynchronous stream that produces updates when any item in the `messages` collection is updated

Sources/Entities/Message.swift

@@ -61,14 +61,16 @@ public protocol Message: CustomStringConvertible {
   /// Error associated with the message, if any
   var error: Error? { get }
 
-  /// Receive updates when specific messages and related message reactions are added, edited, or removed.
+  /// Receive updates when specific messages and related message reactions are updated or removed.
+  ///
+  /// Returns the complete list of monitored messages whenever any one of them changes, excluding any that were removed.
   ///
   /// - Important: Keep a strong reference to the returned ``AutoCloseable`` object as long as you want to receive updates. If ``AutoCloseable`` is deallocated,
   /// the stream will be canceled, and no further items will be produced. You can also stop receiving updates manually by calling ``AutoCloseable/close()``.
   ///
   /// - Parameters:
   ///   - messages: A collection of ``Message`` objects for which you want to get updates on changed messages
-  ///   - callback: Function that takes a collection of ``Message`` objects. It defines the custom behavior to be executed when detecting message or message reaction changes
+  ///   - callback: A closure to be executed when detecting message or message reaction changes
   /// - Returns: Interface that lets you stop receiving message-related updates by invoking the `close()` method
   static func streamUpdatesOn(
     messages: [Self],

Sources/Entities/User+AsyncAwait.swift

@@ -15,7 +15,9 @@ import PubNubSDK
 /// Extension providing `async-await` support for ``User``.
 ///
 public extension User {
-  /// Receive updates when specific users are added, edited or removed.
+  /// Receive updates when specific users are updated or removed.
+  ///
+  /// Returns the complete list of monitored users whenever any one of them changes, excluding any that were removed.
   ///
   /// - Parameters:
   ///   - users: Collection containing the users to watch for updates
@@ -179,7 +181,7 @@ public extension User {
 
   /// Receives updates on a single User object.
   ///
-  /// - Returns: An asynchronous stream that produces updates when the current ``User`` is edited or removed.
+  /// - Returns: An asynchronous stream that produces updates when the current ``User`` is edited or `nil` if the user was removed.
   func streamUpdates() -> AsyncStream<ChatType.ChatUserType?> {
     AsyncStream { continuation in
       let autoCloseable = streamUpdates {

Sources/Entities/User.swift

@@ -42,14 +42,16 @@ public protocol User: CustomStringConvertible {
   /// Indicates whether the user is currently (at the time of obtaining this ``User`` object) active
   var active: Bool { get }
 
-  /// Receive updates when specific users are added, edited or removed.
+  /// Receive updates when specific users are updated or removed.
+  ///
+  /// Returns the complete list of monitored users whenever any one of them changes, excluding any that were removed.
   ///
   /// - Important: Keep a strong reference to the returned ``AutoCloseable`` object as long as you want to receive updates. If ``AutoCloseable`` is deallocated,
   /// the stream will be canceled, and no further items will be produced. You can also stop receiving updates manually by calling ``AutoCloseable/close()``.
   ///
   /// - Parameters:
   ///   - users: Collection containing the users to watch for updates
-  ///   - callback: Defines the custom behavior to be executed when detecting users changes
+  ///   - callback: A closure to be executed when detecting user changes
   /// - Returns: An ``AutoCloseable`` that you can use to stop receiving objects events by invoking its ``AutoCloseable/close()`` method
   static func streamUpdatesOn(
     users: [ChatType.ChatUserType],
@@ -156,7 +158,7 @@ public protocol User: CustomStringConvertible {
   /// the stream will be canceled, and no further items will be produced. You can also stop receiving updates manually by calling ``AutoCloseable/close()``.
   ///
   /// - Parameters:
-  ///   - callback: A function that is triggered whenever the user's information are changed (added, edited, or removed)
+  ///   - callback: A closure to be executed when detecting user changes. Takes a User object or `nil` if the user was removed
   /// - Returns: An ``AutoCloseable`` that you can use to stop receiving objects events by invoking its ``AutoCloseable/close()`` method
   func streamUpdates(
     callback: @escaping ((ChatType.ChatUserType?) -> Void)