Adding comments to CallbackExecutor.submit

google-cloud-clients/google-cloud-pubsub/src/main/java/com/google/cloud/pubsub/v1/SequentialExecutorService.java

@@ -115,6 +115,7 @@ private static class AutoExecutor extends SequentialExecutor {
       super(executor);
     }
 
+    @Override
     protected void execute(final String key, final Deque<Runnable> tasks) {
       executor.execute(
           new Runnable() {
@@ -146,29 +147,66 @@ private static class CallbackExecutor extends SequentialExecutor {
       super(executor);
     }
 
+    /**
+     * This method does the following in a chain:
+     *
+     * <ol>
+     *   <li>Creates an `ApiFuture` that can be used for tracking progress.
+     *   <li>Creates a `CancellableRunnable` out of the `Callable`
+     *   <li>Adds the `CancellableRunnable` to the task queue
+     *   <li>Once the task is ready to be run, it will execute the `Callable`
+     *   <li>When the `Callable` completes one of two things happens:
+     *       <ol>
+     *         <li>On success:
+     *             <ol>
+     *               <li>Complete the `ApiFuture` by setting the return value.
+     *               <li>Call the next task.
+     *             </ol>
+     *         <li>On Failure:
+     *             <ol>
+     *               <li>Fail the `ApiFuture` by setting the exception.
+     *               <li>Cancel all tasks in the queue.
+     *             </ol>
+     *       </ol>
+     * </ol>
+     *
+     * @param key The key for the task queue
+     * @param callable The thing to run
+     * @param <T> The return type for the `Callable`'s `ApiFuture`.
+     * @return an `ApiFuture` for tracking.
+     */
     <T> ApiFuture<T> submit(final String key, final Callable<ApiFuture<T>> callable) {
+      // Step 1: create a future for the user
       final SettableApiFuture<T> future = SettableApiFuture.create();
+
+      // Step 2: create the CancellableRunnable
+      // Step 3: add the task to queue via `execute`
       execute(
           key,
           new CancellableRunnable() {
             private boolean cancelled = false;
 
             @Override
             public void run() {
+              // the task was cancelled
               if (cancelled) {
                 return;
               }
+
               try {
+                // Step 4: call the `Callable`
                 ApiFuture<T> callResult = callable.call();
                 ApiFutures.addCallback(
                     callResult,
                     new ApiFutureCallback<T>() {
+                      // Step 5.1: on success
                       @Override
                       public void onSuccess(T msg) {
                         future.set(msg);
                         resume(key);
                       }
 
+                      // Step 5.2: on failure
                       @Override
                       public void onFailure(Throwable e) {
                         future.setException(e);
@@ -193,6 +231,7 @@ public void cancel(Throwable e) {
       return future;
     }
 
+    @Override
     protected void execute(final String key, final Deque<Runnable> tasks) {
       executor.execute(
           new Runnable() {