2.x: cleanup 9/12-1, more Maybe operators, more source code checking (#4530)

Author: akarnokd

src/main/java/io/reactivex/Completable.java

@@ -136,6 +136,9 @@ public static Completable concat(Iterable<? extends CompletableSource> sources)
     /**
      * Returns a Completable which completes only when all sources complete, one after another.
      * <dl>
+     *  <dt><b>Backpressure:</b><dt>
+     *  <dd>The returned {@code Completable} honors the backpressure of the downstream consumer
+     *  and expects the other {@code Publisher} to honor it as well.</dd>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
@@ -152,6 +155,9 @@ public static Completable concat(Publisher<? extends CompletableSource> sources)
     /**
      * Returns a Completable which completes only when all sources complete, one after another.
      * <dl>
+     *  <dt><b>Backpressure:</b><dt>
+     *  <dd>The returned {@code Completable} honors the backpressure of the downstream consumer
+     *  and expects the other {@code Publisher} to honor it as well.</dd>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
@@ -197,9 +203,9 @@ public static Completable concat(Publisher<? extends CompletableSource> sources,
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code create} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
-     * @param source the emitter that is called when a Subscriber subscribes to the returned {@code Flowable}
+     * @param source the emitter that is called when a CompletableObserver subscribes to the returned {@code Completable}
      * @return the new Completable instance
-     * @see FlowableOnSubscribe
+     * @see CompletableOnSubscribe
      * @see Cancellable
      */
     @SchedulerSupport(SchedulerSupport.NONE)
@@ -249,7 +255,7 @@ public static Completable defer(final Callable<? extends CompletableSource> comp
      * Creates a Completable which calls the given error supplier for each subscriber
      * and emits its returned Throwable.
      * <p>
-     * If the errorSupplier returns null, the child CompletableSubscribers will receive a
+     * If the errorSupplier returns null, the child CompletableObservers will receive a
      * NullPointerException.
      * <dl>
      *  <dt><b>Scheduler:</b></dt>
@@ -354,6 +360,9 @@ public static <T> Completable fromObservable(final ObservableSource<T> observabl
      * Returns a Completable instance that subscribes to the given publisher, ignores all values and
      * emits only the terminal event.
      * <dl>
+     *  <dt><b>Backpressure:</b><dt>
+     *  <dd>The returned {@code Completable} honors the backpressure of the downstream consumer
+     *  and expects the other {@code Publisher} to honor it as well.</dd>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code fromPublisher} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
@@ -431,6 +440,9 @@ public static Completable merge(Iterable<? extends CompletableSource> sources) {
      * Returns a Completable instance that subscribes to all sources at once and
      * completes only when all source Completables complete or one of them emits an error.
      * <dl>
+     *  <dt><b>Backpressure:</b><dt>
+     *  <dd>The returned {@code Completable} honors the backpressure of the downstream consumer
+     *  and expects the other {@code Publisher} to honor it as well.</dd>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
@@ -448,6 +460,9 @@ public static Completable merge(Publisher<? extends CompletableSource> sources)
      * Returns a Completable instance that keeps subscriptions to a limited number of sources at once and
      * completes only when all source Completables complete or one of them emits an error.
      * <dl>
+     *  <dt><b>Backpressure:</b><dt>
+     *  <dd>The returned {@code Completable} honors the backpressure of the downstream consumer
+     *  and expects the other {@code Publisher} to honor it as well.</dd>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
@@ -468,6 +483,9 @@ public static Completable merge(Publisher<? extends CompletableSource> sources,
      * completes only when all source Completables terminate in one way or another, combining any exceptions
      * thrown by either the sources Observable or the inner Completable instances.
      * <dl>
+     *  <dt><b>Backpressure:</b><dt>
+     *  <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer
+     *  and expects the other {@code Publisher} to honor it as well.
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code merge0} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
@@ -528,6 +546,9 @@ public static Completable mergeDelayError(Iterable<? extends CompletableSource>
      * any error emitted by either the sources observable or any of the inner Completables until all of
      * them terminate in a way or another.
      * <dl>
+     *  <dt><b>Backpressure:</b><dt>
+     *  <dd>The returned {@code Completable} honors the backpressure of the downstream consumer
+     *  and expects the other {@code Publisher} to honor it as well.</dd>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
@@ -547,6 +568,9 @@ public static Completable mergeDelayError(Publisher<? extends CompletableSource>
      * observable or any of the inner Completables until all of
      * them terminate in a way or another.
      * <dl>
+     *  <dt><b>Backpressure:</b><dt>
+     *  <dd>The returned {@code Completable} honors the backpressure of the downstream consumer
+     *  and expects the other {@code Publisher} to honor it as well.</dd>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
@@ -732,11 +756,14 @@ public final <T> Observable<T> andThen(ObservableSource<T> next) {
     }
 
     /**
-     * Returns an Flowable which will subscribe to this Completable and once that is completed then
+     * Returns a Flowable which will subscribe to this Completable and once that is completed then
      * will subscribe to the {@code next} Flowable. An error event from this Completable will be
      * propagated to the downstream subscriber and will result in skipping the subscription of the
      * Observable.
      * <dl>
+     *  <dt><b>Backpressure:</b><dt>
+     *  <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer
+     *  and expects the other {@code Publisher} to honor it as well.
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code andThen} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
@@ -1387,6 +1414,9 @@ public final <T> Observable<T> startWith(Observable<T> other) {
      * Returns an Observable which first delivers the events
      * of the other Observable then runs this Completable.
      * <dl>
+     *  <dt><b>Backpressure:</b><dt>
+     *  <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer
+     *  and expects the other {@code Publisher} to honor it as well.
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
@@ -1659,6 +1689,8 @@ public final <U> U to(Function<? super Completable, U> converter) {
      * Returns an Observable which when subscribed to subscribes to this Completable and
      * relays the terminal events to the subscriber.
      * <dl>
+     *  <dt><b>Backpressure:</b><dt>
+     *  <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code toFlowable} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>

src/main/java/io/reactivex/Flowable.java

@@ -408,7 +408,7 @@ public static <T, R> Flowable<R> combineLatestDelayError(Function<? super Object
 
     /**
      * Combines a collection of source Publishers by emitting an item that aggregates the latest values of each of
-     * the source ObservableSources each time an item is received from any of the source Publisher, where this
+     * the source Publishers each time an item is received from any of the source Publisher, where this
      * aggregation is defined by a specified function and delays any error from the sources until
      * all source Publishers terminate.
      * <p>
@@ -1274,7 +1274,7 @@ public static <T> Flowable<T> concatArrayDelayError(Publisher<? extends T>... so
      * in order, each one after the previous one completes.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
-     *  <dd><dd>The operator honors backpressure from downstream. The {@code Publisher}
+     *  <dd>The operator honors backpressure from downstream. The {@code Publisher}
      *  sources are expected to honor backpressure as well.
      *  If any of the source {@code Publisher}s violate this, the operator will signal a
      *  {@code MissingBackpressureException}.</dd>
@@ -1300,7 +1300,7 @@ public static <T> Flowable<T> concatArrayEager(Publisher<? extends T>... sources
      * in order, each one after the previous one completes.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
-     *  <dd><dd>The operator honors backpressure from downstream. The {@code Publisher}
+     *  <dd>The operator honors backpressure from downstream. The {@code Publisher}
      *  sources are expected to honor backpressure as well.
      *  If any of the source {@code Publisher}s violate this, the operator will signal a
      *  {@code MissingBackpressureException}.</dd>
@@ -1564,7 +1564,7 @@ public static <T> Flowable<T> create(FlowableOnSubscribe<T> source, FlowableEmit
      * <img width="640" height="340" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/defer.png" alt="">
      * <p>
      * The defer Subscriber allows you to defer or delay emitting items from a Publisher until such time as an
-     * Subscriber subscribes to the Publisher. This allows an {@link Subscriber} to easily obtain updates or a
+     * Subscriber subscribes to the Publisher. This allows a {@link Subscriber} to easily obtain updates or a
      * refreshed version of the sequence.
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
@@ -1616,7 +1616,7 @@ public static <T> Flowable<T> empty() {
     }
 
     /**
-     * Returns a Flowable that invokes an {@link Subscriber}'s {@link Subscriber#onError onError} method when the
+     * Returns a Flowable that invokes a {@link Subscriber}'s {@link Subscriber#onError onError} method when the
      * Subscriber subscribes to it.
      * <p>
      * <img width="640" height="190" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/error.png" alt="">
@@ -1643,7 +1643,7 @@ public static <T> Flowable<T> error(Callable<? extends Throwable> supplier) {
     }
 
     /**
-     * Returns a Flowable that invokes an {@link Subscriber}'s {@link Subscriber#onError onError} method when the
+     * Returns a Flowable that invokes a {@link Subscriber}'s {@link Subscriber#onError onError} method when the
      * Subscriber subscribes to it.
      * <p>
      * <img width="640" height="190" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/error.png" alt="">
@@ -1702,12 +1702,12 @@ public static <T> Flowable<T> fromArray(T... items) {
     }
 
     /**
-     * Returns a Flowable that, when an Subscriber subscribes to it, invokes a function you specify and then
+     * Returns a Flowable that, when a Subscriber subscribes to it, invokes a function you specify and then
      * emits the value returned from that function.
      * <p>
      * <img width="640" height="195" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/fromCallable.png" alt="">
      * <p>
-     * This allows you to defer the execution of the function you specify until an Subscriber subscribes to the
+     * This allows you to defer the execution of the function you specify until a Subscriber subscribes to the
      * Publisher. That is to say, it makes the function "lazy."
      * <dl>
      *   <dt><b>Backpressure:</b></dt>
@@ -1718,7 +1718,7 @@ public static <T> Flowable<T> fromArray(T... items) {
      *
      * @param supplier
      *         a function, the execution of which should be deferred; {@code fromCallable} will invoke this
-     *         function only when an Subscriber subscribes to the Publisher that {@code fromCallable} returns
+     *         function only when a Subscriber subscribes to the Publisher that {@code fromCallable} returns
      * @param <T>
      *         the type of the item emitted by the Publisher
      * @return a Flowable whose {@link Subscriber}s' subscriptions trigger an invocation of the given function
@@ -2151,7 +2151,7 @@ public static Flowable<Long> interval(long initialDelay, long period, TimeUnit u
      * <dl>
      *  <dt><b>Backpressure:</b></dt>
      *  <dd>The operator signals a {@code MissingBackpressureException} if the downstream
-     *  is not ready to receive the next value.
+     *  is not ready to receive the next value.</dd>
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code interval} operates by default on the {@code computation} {@link Scheduler}.</dd>
      * </dl>
@@ -3007,7 +3007,7 @@ public static <T> Flowable<T> merge(
     }
 
     /**
-     * Flattens an Iterable of Publishers into one Publisher, in a way that allows an Subscriber to receive all
+     * Flattens an Iterable of Publishers into one Publisher, in a way that allows a Subscriber to receive all
      * successfully emitted items from each of the source Publishers without being interrupted by an error
      * notification from one of them.
      * <p>
@@ -3043,7 +3043,7 @@ public static <T> Flowable<T> mergeDelayError(Iterable<? extends Publisher<? ext
 
 
     /**
-     * Flattens an Iterable of Publishers into one Publisher, in a way that allows an Subscriber to receive all
+     * Flattens an Iterable of Publishers into one Publisher, in a way that allows a Subscriber to receive all
      * successfully emitted items from each of the source Publishers without being interrupted by an error
      * notification from one of them, while limiting the number of concurrent subscriptions to these Publishers.
      * <p>
@@ -3082,7 +3082,7 @@ public static <T> Flowable<T> mergeDelayError(Iterable<? extends Publisher<? ext
     }
 
     /**
-     * Flattens an array of Publishers into one Publisher, in a way that allows an Subscriber to receive all
+     * Flattens an array of Publishers into one Publisher, in a way that allows a Subscriber to receive all
      * successfully emitted items from each of the source Publishers without being interrupted by an error
      * notification from one of them, while limiting the number of concurrent subscriptions to these Publishers.
      * <p>
@@ -3121,7 +3121,7 @@ public static <T> Flowable<T> mergeArrayDelayError(int maxConcurrency, int buffe
     }
 
     /**
-     * Flattens an Iterable of Publishers into one Publisher, in a way that allows an Subscriber to receive all
+     * Flattens an Iterable of Publishers into one Publisher, in a way that allows a Subscriber to receive all
      * successfully emitted items from each of the source Publishers without being interrupted by an error
      * notification from one of them, while limiting the number of concurrent subscriptions to these Publishers.
      * <p>
@@ -3158,7 +3158,7 @@ public static <T> Flowable<T> mergeDelayError(Iterable<? extends Publisher<? ext
     }
 
     /**
-     * Flattens a Publisher that emits Publishers into one Publisher, in a way that allows an Subscriber to
+     * Flattens a Publisher that emits Publishers into one Publisher, in a way that allows a Subscriber to
      * receive all successfully emitted items from all of the source Publishers without being interrupted by
      * an error notification from one of them.
      * <p>
@@ -3193,7 +3193,7 @@ public static <T> Flowable<T> mergeDelayError(Publisher<? extends Publisher<? ex
     }
 
     /**
-     * Flattens a Publisher that emits Publishers into one Publisher, in a way that allows an Subscriber to
+     * Flattens a Publisher that emits Publishers into one Publisher, in a way that allows a Subscriber to
      * receive all successfully emitted items from all of the source Publishers without being interrupted by
      * an error notification from one of them, while limiting the
      * number of concurrent subscriptions to these Publishers.
@@ -3232,7 +3232,7 @@ public static <T> Flowable<T> mergeDelayError(Publisher<? extends Publisher<? ex
     }
 
     /**
-     * Flattens an array of Publishers into one Flowable, in a way that allows an Subscriber to receive all
+     * Flattens an array of Publishers into one Flowable, in a way that allows a Subscriber to receive all
      * successfully emitted items from each of the source Publishers without being interrupted by an error
      * notification from one of them.
      * <p>
@@ -3267,7 +3267,7 @@ public static <T> Flowable<T> mergeArrayDelayError(Publisher<? extends T>... sou
     }
 
     /**
-     * Flattens two Publishers into one Publisher, in a way that allows an Subscriber to receive all
+     * Flattens two Publishers into one Publisher, in a way that allows a Subscriber to receive all
      * successfully emitted items from each of the source Publishers without being interrupted by an error
      * notification from one of them.
      * <p>
@@ -3305,7 +3305,7 @@ public static <T> Flowable<T> mergeDelayError(Publisher<? extends T> source1, Pu
     }
 
     /**
-     * Flattens three Publishers into one Publisher, in a way that allows an Subscriber to receive all
+     * Flattens three Publishers into one Publisher, in a way that allows a Subscriber to receive all
      * successfully emitted items from all of the source Publishers without being interrupted by an error
      * notification from one of them.
      * <p>
@@ -3348,7 +3348,7 @@ public static <T> Flowable<T> mergeDelayError(Publisher<? extends T> source1, Pu
 
 
     /**
-     * Flattens four Publishers into one Publisher, in a way that allows an Subscriber to receive all
+     * Flattens four Publishers into one Publisher, in a way that allows a Subscriber to receive all
      * successfully emitted items from all of the source Publishers without being interrupted by an error
      * notification from one of them.
      * <p>
@@ -3395,7 +3395,7 @@ public static <T> Flowable<T> mergeDelayError(
     }
 
     /**
-     * Returns a Flowable that never sends any items or notifications to an {@link Subscriber}.
+     * Returns a Flowable that never sends any items or notifications to a {@link Subscriber}.
      * <p>
      * <img width="640" height="185" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/never.png" alt="">
      * <p>
@@ -3409,7 +3409,7 @@ public static <T> Flowable<T> mergeDelayError(
      *
      * @param <T>
      *            the type of items (not) emitted by the Publisher
-     * @return a Flowable that never emits any items or sends any notifications to an {@link Subscriber}
+     * @return a Flowable that never emits any items or sends any notifications to a {@link Subscriber}
      * @see <a href="http://reactivex.io/documentation/operators/empty-never-throw.html">ReactiveX operators documentation: Never</a>
      */
     @BackpressureSupport(BackpressureKind.PASS_THROUGH)