2.x: document (internal) SimpleQueue (#5056)

Author: akarnokd

src/main/java/io/reactivex/internal/fuseable/SimplePlainQueue.java

@@ -16,7 +16,7 @@
 import io.reactivex.annotations.Nullable;
 
 /**
- * Override of the SimpleQueue interface with no throws Exception on poll.
+ * Override of the SimpleQueue interface with no throws Exception on poll().
  *
  * @param <T> the value type to enqueue and dequeue, not null
  */

src/main/java/io/reactivex/internal/fuseable/SimpleQueue.java

@@ -13,7 +13,7 @@
 
 package io.reactivex.internal.fuseable;
 
-import io.reactivex.annotations.Nullable;
+import io.reactivex.annotations.*;
 
 /**
  * A minimalist queue interface without the method bloat of java.util.Collection and java.util.Queue.
@@ -22,17 +22,50 @@
  */
 public interface SimpleQueue<T> {
 
-    boolean offer(T value);
+    /**
+     * Atomically enqueue a single.
+     * @param value the value to enqueue, not null
+     * @return true if successful, false if the value was not enqueued
+     * likely due to reaching the queue capacity)
+     */
+    boolean offer(@NonNull T value);
 
-    boolean offer(T v1, T v2);
+    /**
+     * Atomically enqueue two values.
+     * @param v1 the first value to enqueue, not null
+     * @param v2 the second value to enqueue, not null
+     * @return true if successful, false if the value was not enqueued
+     * likely due to reaching the queue capacity)
+     */
+    boolean offer(@NonNull T v1, @NonNull T v2);
 
     /**
-     * @return null to indicate an empty queue
+     * Tries to dequeue a value (non-null) or returns null if
+     * the queue is empty.
+     * <p>
+     * If the producer uses {@link #offer(Object, Object)} and
+     * when polling in pairs, if the first poll() returns a non-null
+     * item, the second poll() is guaranteed to return a non-null item
+     * as well.
+     * @return the item or null to indicate an empty queue
+     * @throws Exception if some pre-processing of the dequeued
+     * item (usually through fused functions) throws.
      */
     @Nullable
     T poll() throws Exception;
 
+    /**
+     * Returns true if the queue is empty.
+     * <p>
+     * Note however that due to potential fused functions in {@link #poll()}
+     * it is possible this method returns false but then poll() returns null
+     * because the fused function swallowed the available item(s).
+     * @return true if the queue is empty
+     */
     boolean isEmpty();
 
+    /**
+     * Removes all enqueued items from this queue.
+     */
     void clear();
 }