Add docs for ApolloCallTracker

apollo-runtime/src/main/java/com/apollographql/apollo/internal/ApolloCallTracker.java

@@ -6,6 +6,9 @@
 import java.util.ArrayDeque;
 import java.util.Deque;
 
+/**
+ * ApolloCallTracker is responsible for keeping track of running {@link ApolloCall} & {@link ApolloPrefetch} objects.
+ */
 public class ApolloCallTracker {
 
   private Runnable idleCallback;
@@ -18,10 +21,25 @@ public class ApolloCallTracker {
   public ApolloCallTracker() {
   }
 
-  void syncPrefetchInProgress(ApolloPrefetch apolloPrefetch) {
+  /**
+   * <p>Adds this {@link ApolloPrefetch} to the underlying data structure keeping track of the in progress synchronous
+   * prefetch objects.</p>
+   *
+   * <p><b>Note</b>: This method needs to be called right before a prefetch call is executed.</p>
+   */
+  synchronized void syncPrefetchInProgress(ApolloPrefetch apolloPrefetch) {
     runningSyncPrefetches.add(apolloPrefetch);
   }
 
+  /**
+   * <p>Removes this {@link ApolloPrefetch} from the underlying data structure keeping track of the in progress
+   * synchronous prefetch objects, if it is found, else throws an {@link AssertionError}.</p> If the removal operation
+   * is successful and no active running calls are found, then the registered {@link ApolloCallTracker#idleCallback} is
+   * invoked.
+   *
+   * <p><b>Note</b>: This method needs to be called right after a prefetch call is completed (whether successful or
+   * failed).</p>
+   */
   void syncPrefetchFinished(ApolloPrefetch apolloPrefetch) {
     Runnable idleCallback;
     int runningCallsCount;
@@ -35,10 +53,25 @@ void syncPrefetchFinished(ApolloPrefetch apolloPrefetch) {
     executeCallBackIfCallsAreFinished(runningCallsCount, idleCallback);
   }
 
+  /**
+   * <p>Adds this asyncCall representing an asynchronous {@link ApolloPrefetch} to the underlying data structure keeping
+   * track of the in progress asynchronous prefetch objects.</p>
+   *
+   * <p><b>Note</b>: This method needs to be called right before a prefetch call is executed.</p>
+   */
   synchronized void asyncPrefetchInProgress(RealApolloPrefetch.AsyncCall asyncCall) {
     runningAsyncPrefetches.add(asyncCall);
   }
 
+  /**
+   * <p>Removes this asyncCall representing an asynchronous {@link ApolloPrefetch} from the underlying data structure
+   * keeping track of the in progress asynchronous prefetch objects, if it is found, else throws an {@link
+   * AssertionError}.</p> If the removal operation is successful and no active running calls are found, then the
+   * registered {@link ApolloCallTracker#idleCallback} is invoked.
+   *
+   * <p><b>Note</b>: This method needs to be called right after a prefetch call is completed (whether successful or
+   * failed).</p>
+   */
   void asyncPrefetchFinished(RealApolloPrefetch.AsyncCall asyncCall) {
     Runnable idleCallback;
     int runningCallsCount;
@@ -52,10 +85,25 @@ void asyncPrefetchFinished(RealApolloPrefetch.AsyncCall asyncCall) {
     executeCallBackIfCallsAreFinished(runningCallsCount, idleCallback);
   }
 
+  /**
+   * <p>Adds this {@link ApolloCall} to the underlying data structure keeping track of the in progress synchronous
+   * apolloCall objects.</p>
+   *
+   * <p><b>Note</b>: This method needs to be called right before an apolloCall is executed.</p>
+   */
   synchronized void syncCallInProgress(ApolloCall apolloCall) {
     runningSyncCalls.add(apolloCall);
   }
 
+  /**
+   * <p>Removes this {@link ApolloCall} from the underlying data structure keeping track of the in progress synchronous
+   * apolloCall objects, if it is found, else throws an {@link AssertionError}.</p> If the removal operation is
+   * successful and no active running calls are found, then the registered {@link ApolloCallTracker#idleCallback} is
+   * invoked.
+   *
+   * <p><b>Note</b>: This method needs to be called right after an apolloCall is completed (whether successful or
+   * failed).</p>
+   */
   void syncCallFinished(ApolloCall apolloCall) {
     Runnable idleCallback;
     int runningCallsCount;
@@ -69,10 +117,25 @@ void syncCallFinished(ApolloCall apolloCall) {
     executeCallBackIfCallsAreFinished(runningCallsCount, idleCallback);
   }
 
+  /**
+   * <p>Adds this asyncCall representing an asynchronous {@link ApolloCall} to the underlying data structure keeping
+   * track of the in progress asynchronous apolloCall objects.</p>
+   *
+   * <p><b>Note</b>: This method needs to be called right before an apolloCall is executed.</p>
+   */
   synchronized void asyncCallInProgress(RealApolloCall<?>.AsyncCall asyncCall) {
     runningAsyncCalls.add(asyncCall);
   }
 
+  /**
+   * <p>Removes this asyncCall representing an asynchronous {@link ApolloCall} from the underlying data structure
+   * keeping track of the in progress asynchronous apolloCall objects, if it is found, else throws an {@link
+   * AssertionError}.</p> If the removal operation is successful and no active running calls are found, then the
+   * registered {@link ApolloCallTracker#idleCallback} is invoked.
+   *
+   * <p><b>Note</b>: This method needs to be called right after an apolloCall is completed (whether successful or
+   * failed).</p>
+   */
   void asyncCallFinished(RealApolloCall<?>.AsyncCall asyncCall) {
     Runnable idleCallback;
     int runningCallsCount;
@@ -86,6 +149,9 @@ void asyncCallFinished(RealApolloCall<?>.AsyncCall asyncCall) {
     executeCallBackIfCallsAreFinished(runningCallsCount, idleCallback);
   }
 
+  /**
+   * Registers idleCallback which is invoked when the apolloClient becomes idle.
+   */
   public synchronized void setIdleCallback(Runnable idleCallback) {
     this.idleCallback = idleCallback;
   }
@@ -96,6 +162,9 @@ private void executeCallBackIfCallsAreFinished(int runningCallsCount, Runnable i
     }
   }
 
+  /**
+   * Returns a total count of in progress {@link ApolloCall} & {@link ApolloPrefetch} objects.
+   */
   public int getRunningCallsCount() {
     return runningAsyncCalls.size() +
         runningSyncCalls.size() +