[ECO-5458] Added missing doc for subscription specific public interfaces

Author: sacOO7

lib/src/main/java/io/ably/lib/objects/type/LiveObjectUpdate.java

@@ -1,9 +1,23 @@
 package io.ably.lib.objects.type;
 
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Abstract base class for all LiveObject update notifications.
+ * Provides common structure for updates that occur on LiveMap and LiveCounter objects.
+ * Contains the update data that describes what changed in the live object.
+ */
 public abstract class LiveObjectUpdate {
+    /** The update data containing details about the change that occurred */
+    @Nullable
     protected final Object update;
 
-    protected LiveObjectUpdate(Object update) {
+    /**
+     * Creates a LiveObjectUpdate with the specified update data.
+     *
+     * @param update the data describing the change, or null for no-op updates
+     */
+    protected LiveObjectUpdate(@Nullable Object update) {
         this.update = update;
     }
 }

lib/src/main/java/io/ably/lib/objects/type/counter/LiveCounterChange.java

@@ -4,18 +4,49 @@
 import org.jetbrains.annotations.NonBlocking;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Provides methods to subscribe to real-time updates on LiveCounter objects.
+ * Enables clients to receive notifications when counter values change due to
+ * operations performed by any client connected to the same channel.
+ */
 public interface LiveCounterChange {
 
+    /**
+     * Subscribes to real-time updates on this LiveCounter object.
+     * Multiple listeners can be subscribed to the same object independently.
+     * 
+     * @param listener the listener to be notified of counter updates
+     * @return an ObjectsSubscription for managing this specific listener
+     */
     @NonBlocking
     @NotNull ObjectsSubscription subscribe(@NotNull Listener listener);
 
+    /**
+     * Unsubscribes a specific listener from receiving updates.
+     * Has no effect if the listener is not currently subscribed.
+     * 
+     * @param listener the listener to be unsubscribed
+     */
     @NonBlocking
     void unsubscribe(@NotNull Listener listener);
 
+    /**
+     * Unsubscribes all listeners from receiving updates.
+     * No notifications will be delivered until new listeners are subscribed.
+     */
     @NonBlocking
     void unsubscribeAll();
 
+    /**
+     * Listener interface for receiving LiveCounter updates.
+     */
     interface Listener {
+        /**
+         * Called when the LiveCounter has been updated.
+         * Should execute quickly as it's called from the real-time processing thread.
+         * 
+         * @param update details about the counter change
+         */
         void onUpdated(@NotNull LiveCounterUpdate update);
     }
 }

lib/src/main/java/io/ably/lib/objects/type/counter/LiveCounterUpdate.java

@@ -4,34 +4,63 @@
 import org.jetbrains.annotations.NotNull;
 
 /**
- * Spec: RTLC11, RTLC11a
+ * Represents an update that occurred on a LiveCounter object.
+ * Contains information about counter value changes from increment/decrement operations.
+ * Updates can represent positive changes (increments) or negative changes (decrements).
+ * 
+ * @spec RTLC11, RTLC11a - LiveCounter update structure and behavior
  */
 public class LiveCounterUpdate extends LiveObjectUpdate {
 
+    /**
+     * Creates a no-op LiveCounterUpdate representing no actual change.
+     */
     public LiveCounterUpdate() {
         super(null);
     }
 
+    /**
+     * Creates a LiveCounterUpdate with the specified amount change.
+     * 
+     * @param amount the amount by which the counter changed (positive = increment, negative = decrement)
+     */
     public LiveCounterUpdate(@NotNull Long amount) {
         super(new Update(amount));
     }
 
+    /**
+     * Gets the update information containing the amount of change.
+     * 
+     * @return the Update object with the counter modification amount
+     */
     @NotNull
     public LiveCounterUpdate.Update getUpdate() {
         return (Update) update;
     }
 
     /**
-     * Spec: RTLC11b, RTLC11b1
+     * Contains the specific details of a counter update operation.
+     * 
+     * @spec RTLC11b, RTLC11b1 - Counter update data structure
      */
     public static class Update {
         @NotNull
         private final Long amount;
 
+        /**
+         * Creates an Update with the specified amount.
+         * 
+         * @param amount the counter change amount (positive = increment, negative = decrement)
+         */
         public Update(@NotNull Long amount) {
             this.amount = amount;
         }
 
+        /**
+         * Gets the amount by which the counter value was modified.
+         * 
+         * @return the change amount (positive for increments, negative for decrements)
+         */
         public @NotNull Long getAmount() {
             return amount;
         }

lib/src/main/java/io/ably/lib/objects/type/map/LiveMapChange.java

@@ -4,18 +4,49 @@
 import org.jetbrains.annotations.NonBlocking;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Provides methods to subscribe to real-time updates on LiveMap objects.
+ * Enables clients to receive notifications when map entries are added, updated, or removed.
+ * Uses last-write-wins conflict resolution when multiple clients modify the same key.
+ */
 public interface LiveMapChange {
 
+    /**
+     * Subscribes to real-time updates on this LiveMap object.
+     * Multiple listeners can be subscribed to the same object independently.
+     * 
+     * @param listener the listener to be notified of map updates
+     * @return an ObjectsSubscription for managing this specific listener
+     */
     @NonBlocking
     @NotNull ObjectsSubscription subscribe(@NotNull Listener listener);
 
+    /**
+     * Unsubscribes a specific listener from receiving updates.
+     * Has no effect if the listener is not currently subscribed.
+     * 
+     * @param listener the listener to be unsubscribed
+     */
     @NonBlocking
     void unsubscribe(@NotNull Listener listener);
 
+    /**
+     * Unsubscribes all listeners from receiving updates.
+     * No notifications will be delivered until new listeners are subscribed.
+     */
     @NonBlocking
     void unsubscribeAll();
 
+    /**
+     * Listener interface for receiving LiveMap updates.
+     */
     interface Listener {
+        /**
+         * Called when the LiveMap has been updated.
+         * Should execute quickly as it's called from the real-time processing thread.
+         * 
+         * @param update details about which keys were modified and how
+         */
         void onUpdated(@NotNull LiveMapUpdate update);
     }
 }

lib/src/main/java/io/ably/lib/objects/type/map/LiveMapUpdate.java

@@ -6,36 +6,48 @@
 import java.util.Map;
 
 /**
- * Spec: RTLM18, RTLM18a
+ * Represents an update that occurred on a LiveMap object.
+ * Contains information about which keys were modified and whether they were updated or removed.
+ *
+ * @spec RTLM18, RTLM18a - LiveMap update structure and behavior
  */
 public class LiveMapUpdate extends LiveObjectUpdate {
 
+    /**
+     * Creates a no-op LiveMapUpdate representing no actual change.
+     */
     public LiveMapUpdate() {
         super(null);
     }
 
     /**
-     * Constructor for LiveMapUpdate
-     * @param update The map of updates
+     * Creates a LiveMapUpdate with the specified key changes.
+     *
+     * @param update map of key names to their change types (UPDATED or REMOVED)
      */
     public LiveMapUpdate(@NotNull Map<String, Change> update) {
         super(update);
     }
 
     /**
-     * Get the map of updates
-     * @return The update map
+     * Gets the map of key changes that occurred in this update.
+     *
+     * @return map of key names to their change types
      */
     @NotNull
     public Map<String, Change> getUpdate() {
         return (Map<String, Change>) update;
     }
 
     /**
-     * Spec: RTLM18b
+     * Indicates the type of change that occurred to a map key.
+     *
+     * @spec RTLM18b - Map change types
      */
     public enum Change {
+        /** The key was added or its value was modified */
         UPDATED,
+        /** The key was removed from the map */
         REMOVED
     }
 }

live-objects/src/main/kotlin/io/ably/lib/objects/type/livecounter/LiveCounterChangeCoordinator.kt

@@ -8,13 +8,19 @@ import io.ably.lib.util.Log
 
 internal val noOpCounterUpdate = LiveCounterUpdate()
 
+/**
+ * Interface for handling live counter changes by notifying subscribers of updates.
+ * Implementations typically propagate updates through event emission to registered listeners.
+ */
 internal interface HandlesLiveCounterChange {
+  /**
+   * Notifies all registered listeners about a counter update by propagating the change through the event system.
+   * This method is called when counter data changes and triggers the emission of update events to subscribers.
+   */
   fun notify(update: LiveCounterUpdate)
 }
 
 internal abstract class LiveCounterChangeCoordinator: LiveCounterChange, HandlesLiveCounterChange {
-  private val tag = "DefaultLiveCounterChangeCoordinator"
-
   private val counterChangeEmitter = LiveCounterChangeEmitter()
 
   override fun subscribe(listener: LiveCounterChange.Listener): ObjectsSubscription {

live-objects/src/main/kotlin/io/ably/lib/objects/type/livemap/LiveMapChangeCoordinator.kt

@@ -8,13 +8,19 @@ import io.ably.lib.util.Log
 
 internal val noOpMapUpdate = LiveMapUpdate()
 
+/**
+ * Interface for handling live map changes by notifying subscribers of updates.
+ * Implementations typically propagate updates through event emission to registered listeners.
+ */
 internal interface HandlesLiveMapChange {
+  /**
+   * Notifies all registered listeners about a map update by propagating the change through the event system.
+   * This method is called when map data changes and triggers the emission of update events to subscribers.
+   */
   fun notify(update: LiveMapUpdate)
 }
 
 internal abstract class LiveMapChangeCoordinator: LiveMapChange, HandlesLiveMapChange {
-  private val tag = "DefaultLiveMapChangeCoordinator"
-
   private val mapChangeEmitter = LiveMapChangeEmitter()
 
   override fun subscribe(listener: LiveMapChange.Listener): ObjectsSubscription {