diff --git a/src/main/java/io/reactivex/rxjava3/core/Completable.java b/src/main/java/io/reactivex/rxjava3/core/Completable.java index 1f24e413f5..a51bb7399f 100644 --- a/src/main/java/io/reactivex/rxjava3/core/Completable.java +++ b/src/main/java/io/reactivex/rxjava3/core/Completable.java @@ -336,6 +336,7 @@ public static Completable create(@NonNull CompletableOnSubscribe source) { * when the {@code Completable} is subscribed to. * @return the created {@code Completable} instance * @throws NullPointerException if {@code source} is {@code null} + * @throws IllegalArgumentException if {@code source} is a {@code Completable} */ @CheckReturnValue @NonNull @@ -364,7 +365,7 @@ public static Completable unsafeCreate(@NonNull CompletableSource source) { @NonNull @SchedulerSupport(SchedulerSupport.NONE) public static Completable defer(@NonNull Supplier completableSupplier) { - Objects.requireNonNull(completableSupplier, "completableSupplier"); + Objects.requireNonNull(completableSupplier, "completableSupplier is null"); return RxJavaPlugins.onAssembly(new CompletableDefer(completableSupplier)); } diff --git a/src/main/java/io/reactivex/rxjava3/core/Flowable.java b/src/main/java/io/reactivex/rxjava3/core/Flowable.java index b5135bf356..f11415e0de 100644 --- a/src/main/java/io/reactivex/rxjava3/core/Flowable.java +++ b/src/main/java/io/reactivex/rxjava3/core/Flowable.java @@ -1352,7 +1352,7 @@ public static Flowable concat( * @param sources the array of source {@code Publisher}s * @param the common base value type * @return the new {@code Publisher} instance - * @throws NullPointerException if sources is {@code null} + * @throws NullPointerException if {@code sources} is {@code null} */ @CheckReturnValue @BackpressureSupport(BackpressureKind.FULL) @@ -1360,6 +1360,7 @@ public static Flowable concat( @SafeVarargs @NonNull public static Flowable concatArray(@NonNull Publisher... sources) { + Objects.requireNonNull(sources, "sources is null"); if (sources.length == 0) { return empty(); } else @@ -1386,7 +1387,7 @@ public static Flowable concatArray(@NonNull Publisher... sou * @param sources the array of source {@code Publisher}s * @param the common base value type * @return the new {@code Flowable} instance - * @throws NullPointerException if sources is {@code null} + * @throws NullPointerException if {@code sources} is {@code null} */ @CheckReturnValue @BackpressureSupport(BackpressureKind.FULL) @@ -1394,6 +1395,7 @@ public static Flowable concatArray(@NonNull Publisher... sou @SafeVarargs @NonNull public static Flowable concatArrayDelayError(@NonNull Publisher... sources) { + Objects.requireNonNull(sources, "sources is null"); if (sources.length == 0) { return empty(); } else @@ -1925,7 +1927,7 @@ public static Flowable error(@NonNull Throwable throwable) { } /** - * Converts an Array into a {@link Publisher} that emits the items in the Array. + * Converts an array into a {@link Publisher} that emits the items in the array. *

* *

@@ -1939,8 +1941,8 @@ public static Flowable error(@NonNull Throwable throwable) { * @param items * the array of elements * @param - * the type of items in the Array and the type of items to be emitted by the resulting {@code Publisher} - * @return a {@code Flowable} that emits each item in the source Array + * the type of items in the array and the type of items to be emitted by the resulting {@code Publisher} + * @return a {@code Flowable} that emits each item in the source array * @see ReactiveX operators documentation: From */ @CheckReturnValue @@ -1981,7 +1983,7 @@ public static Flowable error(@NonNull Throwable throwable) { * *
* - * @param supplier + * @param callable * a function, the execution of which should be deferred; {@code fromCallable} will invoke this * function only when a {@code Subscriber} subscribes to the {@code Publisher} that {@code fromCallable} returns * @param @@ -1995,9 +1997,9 @@ public static Flowable error(@NonNull Throwable throwable) { @NonNull @BackpressureSupport(BackpressureKind.FULL) @SchedulerSupport(SchedulerSupport.NONE) - public static <@NonNull T> Flowable fromCallable(@NonNull Callable supplier) { - Objects.requireNonNull(supplier, "supplier is null"); - return RxJavaPlugins.onAssembly(new FlowableFromCallable<>(supplier)); + public static <@NonNull T> Flowable fromCallable(@NonNull Callable callable) { + Objects.requireNonNull(callable, "callable is null"); + return RxJavaPlugins.onAssembly(new FlowableFromCallable<>(callable)); } /** @@ -2005,11 +2007,10 @@ public static Flowable error(@NonNull Throwable throwable) { *

* *

- * You can convert any object that supports the {@code Future} interface into a {@code Publisher} that emits the - * return value of the {@link Future#get} method of that object by passing the object into the {@code from} - * method. - *

- * Important note: This {@code Publisher} is blocking on the thread it gets subscribed on; you cannot cancel it. + * The operator calls {@link Future#get()}, which is a blocking method, on the subscription thread. + * It is recommended applying {@link #subscribeOn(Scheduler)} to move this blocking wait to a + * background thread, and if the {@link Scheduler} supports it, interrupt the wait when the flow + * is disposed. *

* Also note that this operator will consume a {@link CompletionStage}-based {@code Future} subclass (such as * {@link CompletableFuture}) in a blocking manner as well. Use the {@link #fromCompletionStage(CompletionStage)} @@ -2021,7 +2022,7 @@ public static Flowable error(@NonNull Throwable throwable) { *

Backpressure:
*
The operator honors backpressure from downstream.
*
Scheduler:
- *
{@code fromFuture} does not operate by default on a particular {@link Scheduler}.
+ *
{@code fromFuture} does not operate by default on a particular {@code Scheduler}.
* * * @param future @@ -2047,15 +2048,14 @@ public static Flowable error(@NonNull Throwable throwable) { *

* *

- * You can convert any object that supports the {@code Future} interface into a {@code Publisher} that emits the - * return value of the {@link Future#get} method of that object by passing the object into the {@code fromFuture} - * method. + * The operator calls {@link Future#get(long, TimeUnit)}, which is a blocking method, on the subscription thread. + * It is recommended applying {@link #subscribeOn(Scheduler)} to move this blocking wait to a + * background thread, and if the {@link Scheduler} supports it, interrupt the wait when the flow + * is disposed. *

* Unlike 1.x, canceling the {@code Flowable} won't cancel the future. If necessary, one can use composition to achieve the * cancellation effect: {@code futurePublisher.doOnCancel(() -> future.cancel(true));}. *

- * Important note: This {@code Publisher} is blocking on the thread it gets subscribed on; you cannot cancel it. - *

* Also note that this operator will consume a {@link CompletionStage}-based {@code Future} subclass (such as * {@link CompletableFuture}) in a blocking manner as well. Use the {@link #fromCompletionStage(CompletionStage)} * operator to convert and consume such sources in a non-blocking fashion instead. @@ -2063,7 +2063,7 @@ public static Flowable error(@NonNull Throwable throwable) { *

Backpressure:
*
The operator honors backpressure from downstream.
*
Scheduler:
- *
{@code fromFuture} does not operate by default on a particular {@link Scheduler}.
+ *
{@code fromFuture} does not operate by default on a particular {@code Scheduler}.
* * * @param future @@ -2540,6 +2540,9 @@ public static Flowable intervalRange(long start, long count, long initialD * @param unit the unit of measure of the {@code initialDelay} and {@code period} amounts * @param scheduler the target {@code Scheduler} where the values and terminal signals will be emitted * @return the new {@code Flowable} instance + * @throws IllegalArgumentException + * if {@code count} is less than zero, or if {@code start} + {@code count} − 1 exceeds + * {@link Long#MAX_VALUE} */ @CheckReturnValue @NonNull @@ -3042,7 +3045,7 @@ public static Flowable merge(@NonNull Iterable * @@ -3288,7 +3291,7 @@ public static Flowable merge(@NonNull Publisher * *

@@ -4401,7 +4404,9 @@ public static Flowable unsafeCreate(@NonNull Publisher onSubscribe) { } /** - * Constructs a {@link Publisher} that creates a dependent resource object which is disposed of on cancellation. + * Constructs a {@code Flowable} that creates a dependent resource object, a {@link Publisher} with + * that resource and calls the provided {@code resourceDisposer} function if this inner source terminates or the + * downstream cancels the flow. *

* *

@@ -4435,11 +4440,9 @@ public static Flowable using( } /** - * Constructs a {@link Publisher} that creates a dependent resource object which is disposed of just before - * termination if you have set {@code disposeEagerly} to {@code true} and cancellation does not occur - * before termination. Otherwise, resource disposal will occur on cancellation. Eager disposal is - * particularly appropriate for a synchronous {@code Publisher} that reuses resources. {@code disposeAction} will - * only be called once per subscription. + * Constructs a {@code Flowable} that creates a dependent resource object, a {@link Publisher} with + * that resource and calls the provided {@code resourceDisposer} function if this inner source terminates or the + * downstream disposes the flow; doing it before these end-states have been reached if {@code eager == true}, after otherwise. *

* *

@@ -4459,7 +4462,7 @@ public static Flowable using( * @param resourceDisposer * the function that will dispose of the resource * @param eager - * If {@code true} then resource disposal will happen either on a {@code cancel()} call before the upstream is disposed + * If {@code true}, the resource disposal will happen either on a {@code cancel()} call before the upstream is disposed * or just before the emission of a terminal event ({@code onComplete} or {@code onError}). * If {@code false} the resource disposal will happen either on a {@code cancel()} call after the upstream is disposed * or just after the emission of a terminal event ({@code onComplete} or {@code onError}). @@ -5383,6 +5386,8 @@ public static Flowable zip( * @param bufferSize * the number of elements to prefetch from each source {@code Publisher} * @return a {@code Flowable} that emits the zipped results + * @throws NullPointerException if {@code sources} or {@code zipper} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Zip */ @CheckReturnValue @@ -5392,6 +5397,7 @@ public static Flowable zip( @SafeVarargs public static Flowable zipArray(@NonNull Function zipper, boolean delayError, int bufferSize, @NonNull Publisher... sources) { + Objects.requireNonNull(sources, "sources is null"); if (sources.length == 0) { return empty(); } @@ -5628,6 +5634,8 @@ public final void blockingForEach(@NonNull Consumer onNext) { * the {@code Consumer} to invoke for each item emitted by the {@code Flowable} * @param bufferSize * the number of items to prefetch upfront, then 75% of it after 75% received + * @throws NullPointerException if {@code onNext} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @throws RuntimeException * if an error occurs; {@code Error}s and {@code RuntimeException}s are rethrown * as they are, checked {@code Exception}s are wrapped into {@code RuntimeException}s @@ -5637,6 +5645,7 @@ public final void blockingForEach(@NonNull Consumer onNext) { @BackpressureSupport(BackpressureKind.FULL) @SchedulerSupport(SchedulerSupport.NONE) public final void blockingForEach(@NonNull Consumer onNext, int bufferSize) { + Objects.requireNonNull(onNext, "onNext is null"); Iterator it = blockingIterable(bufferSize).iterator(); while (it.hasNext()) { try { @@ -6143,11 +6152,13 @@ public final void blockingSubscribe(@NonNull Consumer onNext, @NonNul *
* The cancellation and backpressure is composed through. * @param subscriber the subscriber to forward events and calls to in the current thread + * @throws NullPointerException if {@code subscriber} is {@code null} * @since 2.0 */ @BackpressureSupport(BackpressureKind.SPECIAL) @SchedulerSupport(SchedulerSupport.NONE) public final void blockingSubscribe(@NonNull Subscriber subscriber) { + Objects.requireNonNull(subscriber, "subscriber is null"); FlowableBlockingSubscribe.subscribe(this, subscriber); } @@ -6824,7 +6835,7 @@ public final > Flowable buffer(@NonNull Pu * that return a {@link ConnectableFlowable} require an explicit call to {@link ConnectableFlowable#connect()}. *

* Note: You sacrifice the ability to cancel the origin when you use the {@code cache} - * {@code Subscriber} so be careful not to use this {@code Subscriber} on {@code Publisher}s that emit an infinite or very large number + * operator so be careful not to use this operator on {@code Publisher}s that emit an infinite or very large number * of items that will use up memory. * A possible workaround is to apply {@link #takeUntil(Publisher)} with a predicate or * another source before (and perhaps after) the application of {@code cache()}. @@ -6860,6 +6871,8 @@ public final > Flowable buffer(@NonNull Pu * @return a {@code Flowable} that, when first subscribed to, caches all of its items and notifications for the * benefit of subsequent subscribers * @see ReactiveX operators documentation: Replay + * @see #takeUntil(Predicate) + * @see #takeUntil(Publisher) */ @CheckReturnValue @BackpressureSupport(BackpressureKind.FULL) @@ -6883,7 +6896,7 @@ public final Flowable cache() { * that return a {@link ConnectableFlowable} require an explicit call to {@link ConnectableFlowable#connect()}. *

* Note: You sacrifice the ability to cancel the origin when you use the {@code cache} - * {@code Subscriber} so be careful not to use this {@code Subscriber} on {@code Publisher}s that emit an infinite or very large number + * operator so be careful not to use this operator on {@code Publisher}s that emit an infinite or very large number * of items that will use up memory. * A possible workaround is to apply {@link #takeUntil(Publisher)} with a predicate or * another source before (and perhaps after) the application of {@code cacheWithInitialCapacity()}. @@ -6923,6 +6936,8 @@ public final Flowable cache() { * @return a {@code Flowable} that, when first subscribed to, caches all of its items and notifications for the * benefit of subsequent subscribers * @see ReactiveX operators documentation: Replay + * @see #takeUntil(Predicate) + * @see #takeUntil(Publisher) */ @CheckReturnValue @BackpressureSupport(BackpressureKind.FULL) @@ -7201,7 +7216,7 @@ public final Flowable concatMap(@NonNull Function Flowable concatMap(@NonNull Function> mapper, int prefetch, @NonNull Scheduler scheduler) { Objects.requireNonNull(mapper, "mapper is null"); ObjectHelper.verifyPositive(prefetch, "prefetch"); - Objects.requireNonNull(scheduler, "scheduler"); + Objects.requireNonNull(scheduler, "scheduler is null"); return RxJavaPlugins.onAssembly(new FlowableConcatMapScheduler<>(this, mapper, prefetch, ErrorMode.IMMEDIATE, scheduler)); } @@ -9412,6 +9427,7 @@ public final Flowable doOnTerminate(@NonNull Action onTerminate) { * the zero-based index of the item to retrieve * @return a {@code Maybe} that emits a single item: the item at the specified position in the sequence of * those emitted by the source {@code Publisher} + * @throws IndexOutOfBoundsException if {@code index} is negative * @see ReactiveX operators documentation: ElementAt */ @CheckReturnValue @@ -9444,7 +9460,7 @@ public final Maybe elementAt(long index) { * @return a {@code Single} that emits the item at the specified position in the sequence emitted by the source * {@code Publisher}, or the default item if that index is outside the bounds of the source sequence * @throws IndexOutOfBoundsException - * if {@code index} is less than 0 + * if {@code index} is negative * @see ReactiveX operators documentation: ElementAt */ @CheckReturnValue @@ -10142,26 +10158,25 @@ public final Completable flatMapCompletable(@NonNull Function * *

*
Backpressure:
- *
The operator honors backpressure from downstream. The source {@code Publisher}s is - * expected to honor backpressure as well. If the source {@code Publisher} violates the rule, the operator will + *
The operator honors backpressure from downstream. The current {@code Flowable}s is + * expected to honor backpressure as well. If the current {@code Flowable} violates the rule, the operator will * signal a {@link MissingBackpressureException}.
*
Scheduler:
*
{@code flatMapIterable} does not operate by default on a particular {@link Scheduler}.
*
* * @param - * the type of item emitted by the resulting {@code Iterable} + * the output type and the element type of the {@code Iterable}s * @param mapper * a function that returns an {@code Iterable} sequence of values for when given an item emitted by the - * source {@code Publisher} - * @return a {@code Flowable} that emits the results of merging the items emitted by the source {@code Publisher} with - * the values in the {@code Iterable}s corresponding to those items, as generated by {@code collectionSelector} + * current {@code Flowable} + * @return the new {@code Flowable} instance * @see ReactiveX operators documentation: FlatMap */ @CheckReturnValue @@ -10173,14 +10188,14 @@ public final Flowable flatMapIterable(@NonNull Function * *
*
Backpressure:
- *
The operator honors backpressure from downstream. The source {@code Publisher}s is - * expected to honor backpressure as well. If the source {@code Publisher} violates the rule, the operator will + *
The operator honors backpressure from downstream. The current {@code Flowable}s is + * expected to honor backpressure as well. If the current {@code Flowable} violates the rule, the operator will * signal a {@link MissingBackpressureException}.
*
Scheduler:
*
{@code flatMapIterable} does not operate by default on a particular {@link Scheduler}.
@@ -10190,11 +10205,10 @@ public final Flowable flatMapIterable(@NonNull FunctionReactiveX operators documentation: FlatMap */ @CheckReturnValue @@ -10208,30 +10222,32 @@ public final Flowable flatMapIterable(@NonNull Function * *
*
Backpressure:
- *
The operator honors backpressure from downstream and the source {@code Publisher}s is - * consumed in an unbounded manner (i.e., no backpressure is applied to it).
+ *
The operator honors backpressure from downstream and the current {@code Flowable}s is + * consumed in a bounded manner (requesting {@link #bufferSize()} items upfront, then 75% of it after 75% received).
*
Scheduler:
*
{@code flatMapIterable} does not operate by default on a particular {@link Scheduler}.
*
* * @param - * the collection element type + * the element type of the {@code Iterable}s * @param - * the type of item emitted by the resulting {@code Iterable} + * the output type as determined by the {@code resultSelector} function * @param mapper - * a function that returns an {@code Iterable} sequence of values for each item emitted by the source - * {@code Publisher} + * a function that returns an {@code Iterable} sequence of values for each item emitted by the current + * {@code Flowable} * @param resultSelector - * a function that returns an item based on the item emitted by the source {@code Publisher} and the + * a function that returns an item based on the item emitted by the current {@code Flowable} and the * {@code Iterable} returned for that item by the {@code collectionSelector} - * @return a {@code Flowable} that emits the items returned by {@code resultSelector} for each item in the source - * {@code Publisher} + * @return a {@code Flowable} that emits the items returned by {@code resultSelector} for each item in the current + * {@code Flowable} * @see ReactiveX operators documentation: FlatMap */ @CheckReturnValue @@ -10246,15 +10262,16 @@ public final Flowable flatMapIterable(@NonNull Function * *
*
Backpressure:
- *
The operator honors backpressure from downstream. The source {@code Publisher}s is - * expected to honor backpressure as well. If the source {@code Publisher} violates the rule, the operator will + *
The operator honors backpressure from downstream. The current {@code Flowable}s is + * expected to honor backpressure as well. If the current {@code Flowable} violates the rule, the operator will * signal a {@link MissingBackpressureException}.
*
Scheduler:
*
{@code flatMapIterable} does not operate by default on a particular {@link Scheduler}.
@@ -10263,17 +10280,16 @@ public final Flowable flatMapIterable(@NonNull Function * the element type of the inner {@code Iterable} sequences * @param - * the type of item emitted by the resulting {@code Publisher} + * the type of item emitted by the resulting {@code Flowable} * @param mapper * a function that returns an {@code Iterable} sequence of values for when given an item emitted by the - * source {@code Publisher} + * current {@code Flowable} * @param resultSelector - * a function that returns an item based on the item emitted by the source {@code Publisher} and the + * a function that returns an item based on the item emitted by the current {@code Flowable} and the * {@code Iterable} returned for that item by the {@code collectionSelector} * @param prefetch * the number of elements to prefetch from the current {@code Flowable} - * @return a {@code Flowable} that emits the results of merging the items emitted by the source {@code Publisher} with - * the values in the {@code Iterable}s corresponding to those items, as generated by {@code collectionSelector} + * @return the new {@code Flowable} instance * @see ReactiveX operators documentation: FlatMap * @since 2.0 */ @@ -11185,7 +11201,7 @@ public final Maybe lastElement() { @BackpressureSupport(BackpressureKind.UNBOUNDED_IN) @SchedulerSupport(SchedulerSupport.NONE) public final Single last(@NonNull T defaultItem) { - Objects.requireNonNull(defaultItem, "defaultItem"); + Objects.requireNonNull(defaultItem, "defaultItem is null"); return RxJavaPlugins.onAssembly(new FlowableLastSingle<>(this, defaultItem)); } @@ -11620,7 +11636,7 @@ public final Flowable observeOn(@NonNull Scheduler scheduler) { * the {@code Scheduler} to notify {@link Subscriber}s on * @param delayError * indicates if the {@code onError} notification may not cut ahead of {@code onNext} notification on the other side of the - * scheduling boundary. If {@code true} a sequence ending in {@code onError} will be replayed in the same order as was received + * scheduling boundary. If {@code true}, a sequence ending in {@code onError} will be replayed in the same order as was received * from upstream * @return the source {@code Publisher} modified so that its {@code Subscriber}s are notified on the specified * {@code Scheduler} @@ -11672,7 +11688,7 @@ public final Flowable observeOn(@NonNull Scheduler scheduler, boolean delayEr * the {@code Scheduler} to notify {@link Subscriber}s on * @param delayError * indicates if the {@code onError} notification may not cut ahead of {@code onNext} notification on the other side of the - * scheduling boundary. If {@code true} a sequence ending in {@code onError} will be replayed in the same order as was received + * scheduling boundary. If {@code true}, a sequence ending in {@code onError} will be replayed in the same order as was received * from upstream * @param bufferSize the size of the buffer. * @return the source {@code Publisher} modified so that its {@code Subscriber}s are notified on the specified @@ -11940,13 +11956,13 @@ public final Flowable onBackpressureBuffer(int capacity, @NonNull Action onOv * by {@code overflowStrategy} if the buffer capacity is exceeded. * *
    - *
  • {@code BackpressureOverflow.Strategy.ON_OVERFLOW_ERROR} (default) will call {@code onError} dropping all undelivered items, + *
  • {@link BackpressureOverflowStrategy#ERROR} (default) will call {@code onError} dropping all undelivered items, * canceling the source, and notifying the producer with {@code onOverflow}.
    • - *
  • {@code BackpressureOverflow.Strategy.ON_OVERFLOW_DROP_LATEST} will drop any new items emitted by the producer while + *
  • {@link BackpressureOverflowStrategy#DROP_LATEST} will drop any new items emitted by the producer while * the buffer is full, without generating any {@code onError}. Each drop will, however, invoke {@code onOverflow} * to signal the overflow to the producer.
    • - *
  • {@code BackpressureOverflow.Strategy.ON_OVERFLOW_DROP_OLDEST} will drop the oldest items in the buffer in order to make - * room for newly emitted ones. Overflow will not generate an{@code onError}, but each drop will invoke + *
  • {@link BackpressureOverflowStrategy#DROP_OLDEST} will drop the oldest items in the buffer in order to make + * room for newly emitted ones. Overflow will not generate an {@code onError}, but each drop will invoke * {@code onOverflow} to signal the overflow to the producer.
    • *
* @@ -11961,8 +11977,8 @@ public final Flowable onBackpressureBuffer(int capacity, @NonNull Action onOv *
* * @param capacity number of slots available in the buffer. - * @param onOverflow action to execute if an item needs to be buffered, but there are no available slots. Null is allowed. - * @param overflowStrategy how should the {@code Publisher} react to buffer overflows. Null is not allowed. + * @param onOverflow action to execute if an item needs to be buffered, but there are no available slots, {@code null} is allowed. + * @param overflowStrategy how should the {@code Publisher} react to buffer overflows, {@code null} is not allowed. * @return the source {@code Flowable} modified to buffer items up to the given capacity * @see ReactiveX operators documentation: backpressure operators * @since 2.0 @@ -11971,7 +11987,7 @@ public final Flowable onBackpressureBuffer(int capacity, @NonNull Action onOv @NonNull @BackpressureSupport(BackpressureKind.SPECIAL) @SchedulerSupport(SchedulerSupport.NONE) - public final Flowable onBackpressureBuffer(long capacity, @NonNull Action onOverflow, @NonNull BackpressureOverflowStrategy overflowStrategy) { + public final Flowable onBackpressureBuffer(long capacity, @Nullable Action onOverflow, @NonNull BackpressureOverflowStrategy overflowStrategy) { Objects.requireNonNull(overflowStrategy, "overflowStrategy is null"); ObjectHelper.verifyPositive(capacity, "capacity"); return RxJavaPlugins.onAssembly(new FlowableOnBackpressureBufferStrategy<>(this, capacity, onOverflow, overflowStrategy)); @@ -13637,6 +13653,7 @@ public final Flowable retry(long count) { *
* @param times the number of times to resubscribe if the current {@code Flowable} fails * @param predicate the predicate called with the failure {@link Throwable} and should return {@code true} to trigger a retry. + * @throws IllegalArgumentException if {@code times} is negative * @return the new {@code Flowable} instance */ @CheckReturnValue @@ -14397,7 +14414,7 @@ public final Flowable skip(long time, @NonNull TimeUnit unit, @NonNull Schedu * number of items to drop from the end of the source sequence * @return a {@code Flowable} that emits the items emitted by the source {@code Publisher} except for the dropped ones * at the end - * @throws IndexOutOfBoundsException + * @throws IllegalArgumentException * if {@code count} is less than zero * @see ReactiveX operators documentation: SkipLast */ @@ -14407,7 +14424,7 @@ public final Flowable skip(long time, @NonNull TimeUnit unit, @NonNull Schedu @NonNull public final Flowable skipLast(int count) { if (count < 0) { - throw new IndexOutOfBoundsException("count >= 0 required but it was " + count); + throw new IllegalArgumentException("count >= 0 required but it was " + count); } if (count == 0) { return RxJavaPlugins.onAssembly(this); @@ -14705,7 +14722,7 @@ public final Flowable sorted() { @BackpressureSupport(BackpressureKind.FULL) @SchedulerSupport(SchedulerSupport.NONE) public final Flowable sorted(@NonNull Comparator<@NonNull ? super T> sortFunction) { - Objects.requireNonNull(sortFunction, "sortFunction"); + Objects.requireNonNull(sortFunction, "sortFunction is null"); return toList().toFlowable().map(Functions.listSorter(sortFunction)).flatMapIterable(Functions.identity()); } @@ -15625,6 +15642,7 @@ public final Flowable switchMapSingleDelayError(@NonNull FunctionReactiveX operators documentation: Take */ @CheckReturnValue @@ -15720,8 +15738,8 @@ public final Flowable take(long time, @NonNull TimeUnit unit, @NonNull Schedu * the maximum number of items to emit from the end of the sequence of items emitted by the source * {@code Publisher} * @return a {@code Flowable} that emits at most the last {@code count} items emitted by the source {@code Publisher} - * @throws IndexOutOfBoundsException - * if {@code count} is less than zero + * @throws IllegalArgumentException + * if {@code count} is negative * @see ReactiveX operators documentation: TakeLast */ @CheckReturnValue @@ -15730,7 +15748,7 @@ public final Flowable take(long time, @NonNull TimeUnit unit, @NonNull Schedu @NonNull public final Flowable takeLast(int count) { if (count < 0) { - throw new IndexOutOfBoundsException("count >= 0 required but it was " + count); + throw new IllegalArgumentException("count >= 0 required but it was " + count); } else if (count == 0) { return RxJavaPlugins.onAssembly(new FlowableIgnoreElements<>(this)); @@ -15798,7 +15816,7 @@ public final Flowable takeLast(long count, long time, @NonNull TimeUnit unit) * @return a {@code Flowable} that emits at most {@code count} items from the source {@code Publisher} that were emitted * in a specified window of time before the {@code Publisher} completed, where the timing information is * provided by the given {@code scheduler} - * @throws IndexOutOfBoundsException + * @throws IllegalArgumentException * if {@code count} is less than zero * @see ReactiveX operators documentation: TakeLast */ @@ -15840,8 +15858,8 @@ public final Flowable takeLast(long count, long time, @NonNull TimeUnit unit, * @return a {@code Flowable} that emits at most {@code count} items from the source {@code Publisher} that were emitted * in a specified window of time before the {@code Publisher} completed, where the timing information is * provided by the given {@code scheduler} - * @throws IndexOutOfBoundsException - * if {@code count} is less than zero + * @throws IllegalArgumentException + * if {@code count} is negative * @see ReactiveX operators documentation: TakeLast */ @CheckReturnValue @@ -15853,7 +15871,7 @@ public final Flowable takeLast(long count, long time, @NonNull TimeUnit unit, Objects.requireNonNull(scheduler, "scheduler is null"); ObjectHelper.verifyPositive(bufferSize, "bufferSize"); if (count < 0) { - throw new IndexOutOfBoundsException("count >= 0 required but it was " + count); + throw new IllegalArgumentException("count >= 0 required but it was " + count); } return RxJavaPlugins.onAssembly(new FlowableTakeLastTimed<>(this, count, time, unit, scheduler, bufferSize, delayError)); } @@ -16697,7 +16715,7 @@ public final Flowable timeout(@NonNull Function Flowable timeout(@NonNull Function timeout(long timeout, @NonNull TimeUnit timeUnit) { - return timeout0(timeout, timeUnit, null, Schedulers.computation()); + public final Flowable timeout(long timeout, @NonNull TimeUnit unit) { + return timeout0(timeout, unit, null, Schedulers.computation()); } /** @@ -16729,7 +16747,7 @@ public final Flowable timeout(long timeout, @NonNull TimeUnit timeUnit) { * * @param timeout * maximum duration between items before a timeout occurs - * @param timeUnit + * @param unit * the unit of time that applies to the {@code timeout} argument * @param other * the fallback {@code Publisher} to use in case of a timeout @@ -16740,9 +16758,9 @@ public final Flowable timeout(long timeout, @NonNull TimeUnit timeUnit) { @NonNull @BackpressureSupport(BackpressureKind.FULL) @SchedulerSupport(SchedulerSupport.COMPUTATION) - public final Flowable timeout(long timeout, @NonNull TimeUnit timeUnit, @NonNull Publisher other) { + public final Flowable timeout(long timeout, @NonNull TimeUnit unit, @NonNull Publisher other) { Objects.requireNonNull(other, "other is null"); - return timeout0(timeout, timeUnit, other, Schedulers.computation()); + return timeout0(timeout, unit, other, Schedulers.computation()); } /** @@ -16764,7 +16782,7 @@ public final Flowable timeout(long timeout, @NonNull TimeUnit timeUnit, @NonN * * @param timeout * maximum duration between items before a timeout occurs - * @param timeUnit + * @param unit * the unit of time that applies to the {@code timeout} argument * @param scheduler * the {@code Scheduler} to run the timeout timers on @@ -16778,9 +16796,9 @@ public final Flowable timeout(long timeout, @NonNull TimeUnit timeUnit, @NonN @NonNull @BackpressureSupport(BackpressureKind.FULL) @SchedulerSupport(SchedulerSupport.CUSTOM) - public final Flowable timeout(long timeout, @NonNull TimeUnit timeUnit, @NonNull Scheduler scheduler, @NonNull Publisher other) { + public final Flowable timeout(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, @NonNull Publisher other) { Objects.requireNonNull(other, "other is null"); - return timeout0(timeout, timeUnit, other, scheduler); + return timeout0(timeout, unit, other, scheduler); } /** @@ -16800,7 +16818,7 @@ public final Flowable timeout(long timeout, @NonNull TimeUnit timeUnit, @NonN * * @param timeout * maximum duration between items before a timeout occurs - * @param timeUnit + * @param unit * the unit of time that applies to the {@code timeout} argument * @param scheduler * the {@code Scheduler} to run the timeout timers on @@ -16812,8 +16830,8 @@ public final Flowable timeout(long timeout, @NonNull TimeUnit timeUnit, @NonN @BackpressureSupport(BackpressureKind.PASS_THROUGH) @SchedulerSupport(SchedulerSupport.CUSTOM) @NonNull - public final Flowable timeout(long timeout, @NonNull TimeUnit timeUnit, @NonNull Scheduler scheduler) { - return timeout0(timeout, timeUnit, null, scheduler); + public final Flowable timeout(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) { + return timeout0(timeout, unit, null, scheduler); } /** @@ -16906,11 +16924,11 @@ public final Flowable timeout( return timeout0(firstTimeoutIndicator, itemTimeoutIndicator, other); } - private Flowable timeout0(long timeout, TimeUnit timeUnit, Publisher other, + private Flowable timeout0(long timeout, TimeUnit unit, Publisher other, Scheduler scheduler) { - Objects.requireNonNull(timeUnit, "timeUnit is null"); + Objects.requireNonNull(unit, "unit is null"); Objects.requireNonNull(scheduler, "scheduler is null"); - return RxJavaPlugins.onAssembly(new FlowableTimeoutTimed<>(this, timeout, timeUnit, scheduler, other)); + return RxJavaPlugins.onAssembly(new FlowableTimeoutTimed<>(this, timeout, unit, scheduler, other)); } private Flowable timeout0( diff --git a/src/main/java/io/reactivex/rxjava3/core/Maybe.java b/src/main/java/io/reactivex/rxjava3/core/Maybe.java index e8e01a15c7..441267389c 100644 --- a/src/main/java/io/reactivex/rxjava3/core/Maybe.java +++ b/src/main/java/io/reactivex/rxjava3/core/Maybe.java @@ -147,12 +147,14 @@ public static Maybe amb(@NonNull Iterable Maybe ambArray(@NonNull MaybeSource... sources) { + Objects.requireNonNull(sources, "sources is null"); if (sources.length == 0) { return empty(); } @@ -402,6 +404,7 @@ public static Flowable concatArray(@NonNull MaybeSource... s @SafeVarargs @NonNull public static Flowable concatArrayDelayError(@NonNull MaybeSource... sources) { + Objects.requireNonNull(sources, "sources is null"); if (sources.length == 0) { return Flowable.empty(); } else @@ -1364,6 +1367,7 @@ public static Flowable mergeArray(MaybeSource... sources) { @SafeVarargs @NonNull public static Flowable mergeArrayDelayError(@NonNull MaybeSource... sources) { + Objects.requireNonNull(sources, "sources is null"); if (sources.length == 0) { return Flowable.empty(); } @@ -1764,6 +1768,8 @@ public static Maybe timer(long delay, @NonNull TimeUnit unit, @NonNull Sch * @param the value type * @param onSubscribe the function that is called with the subscribing {@code MaybeObserver} * @return the new {@code Maybe} instance + * @throws IllegalArgumentException if {@code onSubscribe} is a {@code Maybe} + * @throws NullPointerException if {@code onSubscribe} is {@code null} */ @CheckReturnValue @NonNull @@ -1858,6 +1864,7 @@ public static Maybe using(@NonNull Supplier resourceSuppl * @param the value type * @param source the source to wrap * @return the {@code Maybe} wrapper or the source cast to {@code Maybe} (if possible) + * @throws NullPointerException if {@code source} is {@code null} */ @CheckReturnValue @NonNull @@ -3522,7 +3529,7 @@ public final Single isEmpty() { * if (str.length() < 2) { * downstream.onSuccess(str); * } else { - * // Maybe i {@code Maybe} ly expected to produce one of the onXXX events + * // Maybe is expected to produce one of the onXXX events only * downstream.onComplete(); * } * } diff --git a/src/main/java/io/reactivex/rxjava3/core/Observable.java b/src/main/java/io/reactivex/rxjava3/core/Observable.java index 5c94b3f9e2..2d75dee207 100644 --- a/src/main/java/io/reactivex/rxjava3/core/Observable.java +++ b/src/main/java/io/reactivex/rxjava3/core/Observable.java @@ -21,7 +21,7 @@ import io.reactivex.rxjava3.annotations.*; import io.reactivex.rxjava3.disposables.Disposable; -import io.reactivex.rxjava3.exceptions.Exceptions; +import io.reactivex.rxjava3.exceptions.*; import io.reactivex.rxjava3.functions.*; import io.reactivex.rxjava3.internal.functions.*; import io.reactivex.rxjava3.internal.fuseable.ScalarSupplier; @@ -37,14 +37,14 @@ import io.reactivex.rxjava3.schedulers.*; /** - * The Observable class is the non-backpressured, optionally multi-valued base reactive class that + * The {@code Observable} class is the non-backpressured, optionally multi-valued base reactive class that * offers factory methods, intermediate operators and the ability to consume synchronous * and/or asynchronous reactive dataflows. *

- * Many operators in the class accept {@code ObservableSource}(s), the base reactive interface + * Many operators in the class accept {@link ObservableSource}(s), the base reactive interface * for such non-backpressured flows, which {@code Observable} itself implements as well. *

- * The Observable's operators, by default, run with a buffer size of 128 elements (see {@link Flowable#bufferSize()}), + * The {@code Observable}'s operators, by default, run with a buffer size of 128 elements (see {@link Flowable#bufferSize()}), * that can be overridden globally via the system parameter {@code rx3.buffer-size}. Most operators, however, have * overloads that allow setting their internal buffer size explicitly. *

@@ -67,7 +67,7 @@ * {@code Observer.onSubscribe}. *

* Unlike the {@code Observable} of version 1.x, {@link #subscribe(Observer)} does not allow external disposal - * of a subscription and the {@code Observer} instance is expected to expose such capability. + * of a subscription and the {@link Observer} instance is expected to expose such capability. *

Example: * 


  * Disposable d = Observable.just("Hello world!")
@@ -93,14 +93,14 @@
  *
* * @param - * the type of the items emitted by the Observable + * the type of the items emitted by the {@code Observable} * @see Flowable * @see io.reactivex.rxjava3.observers.DisposableObserver */ public abstract class Observable implements ObservableSource { /** - * Mirrors the one ObservableSource in an Iterable of several ObservableSources that first either emits an item or sends + * Mirrors the one {@link ObservableSource} in an {@link Iterable} of several {@code ObservableSource}s that first either emits an item or sends * a termination notification. *

* @@ -111,10 +111,11 @@ public abstract class Observable implements ObservableSource { * * @param the common element type * @param sources - * an Iterable of ObservableSource sources competing to react first. A subscription to each source will - * occur in the same order as in the Iterable. - * @return an Observable that emits the same sequence as whichever of the source ObservableSources first + * an {@code Iterable} of {@code ObservableSource} sources competing to react first. A subscription to each source will + * occur in the same order as in the {@code Iterable}. + * @return an {@code Observable} that emits the same sequence as whichever of the returned {@code ObservableSource}s first * emitted an item or sent a termination notification + * @throws NullPointerException if {@code sources} is {@code null} * @see ReactiveX operators documentation: Amb */ @CheckReturnValue @@ -126,7 +127,7 @@ public static Observable amb(@NonNull Iterable * @@ -137,10 +138,11 @@ public static Observable amb(@NonNull Iterable the common element type * @param sources - * an array of ObservableSource sources competing to react first. A subscription to each source will + * an array of {@code ObservableSource} sources competing to react first. A subscription to each source will * occur in the same order as in the array. - * @return an Observable that emits the same sequence as whichever of the source ObservableSources first + * @return an {@code Observable} that emits the same sequence as whichever of the returned {@code ObservableSource}s first * emitted an item or sent a termination notification + * @throws NullPointerException if {@code sources} is {@code null} * @see ReactiveX operators documentation: Amb */ @SuppressWarnings("unchecked") @@ -173,19 +175,19 @@ public static int bufferSize() { } /** - * Combines a collection of source ObservableSources 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 ObservableSources, where this + * Combines a collection of source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of + * the returned {@code ObservableSource}s each time an item is received from any of the returned {@code ObservableSource}s, where this * aggregation is defined by a specified function. *

* Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a - * {@code Function} passed to the method would trigger a {@code ClassCastException}. + * {@code Function} passed to the method would trigger a {@link ClassCastException}. *

* If any of the sources never produces an item but only terminates (normally or with an error), the * resulting sequence terminates immediately (normally or with all the errors accumulated till that point). * If that input source is also synchronous, other sources after it will not be subscribed to. *

- * If the provided iterable of ObservableSources is empty, the resulting sequence completes immediately without emitting + * If the provided iterable of {@code ObservableSource}s is empty, the resulting sequence completes immediately without emitting * any items and without any calls to the combiner function. * *

@@ -200,11 +202,11 @@ public static int bufferSize() { * @param * the result type * @param sources - * the collection of source ObservableSources + * the collection of source {@code ObservableSource}s * @param combiner - * the aggregation function used to combine the items emitted by the source ObservableSources - * @return an Observable that emits items that are the result of combining the items emitted by the source - * ObservableSources by means of the given aggregation function + * the aggregation function used to combine the items emitted by the returned {@code ObservableSource}s + * @return an {@code Observable} that emits items that are the result of combining the items emitted by the returned + * {@code ObservableSource}s by means of the given aggregation function * @see ReactiveX operators documentation: CombineLatest */ @CheckReturnValue @@ -217,19 +219,19 @@ public static Observable combineLatest( } /** - * Combines a collection of source ObservableSources 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 ObservableSources, where this + * Combines an {@link Iterable} of source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of + * the returned {@code ObservableSource}s each time an item is received from any of the returned {@code ObservableSource}s, where this * aggregation is defined by a specified function. *

* Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a - * {@code Function} passed to the method would trigger a {@code ClassCastException}. + * {@code Function} passed to the method would trigger a {@link ClassCastException}. *

* If any of the sources never produces an item but only terminates (normally or with an error), the * resulting sequence terminates immediately (normally or with all the errors accumulated till that point). * If that input source is also synchronous, other sources after it will not be subscribed to. *

- * If the provided iterable of ObservableSources is empty, the resulting sequence completes immediately without emitting + * If the provided {@code Iterable} of {@code ObservableSource}s is empty, the resulting sequence completes immediately without emitting * any items and without any calls to the combiner function. * *

@@ -244,13 +246,15 @@ public static Observable combineLatest( * @param * the result type * @param sources - * the collection of source ObservableSources + * the collection of source {@code ObservableSource}s * @param combiner - * the aggregation function used to combine the items emitted by the source ObservableSources + * the aggregation function used to combine the items emitted by the returned {@code ObservableSource}s * @param bufferSize - * the internal buffer size and prefetch amount applied to every source Observable - * @return an Observable that emits items that are the result of combining the items emitted by the source - * ObservableSources by means of the given aggregation function + * the expected number of row combination items to be buffered internally + * @return an {@code Observable} that emits items that are the result of combining the items emitted by the returned + * {@code ObservableSource}s by means of the given aggregation function + * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: CombineLatest */ @CheckReturnValue @@ -269,19 +273,19 @@ public static Observable combineLatest( } /** - * Combines a collection of source ObservableSources 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 ObservableSources, where this + * Combines an array of source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of + * the {@code ObservableSource}s each time an item is received from any of the returned {@code ObservableSource}s, where this * aggregation is defined by a specified function. *

* Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a - * {@code Function} passed to the method would trigger a {@code ClassCastException}. + * {@code Function} passed to the method would trigger a {@link ClassCastException}. *

* If any of the sources never produces an item but only terminates (normally or with an error), the * resulting sequence terminates immediately (normally or with all the errors accumulated till that point). * If that input source is also synchronous, other sources after it will not be subscribed to. *

- * If the provided array of ObservableSources is empty, the resulting sequence completes immediately without emitting + * If the provided array of {@code ObservableSource}s is empty, the resulting sequence completes immediately without emitting * any items and without any calls to the combiner function. * *

@@ -296,11 +300,11 @@ public static Observable combineLatest( * @param * the result type * @param sources - * the collection of source ObservableSources + * the collection of source {@code ObservableSource}s * @param combiner - * the aggregation function used to combine the items emitted by the source ObservableSources - * @return an Observable that emits items that are the result of combining the items emitted by the source - * ObservableSources by means of the given aggregation function + * the aggregation function used to combine the items emitted by the {@code ObservableSource}s + * @return an {@code Observable} that emits items that are the result of combining the items emitted by the returned + * {@code ObservableSource}s by means of the given aggregation function * @see ReactiveX operators documentation: CombineLatest */ @CheckReturnValue @@ -313,19 +317,19 @@ public static Observable combineLatestArray( } /** - * Combines a collection of source ObservableSources 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 ObservableSources, where this + * Combines an array of source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of + * the {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this * aggregation is defined by a specified function. *

* Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a - * {@code Function} passed to the method would trigger a {@code ClassCastException}. + * {@code Function} passed to the method would trigger a {@link ClassCastException}. *

* If any of the sources never produces an item but only terminates (normally or with an error), the * resulting sequence terminates immediately (normally or with all the errors accumulated till that point). * If that input source is also synchronous, other sources after it will not be subscribed to. *

- * If the provided array of ObservableSources is empty, the resulting sequence completes immediately without emitting + * If the provided array of {@code ObservableSource}s is empty, the resulting sequence completes immediately without emitting * any items and without any calls to the combiner function. * *

@@ -340,13 +344,15 @@ public static Observable combineLatestArray( * @param * the result type * @param sources - * the collection of source ObservableSources + * the collection of source {@code ObservableSource}s * @param combiner - * the aggregation function used to combine the items emitted by the source ObservableSources + * the aggregation function used to combine the items emitted by the {@code ObservableSource}s * @param bufferSize - * the internal buffer size and prefetch amount applied to every source Observable - * @return an Observable that emits items that are the result of combining the items emitted by the source - * ObservableSources by means of the given aggregation function + * the expected number of row combination items to be buffered internally + * @return an {@code Observable} that emits items that are the result of combining the items emitted by the + * {@code ObservableSource}s by means of the given aggregation function + * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: CombineLatest */ @CheckReturnValue @@ -368,8 +374,8 @@ public static Observable combineLatestArray( } /** - * Combines two source ObservableSources by emitting an item that aggregates the latest values of each of the - * source ObservableSources each time an item is received from either of the source ObservableSources, where this + * Combines two source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of the + * {@code ObservableSource}s each time an item is received from either of the {@code ObservableSource}s, where this * aggregation is defined by a specified function. *

* If any of the sources never produces an item but only terminates (normally or with an error), the @@ -386,13 +392,14 @@ public static Observable combineLatestArray( * @param the element type of the second source * @param the combined output type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * the second source ObservableSource + * the second source {@code ObservableSource} * @param combiner - * the aggregation function used to combine the items emitted by the source ObservableSources - * @return an Observable that emits items that are the result of combining the items emitted by the source - * ObservableSources by means of the given aggregation function + * the aggregation function used to combine the items emitted by the {@code ObservableSource}s + * @return an {@code Observable} that emits items that are the result of combining the items emitted by the + * {@code ObservableSource}s by means of the given aggregation function + * @throws NullPointerException if {@code source1}, {@code source2} or {@code combiner} is {@code null} * @see ReactiveX operators documentation: CombineLatest */ @SuppressWarnings("unchecked") @@ -409,8 +416,8 @@ public static Observable combineLatest( } /** - * Combines three source ObservableSources 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 ObservableSources, where this + * Combines three source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of the + * {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this * aggregation is defined by a specified function. *

* If any of the sources never produces an item but only terminates (normally or with an error), the @@ -428,15 +435,16 @@ public static Observable combineLatest( * @param the element type of the third source * @param the combined output type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * the second source ObservableSource + * the second source {@code ObservableSource} * @param source3 - * the third source ObservableSource + * the third source {@code ObservableSource} * @param combiner - * the aggregation function used to combine the items emitted by the source ObservableSources - * @return an Observable that emits items that are the result of combining the items emitted by the source - * ObservableSources by means of the given aggregation function + * the aggregation function used to combine the items emitted by the {@code ObservableSource}s + * @return an {@code Observable} that emits items that are the result of combining the items emitted by the + * {@code ObservableSource}s by means of the given aggregation function + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code combiner} is {@code null} * @see ReactiveX operators documentation: CombineLatest */ @SuppressWarnings("unchecked") @@ -455,8 +463,8 @@ public static Observable combineLatest( } /** - * Combines four source ObservableSources 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 ObservableSources, where this + * Combines four source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of the + * {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this * aggregation is defined by a specified function. *

* If any of the sources never produces an item but only terminates (normally or with an error), the @@ -475,17 +483,19 @@ public static Observable combineLatest( * @param the element type of the fourth source * @param the combined output type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * the second source ObservableSource + * the second source {@code ObservableSource} * @param source3 - * the third source ObservableSource + * the third source {@code ObservableSource} * @param source4 - * the fourth source ObservableSource + * the fourth source {@code ObservableSource} * @param combiner - * the aggregation function used to combine the items emitted by the source ObservableSources - * @return an Observable that emits items that are the result of combining the items emitted by the source - * ObservableSources by means of the given aggregation function + * the aggregation function used to combine the items emitted by the {@code ObservableSource}s + * @return an {@code Observable} that emits items that are the result of combining the items emitted by the + * {@code ObservableSource}s by means of the given aggregation function + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, + * {@code source4} or {@code combiner} is {@code null} * @see ReactiveX operators documentation: CombineLatest */ @SuppressWarnings("unchecked") @@ -505,8 +515,8 @@ public static Observable combineLatest( } /** - * Combines five source ObservableSources 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 ObservableSources, where this + * Combines five source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of the + * {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this * aggregation is defined by a specified function. *

* If any of the sources never produces an item but only terminates (normally or with an error), the @@ -526,19 +536,21 @@ public static Observable combineLatest( * @param the element type of the fifth source * @param the combined output type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * the second source ObservableSource + * the second source {@code ObservableSource} * @param source3 - * the third source ObservableSource + * the third source {@code ObservableSource} * @param source4 - * the fourth source ObservableSource + * the fourth source {@code ObservableSource} * @param source5 - * the fifth source ObservableSource + * the fifth source {@code ObservableSource} * @param combiner - * the aggregation function used to combine the items emitted by the source ObservableSources - * @return an Observable that emits items that are the result of combining the items emitted by the source - * ObservableSources by means of the given aggregation function + * the aggregation function used to combine the items emitted by the {@code ObservableSource}s + * @return an {@code Observable} that emits items that are the result of combining the items emitted by the + * {@code ObservableSource}s by means of the given aggregation function + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, + * {@code source4}, {@code source5} or {@code combiner} is {@code null} * @see ReactiveX operators documentation: CombineLatest */ @SuppressWarnings("unchecked") @@ -560,8 +572,8 @@ public static Observable combineLatest( } /** - * Combines six source ObservableSources 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 ObservableSources, where this + * Combines six source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of the + * {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this * aggregation is defined by a specified function. *

* If any of the sources never produces an item but only terminates (normally or with an error), the @@ -582,21 +594,23 @@ public static Observable combineLatest( * @param the element type of the sixth source * @param the combined output type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * the second source ObservableSource + * the second source {@code ObservableSource} * @param source3 - * the third source ObservableSource + * the third source {@code ObservableSource} * @param source4 - * the fourth source ObservableSource + * the fourth source {@code ObservableSource} * @param source5 - * the fifth source ObservableSource + * the fifth source {@code ObservableSource} * @param source6 - * the sixth source ObservableSource + * the sixth source {@code ObservableSource} * @param combiner - * the aggregation function used to combine the items emitted by the source ObservableSources - * @return an Observable that emits items that are the result of combining the items emitted by the source - * ObservableSources by means of the given aggregation function + * the aggregation function used to combine the items emitted by the {@code ObservableSource}s + * @return an {@code Observable} that emits items that are the result of combining the items emitted by the + * {@code ObservableSource}s by means of the given aggregation function + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, + * {@code source4}, {@code source5}, {@code source6} or {@code combiner} is {@code null} * @see ReactiveX operators documentation: CombineLatest */ @SuppressWarnings("unchecked") @@ -619,8 +633,8 @@ public static Observable combineLatest( } /** - * Combines seven source ObservableSources 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 ObservableSources, where this + * Combines seven source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of the + * {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this * aggregation is defined by a specified function. *

* If any of the sources never produces an item but only terminates (normally or with an error), the @@ -642,23 +656,26 @@ public static Observable combineLatest( * @param the element type of the seventh source * @param the combined output type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * the second source ObservableSource + * the second source {@code ObservableSource} * @param source3 - * the third source ObservableSource + * the third source {@code ObservableSource} * @param source4 - * the fourth source ObservableSource + * the fourth source {@code ObservableSource} * @param source5 - * the fifth source ObservableSource + * the fifth source {@code ObservableSource} * @param source6 - * the sixth source ObservableSource + * the sixth source {@code ObservableSource} * @param source7 - * the seventh source ObservableSource + * the seventh source {@code ObservableSource} * @param combiner - * the aggregation function used to combine the items emitted by the source ObservableSources - * @return an Observable that emits items that are the result of combining the items emitted by the source - * ObservableSources by means of the given aggregation function + * the aggregation function used to combine the items emitted by the {@code ObservableSource}s + * @return an {@code Observable} that emits items that are the result of combining the items emitted by the + * {@code ObservableSource}s by means of the given aggregation function + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, + * {@code source4}, {@code source5}, {@code source6}, + * {@code source7} or {@code combiner} is {@code null} * @see ReactiveX operators documentation: CombineLatest */ @SuppressWarnings("unchecked") @@ -683,8 +700,8 @@ public static Observable combineLatest( } /** - * Combines eight source ObservableSources 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 ObservableSources, where this + * Combines eight source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of the + * {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this * aggregation is defined by a specified function. *

* If any of the sources never produces an item but only terminates (normally or with an error), the @@ -707,25 +724,28 @@ public static Observable combineLatest( * @param the element type of the eighth source * @param the combined output type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * the second source ObservableSource + * the second source {@code ObservableSource} * @param source3 - * the third source ObservableSource + * the third source {@code ObservableSource} * @param source4 - * the fourth source ObservableSource + * the fourth source {@code ObservableSource} * @param source5 - * the fifth source ObservableSource + * the fifth source {@code ObservableSource} * @param source6 - * the sixth source ObservableSource + * the sixth source {@code ObservableSource} * @param source7 - * the seventh source ObservableSource + * the seventh source {@code ObservableSource} * @param source8 - * the eighth source ObservableSource + * the eighth source {@code ObservableSource} * @param combiner - * the aggregation function used to combine the items emitted by the source ObservableSources - * @return an Observable that emits items that are the result of combining the items emitted by the source - * ObservableSources by means of the given aggregation function + * the aggregation function used to combine the items emitted by the {@code ObservableSource}s + * @return an {@code Observable} that emits items that are the result of combining the items emitted by the + * {@code ObservableSource}s by means of the given aggregation function + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, + * {@code source4}, {@code source5}, {@code source6}, + * {@code source7}, {@code source8} or {@code combiner} is {@code null} * @see ReactiveX operators documentation: CombineLatest */ @SuppressWarnings("unchecked") @@ -751,8 +771,8 @@ public static Observable combineLatest( } /** - * Combines nine source ObservableSources 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 ObservableSources, where this + * Combines nine source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of the + * {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this * aggregation is defined by a specified function. *

* If any of the sources never produces an item but only terminates (normally or with an error), the @@ -776,27 +796,30 @@ public static Observable combineLatest( * @param the element type of the ninth source * @param the combined output type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * the second source ObservableSource + * the second source {@code ObservableSource} * @param source3 - * the third source ObservableSource + * the third source {@code ObservableSource} * @param source4 - * the fourth source ObservableSource + * the fourth source {@code ObservableSource} * @param source5 - * the fifth source ObservableSource + * the fifth source {@code ObservableSource} * @param source6 - * the sixth source ObservableSource + * the sixth source {@code ObservableSource} * @param source7 - * the seventh source ObservableSource + * the seventh source {@code ObservableSource} * @param source8 - * the eighth source ObservableSource + * the eighth source {@code ObservableSource} * @param source9 - * the ninth source ObservableSource + * the ninth source {@code ObservableSource} * @param combiner - * the aggregation function used to combine the items emitted by the source ObservableSources - * @return an Observable that emits items that are the result of combining the items emitted by the source - * ObservableSources by means of the given aggregation function + * the aggregation function used to combine the items emitted by the {@code ObservableSource}s + * @return an {@code Observable} that emits items that are the result of combining the items emitted by the + * {@code ObservableSource}s by means of the given aggregation function + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, + * {@code source4}, {@code source5}, {@code source6}, + * {@code source7}, {@code source8}, {@code source9} or {@code combiner} is {@code null} * @see ReactiveX operators documentation: CombineLatest */ @SuppressWarnings("unchecked") @@ -824,21 +847,21 @@ public static Observable combineLates } /** - * Combines a collection of source ObservableSources 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 ObservableSources, where this + * Combines an array of {@link ObservableSource}s by emitting an item that aggregates the latest values of each of + * the {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this * aggregation is defined by a specified function. *

* *

* Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a - * {@code Function} passed to the method would trigger a {@code ClassCastException}. + * {@code Function} passed to the method would trigger a {@link ClassCastException}. *

* If any of the sources never produces an item but only terminates (normally or with an error), the * resulting sequence terminates immediately (normally or with all the errors accumulated till that point). * If that input source is also synchronous, other sources after it will not be subscribed to. *

- * If the provided array of ObservableSources is empty, the resulting sequence completes immediately without emitting + * If the provided array of {@code ObservableSource}s is empty, the resulting sequence completes immediately without emitting * any items and without any calls to the combiner function. * *

@@ -851,11 +874,11 @@ public static Observable combineLates * @param * the result type * @param sources - * the collection of source ObservableSources + * the collection of source {@code ObservableSource}s * @param combiner - * the aggregation function used to combine the items emitted by the source ObservableSources - * @return an Observable that emits items that are the result of combining the items emitted by the source - * ObservableSources by means of the given aggregation function + * the aggregation function used to combine the items emitted by the {@code ObservableSource}s + * @return an {@code Observable} that emits items that are the result of combining the items emitted by the + * {@code ObservableSource}s by means of the given aggregation function * @see ReactiveX operators documentation: CombineLatest */ @CheckReturnValue @@ -868,20 +891,20 @@ public static Observable combineLatestDelayError( } /** - * Combines a collection of source ObservableSources 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 ObservableSources, where this + * Combines an array of {@link ObservableSource}s by emitting an item that aggregates the latest values of each of + * the {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this * aggregation is defined by a specified function and delays any error from the sources until - * all source ObservableSources terminate. + * all source {@code ObservableSource}s terminate. *

* Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a - * {@code Function} passed to the method would trigger a {@code ClassCastException}. + * {@code Function} passed to the method would trigger a {@link ClassCastException}. *

* If any of the sources never produces an item but only terminates (normally or with an error), the * resulting sequence terminates immediately (normally or with all the errors accumulated till that point). * If that input source is also synchronous, other sources after it will not be subscribed to. *

- * If the provided array of ObservableSources is empty, the resulting sequence completes immediately without emitting + * If the provided array of {@code ObservableSource}s is empty, the resulting sequence completes immediately without emitting * any items and without any calls to the combiner function. * *

@@ -896,13 +919,15 @@ public static Observable combineLatestDelayError( * @param * the result type * @param sources - * the collection of source ObservableSources + * the collection of source {@code ObservableSource}s * @param combiner - * the aggregation function used to combine the items emitted by the source ObservableSources + * the aggregation function used to combine the items emitted by the {@code ObservableSource}s * @param bufferSize - * the internal buffer size and prefetch amount applied to every source Observable - * @return an Observable that emits items that are the result of combining the items emitted by the source - * ObservableSources by means of the given aggregation function + * the expected number of row combination items to be buffered internally + * @return an {@code Observable} that emits items that are the result of combining the items emitted by the + * {@code ObservableSource}s by means of the given aggregation function + * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: CombineLatest */ @CheckReturnValue @@ -910,8 +935,9 @@ public static Observable combineLatestDelayError( @SchedulerSupport(SchedulerSupport.NONE) public static Observable combineLatestDelayError(@NonNull ObservableSource[] sources, @NonNull Function combiner, int bufferSize) { - ObjectHelper.verifyPositive(bufferSize, "bufferSize"); + Objects.requireNonNull(sources, "sources is null"); Objects.requireNonNull(combiner, "combiner is null"); + ObjectHelper.verifyPositive(bufferSize, "bufferSize"); if (sources.length == 0) { return empty(); } @@ -921,20 +947,20 @@ public static Observable combineLatestDelayError(@NonNull ObservableSo } /** - * Combines a collection of source ObservableSources 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 ObservableSources, where this + * Combines an {@link Iterable} of {@link ObservableSource}s by emitting an item that aggregates the latest values of each of + * the {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this * aggregation is defined by a specified function and delays any error from the sources until - * all source ObservableSources terminate. + * all source {@code ObservableSource}s terminate. *

* Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a - * {@code Function} passed to the method would trigger a {@code ClassCastException}. + * {@code Function} passed to the method would trigger a {@link ClassCastException}. *

* If any of the sources never produces an item but only terminates (normally or with an error), the * resulting sequence terminates immediately (normally or with all the errors accumulated till that point). * If that input source is also synchronous, other sources after it will not be subscribed to. *

- * If the provided iterable of ObservableSources is empty, the resulting sequence completes immediately without emitting + * If the provided iterable of {@code ObservableSource}s is empty, the resulting sequence completes immediately without emitting * any items and without any calls to the combiner function. * *

@@ -949,11 +975,11 @@ public static Observable combineLatestDelayError(@NonNull ObservableSo * @param * the result type * @param sources - * the collection of source ObservableSources + * the {@code Iterable} of source {@code ObservableSource}s * @param combiner - * the aggregation function used to combine the items emitted by the source ObservableSources - * @return an Observable that emits items that are the result of combining the items emitted by the source - * ObservableSources by means of the given aggregation function + * the aggregation function used to combine the items emitted by the {@code ObservableSource}s + * @return an {@code Observable} that emits items that are the result of combining the items emitted by the + * {@code ObservableSource}s by means of the given aggregation function * @see ReactiveX operators documentation: CombineLatest */ @CheckReturnValue @@ -965,20 +991,20 @@ public static Observable combineLatestDelayError(@NonNull Iterable * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a - * {@code Function} passed to the method would trigger a {@code ClassCastException}. + * {@code Function} passed to the method would trigger a {@link ClassCastException}. *

* If any of the sources never produces an item but only terminates (normally or with an error), the * resulting sequence terminates immediately (normally or with all the errors accumulated till that point). * If that input source is also synchronous, other sources after it will not be subscribed to. *

- * If the provided iterable of ObservableSources is empty, the resulting sequence completes immediately without emitting + * If the provided iterable of {@code ObservableSource}s is empty, the resulting sequence completes immediately without emitting * any items and without any calls to the combiner function. * *

@@ -993,13 +1019,15 @@ public static Observable combineLatestDelayError(@NonNull Iterable * the result type * @param sources - * the collection of source ObservableSources + * the collection of source {@code ObservableSource}s * @param combiner - * the aggregation function used to combine the items emitted by the source ObservableSources + * the aggregation function used to combine the items emitted by the {@code ObservableSource}s * @param bufferSize - * the internal buffer size and prefetch amount applied to every source Observable - * @return an Observable that emits items that are the result of combining the items emitted by the source - * ObservableSources by means of the given aggregation function + * the expected number of row combination items to be buffered internally + * @return an {@code Observable} that emits items that are the result of combining the items emitted by the + * {@code ObservableSource}s by means of the given aggregation function + * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: CombineLatest */ @CheckReturnValue @@ -1017,7 +1045,7 @@ public static Observable combineLatestDelayError(@NonNull Iterable * @@ -1026,8 +1054,9 @@ public static Observable combineLatestDelayError(@NonNull Iterable{@code concat} does not operate by default on a particular {@link Scheduler}. *

* @param the common value type of the sources - * @param sources the Iterable sequence of ObservableSources - * @return the new Observable instance + * @param sources the {@code Iterable} sequence of {@code ObservableSource}s + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code sources} is {@code null} */ @SuppressWarnings({ "unchecked", "rawtypes" }) @CheckReturnValue @@ -1039,8 +1068,8 @@ public static Observable concat(@NonNull Iterable * *
@@ -1050,9 +1079,10 @@ public static Observable concat(@NonNull Iterable the common element base type * @param sources - * an ObservableSource that emits ObservableSources - * @return an Observable that emits items all of the items emitted by the ObservableSources emitted by - * {@code ObservableSources}, one after the other, without interleaving them + * an {@code ObservableSource} that emits {@code ObservableSource}s + * @return an {@code Observable} that emits items all of the items emitted by the {@code ObservableSource}s emitted by + * {@code ObservableSource}s, one after the other, without interleaving them + * @throws NullPointerException if {@code sources} is {@code null} * @see ReactiveX operators documentation: Concat */ @CheckReturnValue @@ -1063,8 +1093,8 @@ public static Observable concat(@NonNull ObservableSource * *
@@ -1074,25 +1104,27 @@ public static Observable concat(@NonNull ObservableSource the common element base type * @param sources - * an ObservableSource that emits ObservableSources - * @param prefetch - * the number of ObservableSources to prefetch from the sources sequence. - * @return an Observable that emits items all of the items emitted by the ObservableSources emitted by - * {@code ObservableSources}, one after the other, without interleaving them + * an {@code ObservableSource} that emits {@code ObservableSource}s + * @param bufferSize + * the number of inner {@code ObservableSource}s expected to be buffered. + * @return an {@code Observable} that emits items all of the items emitted by the {@code ObservableSource}s emitted by + * {@code ObservableSource}s, one after the other, without interleaving them + * @throws NullPointerException if {@code sources} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Concat */ @SuppressWarnings({ "unchecked", "rawtypes" }) @CheckReturnValue @NonNull @SchedulerSupport(SchedulerSupport.NONE) - public static Observable concat(@NonNull ObservableSource> sources, int prefetch) { + public static Observable concat(@NonNull ObservableSource> sources, int bufferSize) { Objects.requireNonNull(sources, "sources is null"); - ObjectHelper.verifyPositive(prefetch, "prefetch"); - return RxJavaPlugins.onAssembly(new ObservableConcatMap(sources, Functions.identity(), prefetch, ErrorMode.IMMEDIATE)); + ObjectHelper.verifyPositive(bufferSize, "bufferSize"); + return RxJavaPlugins.onAssembly(new ObservableConcatMap(sources, Functions.identity(), bufferSize, ErrorMode.IMMEDIATE)); } /** - * Returns an Observable that emits the items emitted by two ObservableSources, one after the other, without + * Returns an {@code Observable} that emits the items emitted by two {@link ObservableSource}s, one after the other, without * interleaving them. *

* @@ -1103,11 +1135,12 @@ public static Observable concat(@NonNull ObservableSource the common element base type * @param source1 - * an ObservableSource to be concatenated + * an {@code ObservableSource} to be concatenated * @param source2 - * an ObservableSource to be concatenated - * @return an Observable that emits items emitted by the two source ObservableSources, one after the other, + * an {@code ObservableSource} to be concatenated + * @return an {@code Observable} that emits items emitted by the two source {@code ObservableSource}s, one after the other, * without interleaving them + * @throws NullPointerException if {@code source1} or {@code source2} is {@code null} * @see ReactiveX operators documentation: Concat */ @CheckReturnValue @@ -1120,7 +1153,7 @@ public static Observable concat(@NonNull ObservableSource so } /** - * Returns an Observable that emits the items emitted by three ObservableSources, one after the other, without + * Returns an {@code Observable} that emits the items emitted by three {@link ObservableSource}s, one after the other, without * interleaving them. *

* @@ -1131,13 +1164,14 @@ public static Observable concat(@NonNull ObservableSource so * * @param the common element base type * @param source1 - * an ObservableSource to be concatenated + * an {@code ObservableSource} to be concatenated * @param source2 - * an ObservableSource to be concatenated + * an {@code ObservableSource} to be concatenated * @param source3 - * an ObservableSource to be concatenated - * @return an Observable that emits items emitted by the three source ObservableSources, one after the other, + * an {@code ObservableSource} to be concatenated + * @return an {@code Observable} that emits items emitted by the three source {@code ObservableSource}s, one after the other, * without interleaving them + * @throws NullPointerException if {@code source1}, {@code source2} or {@code source3} is {@code null} * @see ReactiveX operators documentation: Concat */ @CheckReturnValue @@ -1153,7 +1187,7 @@ public static Observable concat( } /** - * Returns an Observable that emits the items emitted by four ObservableSources, one after the other, without + * Returns an {@code Observable} that emits the items emitted by four {@link ObservableSource}s, one after the other, without * interleaving them. *

* @@ -1164,15 +1198,16 @@ public static Observable concat( * * @param the common element base type * @param source1 - * an ObservableSource to be concatenated + * an {@code ObservableSource} to be concatenated * @param source2 - * an ObservableSource to be concatenated + * an {@code ObservableSource} to be concatenated * @param source3 - * an ObservableSource to be concatenated + * an {@code ObservableSource} to be concatenated * @param source4 - * an ObservableSource to be concatenated - * @return an Observable that emits items emitted by the four source ObservableSources, one after the other, + * an {@code ObservableSource} to be concatenated + * @return an {@code Observable} that emits items emitted by the four source {@code ObservableSource}s, one after the other, * without interleaving them + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code source4} is {@code null} * @see ReactiveX operators documentation: Concat */ @CheckReturnValue @@ -1189,9 +1224,9 @@ public static Observable concat( } /** - * Concatenates a variable number of ObservableSource sources. + * Concatenates a variable number of {@link ObservableSource} sources. *

- * Note: named this way because of overload conflict with concat(ObservableSource<ObservableSource>) + * Note: named this way because of overload conflict with {@code concat(ObservableSource)} *

* *

@@ -1200,8 +1235,8 @@ public static Observable concat( *
* @param sources the array of sources * @param the common base value type - * @return the new Observable instance - * @throws NullPointerException if sources is null + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code sources} is {@code null} */ @SuppressWarnings({ "unchecked", "rawtypes" }) @CheckReturnValue @@ -1209,6 +1244,7 @@ public static Observable concat( @NonNull @SafeVarargs public static Observable concatArray(@NonNull ObservableSource... sources) { + Objects.requireNonNull(sources, "sources is null"); if (sources.length == 0) { return empty(); } @@ -1219,7 +1255,7 @@ public static Observable concatArray(@NonNull ObservableSource * @@ -1229,14 +1265,15 @@ public static Observable concatArray(@NonNull ObservableSource * @param sources the array of sources * @param the common base value type - * @return the new Observable instance - * @throws NullPointerException if sources is null + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code sources} is {@code null} */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @NonNull @SafeVarargs public static Observable concatArrayDelayError(@NonNull ObservableSource... sources) { + Objects.requireNonNull(sources, "sources is null"); if (sources.length == 0) { return empty(); } @@ -1249,20 +1286,20 @@ public static Observable concatArrayDelayError(@NonNull ObservableSource< } /** - * Concatenates an array of ObservableSources eagerly into a single stream of values. + * Concatenates an array of {@link ObservableSource}s eagerly into a single stream of values. *

* *

* Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the - * source ObservableSources. The operator buffers the values emitted by these ObservableSources and then drains them + * {@code ObservableSource}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them * in order, each one after the previous one completes. *

*
Scheduler:
*
This method does not operate by default on a particular {@link Scheduler}.
*
* @param the value type - * @param sources an array of ObservableSources that need to be eagerly concatenated - * @return the new ObservableSource instance with the specified concatenation behavior + * @param sources an array of {@code ObservableSource}s that need to be eagerly concatenated + * @return the new {@code Observable} instance with the specified concatenation behavior * @since 2.0 */ @CheckReturnValue @@ -1274,23 +1311,23 @@ public static Observable concatArrayEager(@NonNull ObservableSource * *

* Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the - * source ObservableSources. The operator buffers the values emitted by these ObservableSources and then drains them + * {@code ObservableSource}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them * in order, each one after the previous one completes. *

*
Scheduler:
*
This method does not operate by default on a particular {@link Scheduler}.
*
* @param the value type - * @param sources an array of ObservableSources that need to be eagerly concatenated + * @param sources an array of {@code ObservableSource}s that need to be eagerly concatenated * @param maxConcurrency the maximum number of concurrent subscriptions at a time, {@link Integer#MAX_VALUE} * is interpreted as indication to subscribe to all sources at once - * @param prefetch the number of elements to prefetch from each ObservableSource source - * @return the new ObservableSource instance with the specified concatenation behavior + * @param bufferSize the number of elements expected from each {@code ObservableSource} to be buffered + * @return the new {@code Observable} instance with the specified concatenation behavior * @since 2.0 */ @SuppressWarnings({ "rawtypes", "unchecked" }) @@ -1298,8 +1335,8 @@ public static Observable concatArrayEager(@NonNull ObservableSource Observable concatArrayEager(int maxConcurrency, int prefetch, @NonNull ObservableSource... sources) { - return fromArray(sources).concatMapEagerDelayError((Function)Functions.identity(), false, maxConcurrency, prefetch); + public static Observable concatArrayEager(int maxConcurrency, int bufferSize, @NonNull ObservableSource... sources) { + return fromArray(sources).concatMapEagerDelayError((Function)Functions.identity(), false, maxConcurrency, bufferSize); } /** @@ -1309,7 +1346,7 @@ public static Observable concatArrayEager(int maxConcurrency, int prefetc * *

* Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the - * source {@code ObservableSource}s. The operator buffers the values emitted by these {@code ObservableSource}s + * {@code ObservableSource}s. The operator buffers the values emitted by these {@code ObservableSource}s * and then drains them in order, each one after the previous one completes. *

*
Scheduler:
@@ -1317,7 +1354,7 @@ public static Observable concatArrayEager(int maxConcurrency, int prefetc *
* @param the value type * @param sources an array of {@code ObservableSource}s that need to be eagerly concatenated - * @return the new Observable instance with the specified concatenation behavior + * @return the new {@code Observable} instance with the specified concatenation behavior * @since 2.2.1 - experimental */ @CheckReturnValue @@ -1335,7 +1372,7 @@ public static Observable concatArrayEagerDelayError(@NonNull ObservableSo * *

* Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the - * source {@code ObservableSource}s. The operator buffers the values emitted by these {@code ObservableSource}s + * {@code ObservableSource}s. The operator buffers the values emitted by these {@code ObservableSource}s * and then drains them in order, each one after the previous one completes. *

*
Scheduler:
@@ -1345,8 +1382,8 @@ public static Observable concatArrayEagerDelayError(@NonNull ObservableSo * @param sources an array of {@code ObservableSource}s that need to be eagerly concatenated * @param maxConcurrency the maximum number of concurrent subscriptions at a time, {@link Integer#MAX_VALUE} * is interpreted as indication to subscribe to all sources at once - * @param prefetch the number of elements to prefetch from each {@code ObservableSource} source - * @return the new Observable instance with the specified concatenation behavior + * @param bufferSize the number of elements expected from each {@code ObservableSource} to be buffered + * @return the new {@code Observable} instance with the specified concatenation behavior * @since 2.2.1 - experimental */ @SuppressWarnings({ "rawtypes", "unchecked" }) @@ -1354,13 +1391,14 @@ public static Observable concatArrayEagerDelayError(@NonNull ObservableSo @SchedulerSupport(SchedulerSupport.NONE) @NonNull @SafeVarargs - public static Observable concatArrayEagerDelayError(int maxConcurrency, int prefetch, @NonNull ObservableSource... sources) { - return fromArray(sources).concatMapEagerDelayError((Function)Functions.identity(), true, maxConcurrency, prefetch); + public static Observable concatArrayEagerDelayError(int maxConcurrency, int bufferSize, @NonNull ObservableSource... sources) { + return fromArray(sources).concatMapEagerDelayError((Function)Functions.identity(), true, maxConcurrency, bufferSize); } /** - * Concatenates the Iterable sequence of ObservableSources into a single sequence by subscribing to each ObservableSource, - * one after the other, one at a time and delays any errors till the all inner ObservableSources terminate. + * Concatenates the {@link Iterable} sequence of {@link ObservableSource}s into a single {@code Observable} sequence + * by subscribing to each {@code ObservableSource}, one after the other, one at a time and delays any errors till + * the all inner {@code ObservableSource}s terminate. *

* *

@@ -1369,8 +1407,9 @@ public static Observable concatArrayEagerDelayError(int maxConcurrency, i *
* * @param the common element base type - * @param sources the Iterable sequence of ObservableSources - * @return the new ObservableSource with the concatenating behavior + * @param sources the {@code Iterable} sequence of {@code ObservableSource}s + * @return the new {@code Observable} with the concatenating behavior + * @throws NullPointerException if {@code sources} is {@code null} */ @CheckReturnValue @NonNull @@ -1381,8 +1420,9 @@ public static Observable concatDelayError(@NonNull Iterable * *
@@ -1391,8 +1431,8 @@ public static Observable concatDelayError(@NonNull Iterable * * @param the common element base type - * @param sources the ObservableSource sequence of ObservableSources - * @return the new ObservableSource with the concatenating behavior + * @param sources the {@code ObservableSource} sequence of {@code ObservableSource}s + * @return the new {@code Observable} with the concatenating behavior */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -1402,8 +1442,8 @@ public static Observable concatDelayError(@NonNull ObservableSource * *
@@ -1412,28 +1452,30 @@ public static Observable concatDelayError(@NonNull ObservableSource * * @param the common element base type - * @param sources the ObservableSource sequence of ObservableSources - * @param prefetch the number of elements to prefetch from the outer ObservableSource - * @param tillTheEnd if true exceptions from the outer and all inner ObservableSources are delayed to the end - * if false, exception from the outer ObservableSource is delayed till the current ObservableSource terminates - * @return the new ObservableSource with the concatenating behavior + * @param sources the {@code ObservableSource} sequence of {@code ObservableSource}s + * @param bufferSize the number of inner {@code ObservableSource}s expected to be buffered + * @param tillTheEnd if {@code true}, exceptions from the outer and all inner {@code ObservableSource}s are delayed to the end + * if {@code false}, exception from the outer {@code ObservableSource} is delayed till the active {@code ObservableSource} terminates + * @return the new {@code Observable} with the concatenating behavior + * @throws NullPointerException if {@code sources} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive */ @SuppressWarnings({ "rawtypes", "unchecked" }) @CheckReturnValue @NonNull @SchedulerSupport(SchedulerSupport.NONE) - public static Observable concatDelayError(@NonNull ObservableSource> sources, int prefetch, boolean tillTheEnd) { + public static Observable concatDelayError(@NonNull ObservableSource> sources, int bufferSize, boolean tillTheEnd) { Objects.requireNonNull(sources, "sources is null"); - ObjectHelper.verifyPositive(prefetch, "prefetch is null"); - return RxJavaPlugins.onAssembly(new ObservableConcatMap(sources, Functions.identity(), prefetch, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY)); + ObjectHelper.verifyPositive(bufferSize, "bufferSize is null"); + return RxJavaPlugins.onAssembly(new ObservableConcatMap(sources, Functions.identity(), bufferSize, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY)); } /** - * Concatenates an ObservableSource sequence of ObservableSources eagerly into a single stream of values. + * Concatenates an {@link ObservableSource} sequence of {@code ObservableSource}s eagerly into a single stream of values. *

* Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the - * emitted source ObservableSources as they are observed. The operator buffers the values emitted by these - * ObservableSources and then drains them in order, each one after the previous one completes. + * emitted source {@code ObservableSource}s as they are observed. The operator buffers the values emitted by these + * {@code ObservableSource}s and then drains them in order, each one after the previous one completes. *

* *

@@ -1441,8 +1483,9 @@ public static Observable concatDelayError(@NonNull ObservableSourceThis method does not operate by default on a particular {@link Scheduler}. *
* @param the value type - * @param sources a sequence of ObservableSources that need to be eagerly concatenated - * @return the new ObservableSource instance with the specified concatenation behavior + * @param sources a sequence of {@code ObservableSource}s that need to be eagerly concatenated + * @return the new {@code Observable} instance with the specified concatenation behavior + * @throws NullPointerException if {@code sources} is {@code null} * @since 2.0 */ @CheckReturnValue @@ -1453,11 +1496,11 @@ public static Observable concatEager(@NonNull ObservableSource * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the - * emitted source ObservableSources as they are observed. The operator buffers the values emitted by these - * ObservableSources and then drains them in order, each one after the previous one completes. + * emitted source {@code ObservableSource}s as they are observed. The operator buffers the values emitted by these + * {@code ObservableSource}s and then drains them in order, each one after the previous one completes. *

* *

@@ -1465,26 +1508,28 @@ public static Observable concatEager(@NonNull ObservableSourceThis method does not operate by default on a particular {@link Scheduler}. *
* @param the value type - * @param sources a sequence of ObservableSources that need to be eagerly concatenated - * @param maxConcurrency the maximum number of concurrently running inner ObservableSources; {@link Integer#MAX_VALUE} - * is interpreted as all inner ObservableSources can be active at the same time - * @param prefetch the number of elements to prefetch from each inner ObservableSource source - * @return the new ObservableSource instance with the specified concatenation behavior + * @param sources a sequence of {@code ObservableSource}s that need to be eagerly concatenated + * @param maxConcurrency the maximum number of concurrently running inner {@code ObservableSource}s; {@link Integer#MAX_VALUE} + * is interpreted as all inner {@code ObservableSource}s can be active at the same time + * @param bufferSize the number of inner {@code ObservableSource} expected to be buffered + * @return the new {@code Observable} instance with the specified concatenation behavior + * @throws NullPointerException if {@code sources} is {@code null} + * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive * @since 2.0 */ @SuppressWarnings({ "unchecked", "rawtypes" }) @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @NonNull - public static Observable concatEager(@NonNull ObservableSource> sources, int maxConcurrency, int prefetch) { - return wrap(sources).concatMapEager((Function)Functions.identity(), maxConcurrency, prefetch); + public static Observable concatEager(@NonNull ObservableSource> sources, int maxConcurrency, int bufferSize) { + return wrap(sources).concatMapEager((Function)Functions.identity(), maxConcurrency, bufferSize); } /** - * Concatenates a sequence of ObservableSources eagerly into a single stream of values. + * Concatenates a sequence of {@link ObservableSource}s eagerly into a single stream of values. *

* Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the - * source ObservableSources. The operator buffers the values emitted by these ObservableSources and then drains them + * {@code ObservableSource}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them * in order, each one after the previous one completes. *

* @@ -1493,8 +1538,8 @@ public static Observable concatEager(@NonNull ObservableSourceThis method does not operate by default on a particular {@link Scheduler}. *

* @param the value type - * @param sources a sequence of ObservableSources that need to be eagerly concatenated - * @return the new ObservableSource instance with the specified concatenation behavior + * @param sources a sequence of {@code ObservableSource}s that need to be eagerly concatenated + * @return the new {@code Observable} instance with the specified concatenation behavior * @since 2.0 */ @CheckReturnValue @@ -1505,10 +1550,10 @@ public static Observable concatEager(@NonNull Iterable * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the - * source ObservableSources. The operator buffers the values emitted by these ObservableSources and then drains them + * {@code ObservableSource}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them * in order, each one after the previous one completes. *

* @@ -1517,23 +1562,23 @@ public static Observable concatEager(@NonNull IterableThis method does not operate by default on a particular {@link Scheduler}. *

* @param the value type - * @param sources a sequence of ObservableSources that need to be eagerly concatenated - * @param maxConcurrency the maximum number of concurrently running inner ObservableSources; {@link Integer#MAX_VALUE} - * is interpreted as all inner ObservableSources can be active at the same time - * @param prefetch the number of elements to prefetch from each inner ObservableSource source - * @return the new ObservableSource instance with the specified concatenation behavior + * @param sources a sequence of {@code ObservableSource}s that need to be eagerly concatenated + * @param maxConcurrency the maximum number of concurrently running inner {@code ObservableSource}s; {@link Integer#MAX_VALUE} + * is interpreted as all inner {@code ObservableSource}s can be active at the same time + * @param bufferSize the number of elements expected from each inner {@code ObservableSource} to be buffered + * @return the new {@code Observable} instance with the specified concatenation behavior * @since 2.0 */ @SuppressWarnings({ "unchecked", "rawtypes" }) @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @NonNull - public static Observable concatEager(@NonNull Iterable> sources, int maxConcurrency, int prefetch) { - return fromIterable(sources).concatMapEagerDelayError((Function)Functions.identity(), false, maxConcurrency, prefetch); + public static Observable concatEager(@NonNull Iterable> sources, int maxConcurrency, int bufferSize) { + return fromIterable(sources).concatMapEagerDelayError((Function)Functions.identity(), false, maxConcurrency, bufferSize); } /** - * Provides an API (via a cold Observable) that bridges the reactive world with the callback-style world. + * Provides an API (via a cold {@code Observable}) that bridges the reactive world with the callback-style world. *

* Example: * 


@@ -1563,12 +1608,12 @@ public static  Observable concatEager(@NonNull Iterable
      * 
      * 

-     * You should call the ObservableEmitter's onNext, onError and onComplete methods in a serialized fashion. The
+     * You should call the {@code ObservableEmitter}'s {@code onNext}, {@code onError} and {@code onComplete} methods in a serialized fashion. The
      * rest of its methods are thread-safe.
      * 

      *  
Scheduler:

@@ -1576,8 +1621,9 @@ public static  Observable concatEager(@NonNull Iterable
      *
      * @param  the element type
-     * @param source the emitter that is called when an Observer subscribes to the returned {@code Observable}
-     * @return the new Observable instance
+     * @param source the emitter that is called when an {@code Observer} subscribes to the returned {@code Observable}
+     * @return the new {@code Observable} instance
+     * @throws NullPointerException if {@code source} is {@code null}
      * @see ObservableOnSubscribe
      * @see ObservableEmitter
      * @see Cancellable
@@ -1591,14 +1637,14 @@ public static  Observable create(@NonNull ObservableOnSubscribe source)
     }
 
     /**
-     * Returns an Observable that calls an ObservableSource factory to create an ObservableSource for each new Observer
-     * that subscribes. That is, for each subscriber, the actual ObservableSource that subscriber observes is
+     * Returns an {@code Observable} that calls an {@link ObservableSource} factory to create an {@code ObservableSource} for each new {@link Observer}
+     * that subscribes. That is, for each subscriber, the actual {@code ObservableSource} that subscriber observes is
      * determined by the factory function.
      * 

      * 
      * 

-     * The defer Observer allows you to defer or delay emitting items from an ObservableSource until such time as an
-     * Observer subscribes to the ObservableSource. This allows an {@link Observer} to easily obtain updates or a
+     * The {@code defer} operator allows you to defer or delay emitting items from an {@code ObservableSource} until such time as an
+     * {@code Observer} subscribes to the {@code ObservableSource}. This allows an {@code Observer} to easily obtain updates or a
      * refreshed version of the sequence.
      * 

      *  
Scheduler:

@@ -1606,12 +1652,13 @@ public static  Observable create(@NonNull ObservableOnSubscribe source)
      * 

      *
      * @param supplier
-     *            the ObservableSource factory function to invoke for each {@link Observer} that subscribes to the
-     *            resulting ObservableSource
+     *            the {@code ObservableSource} factory function to invoke for each {@code Observer} that subscribes to the
+     *            resulting {@code Observable}
      * @param 
-     *            the type of the items emitted by the ObservableSource
-     * @return an Observable whose {@link Observer}s' subscriptions trigger an invocation of the given
-     *         ObservableSource factory function
+     *            the type of the items emitted by the {@code ObservableSource}
+     * @return an {@code Observable} whose {@code Observer}s' subscriptions trigger an invocation of the given
+     *         {@code ObservableSource} factory function
+     * @throws NullPointerException if {@code supplier} is {@code null}
      * @see ReactiveX operators documentation: Defer
      */
     @CheckReturnValue
@@ -1623,7 +1670,7 @@ public static  Observable defer(@NonNull Supplier
      * 
@@ -1633,9 +1680,9 @@ public static  Observable defer(@NonNull Supplier
      *
      * @param 
-     *            the type of the items (ostensibly) emitted by the ObservableSource
-     * @return an Observable that emits no items to the {@link Observer} but immediately invokes the
-     *         {@link Observer}'s {@link Observer#onComplete() onComplete} method
+     *            the type of the items (ostensibly) emitted by the {@code Observable}
+     * @return an {@code Observable} that emits no items to the {@code Observer} but immediately invokes the
+     *         {@code Observer}'s {@link Observer#onComplete() onComplete} method
      * @see ReactiveX operators documentation: Empty
      */
     @CheckReturnValue
@@ -1647,8 +1694,8 @@ public static  Observable empty() {
     }
 
     /**
-     * Returns an Observable that invokes an {@link Observer}'s {@link Observer#onError onError} method when the
-     * Observer subscribes to it.
+     * Returns an {@code Observable} that invokes an {@link Observer}'s {@link Observer#onError onError} method when the
+     * {@code Observer} subscribes to it.
      * 

      * 
      * 

@@ -1657,11 +1704,12 @@ public static  Observable empty() {
      * 

      *
      * @param errorSupplier
-     *            a Supplier factory to return a Throwable for each individual Observer
+     *            a {@link Supplier} factory to return a {@link Throwable} for each individual {@code Observer}
      * @param 
-     *            the type of the items (ostensibly) emitted by the ObservableSource
-     * @return an Observable that invokes the {@link Observer}'s {@link Observer#onError onError} method when
-     *         the Observer subscribes to it
+     *            the type of the items (ostensibly) emitted by the {@code Observable}
+     * @return an {@code Observable} that invokes the {@code Observer}'s {@link Observer#onError onError} method when
+     *         the {@code Observer} subscribes to it
+     * @throws NullPointerException if {@code errorSupplier} is {@code null}
      * @see ReactiveX operators documentation: Throw
      */
     @CheckReturnValue
@@ -1673,8 +1721,8 @@ public static  Observable error(@NonNull Supplier err
     }
 
     /**
-     * Returns an Observable that invokes an {@link Observer}'s {@link Observer#onError onError} method when the
-     * Observer subscribes to it.
+     * Returns an {@code Observable} that invokes an {@link Observer}'s {@link Observer#onError onError} method when the
+     * {@code Observer} subscribes to it.
      * 

      * 
      * 

@@ -1683,11 +1731,12 @@ public static  Observable error(@NonNull Supplier err
      * 

      *
      * @param exception
-     *            the particular Throwable to pass to {@link Observer#onError onError}
+     *            the particular {@link Throwable} to pass to {@link Observer#onError onError}
      * @param 
-     *            the type of the items (ostensibly) emitted by the ObservableSource
-     * @return an Observable that invokes the {@link Observer}'s {@link Observer#onError onError} method when
-     *         the Observer subscribes to it
+     *            the type of the items (ostensibly) emitted by the {@code Observable}
+     * @return an {@code Observable} that invokes the {@code Observer}'s {@link Observer#onError onError} method when
+     *         the {@code Observer} subscribes to it
+     * @throws NullPointerException if {@code exception} is {@code null}
      * @see ReactiveX operators documentation: Throw
      */
     @CheckReturnValue
@@ -1699,7 +1748,7 @@ public static  Observable error(@NonNull Throwable exception) {
     }
 
     /**
-     * Converts an Array into an ObservableSource that emits the items in the Array.
+     * Converts an array into an {@link ObservableSource} that emits the items in the array.
      * 

      * 
      * 

@@ -1710,8 +1759,9 @@ public static  Observable error(@NonNull Throwable exception) {
      * @param items
      *            the array of elements
      * @param 
-     *            the type of items in the Array and the type of items to be emitted by the resulting ObservableSource
-     * @return an Observable that emits each item in the source Array
+     *            the type of items in the array and the type of items to be emitted by the resulting {@code Observable}
+     * @return an {@code Observable} that emits each item in the source array
+     * @throws NullPointerException if {@code items} is {@code null}
      * @see ReactiveX operators documentation: From
      */
     @CheckReturnValue
@@ -1730,30 +1780,31 @@ public static  Observable fromArray(@NonNull T... items) {
     }
 
     /**
-     * Returns an Observable that, when an observer subscribes to it, invokes a function you specify and then
+     * Returns an {@code Observable} that, when an observer subscribes to it, invokes a function you specify and then
      * emits the value returned from that function.
      * 

      * 
      * 

      * This allows you to defer the execution of the function you specify until an observer subscribes to the
-     * ObservableSource. That is to say, it makes the function "lazy."
+     * {@code Observable}. That is to say, it makes the function "lazy."
      * 

      *   
Scheduler:

      *   
{@code fromCallable} does not operate by default on a particular {@link Scheduler}.

      *   
Error handling:

      *   
 If the {@link Callable} throws an exception, the respective {@link Throwable} is
      *   delivered to the downstream via {@link Observer#onError(Throwable)},
-     *   except when the downstream has disposed this {@code Observable} source.
+     *   except when the downstream has disposed the current {@code Observable} source.
      *   In this latter case, the {@code Throwable} is delivered to the global error handler via
-     *   {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
+     *   {@link RxJavaPlugins#onError(Throwable)} as an {@link UndeliverableException}.
      *   

      * 

-     * @param supplier
+     * @param callable
      *         a function, the execution of which should be deferred; {@code fromCallable} will invoke this
-     *         function only when an observer subscribes to the ObservableSource that {@code fromCallable} returns
+     *         function only when an observer subscribes to the {@code Observable} that {@code fromCallable} returns
      * @param 
-     *         the type of the item emitted by the ObservableSource
-     * @return an Observable whose {@link Observer}s' subscriptions trigger an invocation of the given function
+     *         the type of the item returned by the {@code Callable} and emitted by the {@code Observable}
+     * @return an {@code Observable} whose {@link Observer}s' subscriptions trigger an invocation of the given function
+     * @throws NullPointerException if {@code callable} is {@code null}
      * @see #defer(Supplier)
      * @see #fromSupplier(Supplier)
      * @since 2.0
@@ -1761,35 +1812,39 @@ public static  Observable fromArray(@NonNull T... items) {
     @CheckReturnValue
     @NonNull
     @SchedulerSupport(SchedulerSupport.NONE)
-    public static  Observable fromCallable(@NonNull Callable supplier) {
-        Objects.requireNonNull(supplier, "supplier is null");
-        return RxJavaPlugins.onAssembly(new ObservableFromCallable<>(supplier));
+    public static  Observable fromCallable(@NonNull Callable callable) {
+        Objects.requireNonNull(callable, "callable is null");
+        return RxJavaPlugins.onAssembly(new ObservableFromCallable<>(callable));
     }
 
     /**
-     * Converts a {@link Future} into an ObservableSource.
+     * Converts a {@link Future} into an {@code Observable}.
      * 

      * 
      * 

-     * You can convert any object that supports the {@link Future} interface into an ObservableSource that emits the
-     * return value of the {@link Future#get} method of that object, by passing the object into the {@code from}
-     * method.
-     * 

-     * Important note: This ObservableSource is blocking; you cannot dispose it.
+     * The operator calls {@link Future#get()}, which is a blocking method, on the subscription thread.
+     * It is recommended applying {@link #subscribeOn(Scheduler)} to move this blocking wait to a
+     * background thread, and if the {@link Scheduler} supports it, interrupt the wait when the flow
+     * is disposed.
      * 

-     * Unlike 1.x, disposing the Observable won't cancel the future. If necessary, one can use composition to achieve the
+     * Unlike 1.x, disposing the {@code Observable} won't cancel the future. If necessary, one can use composition to achieve the
      * cancellation effect: {@code futureObservableSource.doOnDispose(() -> future.cancel(true));}.
+     * 

+     * Also note that this operator will consume a {@link CompletionStage}-based {@code Future} subclass (such as
+     * {@link CompletableFuture}) in a blocking manner as well. Use the {@link #fromCompletionStage(CompletionStage)}
+     * operator to convert and consume such sources in a non-blocking fashion instead.
      * 

      *  
Scheduler:

-     *  
{@code fromFuture} does not operate by default on a particular {@link Scheduler}.

+     *  
{@code fromFuture} does not operate by default on a particular {@code Scheduler}.

      * 

      *
      * @param future
-     *            the source {@link Future}
+     *            the source {@code Future}
      * @param 
-     *            the type of object that the {@link Future} returns, and also the type of item to be emitted by
-     *            the resulting ObservableSource
-     * @return an Observable that emits the item from the source {@link Future}
+     *            the type of object that the {@code Future} returns, and also the type of item to be emitted by
+     *            the resulting {@code Observable}
+     * @return an {@code Observable} that emits the item from the source {@code Future}
+     * @throws NullPointerException if {@code future} is {@code null}
      * @see ReactiveX operators documentation: From
      */
     @CheckReturnValue
@@ -1801,33 +1856,37 @@ public static  Observable fromFuture(@NonNull Future future)
     }
 
     /**
-     * Converts a {@link Future} into an ObservableSource, with a timeout on the Future.
+     * Converts a {@link Future} into an {@code Observable}, with a timeout on the {@code Future}.
      * 

      * 
      * 

-     * You can convert any object that supports the {@link Future} interface into an ObservableSource that emits the
-     * return value of the {@link Future#get} method of that object, by passing the object into the {@code from}
-     * method.
+     * The operator calls {@link Future#get(long, TimeUnit)}, which is a blocking method, on the subscription thread.
+     * It is recommended applying {@link #subscribeOn(Scheduler)} to move this blocking wait to a
+     * background thread, and if the {@link Scheduler} supports it, interrupt the wait when the flow
+     * is disposed.
      * 

-     * Unlike 1.x, disposing the Observable won't cancel the future. If necessary, one can use composition to achieve the
+     * Unlike 1.x, disposing the {@code Observable} won't cancel the future. If necessary, one can use composition to achieve the
      * cancellation effect: {@code futureObservableSource.doOnDispose(() -> future.cancel(true));}.
      * 

-     * Important note: This ObservableSource is blocking; you cannot dispose it.
+     * Also note that this operator will consume a {@link CompletionStage}-based {@code Future} subclass (such as
+     * {@link CompletableFuture}) in a blocking manner as well. Use the {@link #fromCompletionStage(CompletionStage)}
+     * operator to convert and consume such sources in a non-blocking fashion instead.
      * 

      *  
Scheduler:

-     *  
{@code fromFuture} does not operate by default on a particular {@link Scheduler}.

+     *  
{@code fromFuture} does not operate by default on a particular {@code Scheduler}.

      * 

      *
      * @param future
-     *            the source {@link Future}
+     *            the source {@code Future}
      * @param timeout
      *            the maximum time to wait before calling {@code get}
      * @param unit
      *            the {@link TimeUnit} of the {@code timeout} argument
      * @param 
-     *            the type of object that the {@link Future} returns, and also the type of item to be emitted by
-     *            the resulting ObservableSource
-     * @return an Observable that emits the item from the source {@link Future}
+     *            the type of object that the {@code Future} returns, and also the type of item to be emitted by
+     *            the resulting {@code Observable}
+     * @return an {@code Observable} that emits the item from the source {@code Future}
+     * @throws NullPointerException if {@code future} or {@code unit} is {@code null}
      * @see ReactiveX operators documentation: From
      */
     @CheckReturnValue
@@ -1840,7 +1899,7 @@ public static  Observable fromFuture(@NonNull Future future,
     }
 
     /**
-     * Converts an {@link Iterable} sequence into an ObservableSource that emits the items in the sequence.
+     * Converts an {@link Iterable} sequence into an {@code Observable} that emits the items in the sequence.
      * 

      * 
      * 

@@ -1849,11 +1908,12 @@ public static  Observable fromFuture(@NonNull Future future,
      * 

      *
      * @param source
-     *            the source {@link Iterable} sequence
+     *            the source {@code Iterable} sequence
      * @param 
-     *            the type of items in the {@link Iterable} sequence and the type of items to be emitted by the
-     *            resulting ObservableSource
-     * @return an Observable that emits each item in the source {@link Iterable} sequence
+     *            the type of items in the {@code Iterable} sequence and the type of items to be emitted by the
+     *            resulting {@code Observable}
+     * @return an {@code Observable} that emits each item in the source {@code Iterable} sequence
+     * @throws NullPointerException if {@code source} is {@code null}
      * @see ReactiveX operators documentation: From
      * @see #fromStream(Stream)
      */
@@ -1866,18 +1926,18 @@ public static  Observable fromIterable(@NonNull Iterable sour
     }
 
     /**
-     * Converts an arbitrary Reactive-Streams Publisher into an Observable.
+     * Converts an arbitrary Reactive Streams {@link Publisher} into an {@code Observable}.
      * 

      * 
      * 

-     * The {@link Publisher} must follow the
+     * The {@code Publisher} must follow the
      * Reactive-Streams specification.
      * Violating the specification may result in undefined behavior.
      * 

      * If possible, use {@link #create(ObservableOnSubscribe)} to create a
      * source-like {@code Observable} instead.
      * 

-     * Note that even though {@link Publisher} appears to be a functional interface, it
+     * Note that even though {@code Publisher} appears to be a functional interface, it
      * is not recommended to implement it through a lambda as the specification requires
      * state management that is not achievable with a stateless lambda.
      * 

@@ -1888,9 +1948,9 @@ public static  Observable fromIterable(@NonNull Iterable sour
      *  
{@code fromPublisher} does not operate by default on a particular {@link Scheduler}.

      * 

      * @param  the value type of the flow
-     * @param publisher the Publisher to convert
-     * @return the new Observable instance
-     * @throws NullPointerException if publisher is null
+     * @param publisher the {@code Publisher} to convert
+     * @return the new {@code Observable} instance
+     * @throws NullPointerException if {@code publisher} is {@code null}
      * @see #create(ObservableOnSubscribe)
      */
     @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
@@ -1903,30 +1963,31 @@ public static  Observable fromPublisher(@NonNull Publisher pu
     }
 
     /**
-     * Returns an Observable that, when an observer subscribes to it, invokes a supplier function you specify and then
+     * Returns an {@code Observable} that, when an observer subscribes to it, invokes a supplier function you specify and then
      * emits the value returned from that function.
      * 

      * 
      * 

      * This allows you to defer the execution of the function you specify until an observer subscribes to the
-     * ObservableSource. That is to say, it makes the function "lazy."
+     * {@code Observable}. That is to say, it makes the function "lazy."
      * 

      *   
Scheduler:

      *   
{@code fromSupplier} does not operate by default on a particular {@link Scheduler}.

      *   
Error handling:

      *   
 If the {@link Supplier} throws an exception, the respective {@link Throwable} is
      *   delivered to the downstream via {@link Observer#onError(Throwable)},
-     *   except when the downstream has disposed this {@code Observable} source.
+     *   except when the downstream has disposed the current {@code Observable} source.
      *   In this latter case, the {@code Throwable} is delivered to the global error handler via
-     *   {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
+     *   {@link RxJavaPlugins#onError(Throwable)} as an {@link UndeliverableException}.
      *   

      * 

      * @param supplier
      *         a function, the execution of which should be deferred; {@code fromSupplier} will invoke this
-     *         function only when an observer subscribes to the ObservableSource that {@code fromSupplier} returns
+     *         function only when an observer subscribes to the {@code Observable} that {@code fromSupplier} returns
      * @param 
-     *         the type of the item emitted by the ObservableSource
-     * @return an Observable whose {@link Observer}s' subscriptions trigger an invocation of the given function
+     *         the type of the item emitted by the {@code Observable}
+     * @return an {@code Observable} whose {@link Observer}s' subscriptions trigger an invocation of the given function
+     * @throws NullPointerException if {@code supplier} is {@code null}
      * @see #defer(Supplier)
      * @see #fromCallable(Callable)
      * @since 3.0.0
@@ -1954,11 +2015,12 @@ public static  Observable fromSupplier(@NonNull Supplier supp
      * 

      *
      * @param  the generated value type
-     * @param generator the Consumer called whenever a particular downstream Observer has
-     * requested a value. The callback then should call {@code onNext}, {@code onError} or
-     * {@code onComplete} to signal a value or a terminal event. Signalling multiple {@code onNext}
-     * in a call will make the operator signal {@code IllegalStateException}.
-     * @return the new Observable instance
+     * @param generator the {@link Consumer} called in a loop after a downstream {@link Observer} has
+     * subscribed. The callback then should call {@code onNext}, {@code onError} or
+     * {@code onComplete} to signal a value or a terminal event. Signaling multiple {@code onNext}
+     * in a call will make the operator signal {@link IllegalStateException}.
+     * @return the new {@code Observable} instance
+     * @throws NullPointerException if {@code generator} is {@code null}
      */
     @CheckReturnValue
     @NonNull
@@ -1983,14 +2045,15 @@ public static  Observable generate(@NonNull Consumer> generator
      *  
{@code generate} does not operate by default on a particular {@link Scheduler}.

      * 

      *
-     * @param  the type of the per-Observer state
+     * @param  the type of the per-{@link Observer} state
      * @param  the generated value type
-     * @param initialState the Supplier to generate the initial state for each Observer
-     * @param generator the Consumer called with the current state whenever a particular downstream Observer has
-     * requested a value. The callback then should call {@code onNext}, {@code onError} or
-     * {@code onComplete} to signal a value or a terminal event. Signalling multiple {@code onNext}
-     * in a call will make the operator signal {@code IllegalStateException}.
-     * @return the new Observable instance
+     * @param initialState the {@link Supplier} to generate the initial state for each {@code Observer}
+     * @param generator the {@link BiConsumer} called in a loop after a downstream {@code Observer} has
+     * subscribed. The callback then should call {@code onNext}, {@code onError} or
+     * {@code onComplete} to signal a value or a terminal event. Signaling multiple {@code onNext}
+     * in a call will make the operator signal {@link IllegalStateException}.
+     * @return the new {@code Observable} instance
+     * @throws NullPointerException if {@code initialState} or {@code generator} is {@code null}
      */
     @CheckReturnValue
     @NonNull
@@ -2014,16 +2077,17 @@ public static  Observable generate(@NonNull Supplier initialState, @
      *  
{@code generate} does not operate by default on a particular {@link Scheduler}.

      *
* - * @param the type of the per-Observer state + * @param the type of the per-{@link Observer} state * @param the generated value type - * @param initialState the Supplier to generate the initial state for each Observer - * @param generator the Consumer called with the current state whenever a particular downstream Observer has - * requested a value. The callback then should call {@code onNext}, {@code onError} or - * {@code onComplete} to signal a value or a terminal event. Signalling multiple {@code onNext} - * in a call will make the operator signal {@code IllegalStateException}. - * @param disposeState the Consumer that is called with the current state when the generator + * @param initialState the {@link Supplier} to generate the initial state for each {@code Observer} + * @param generator the {@link BiConsumer} called in a loop after a downstream {@code Observer} has + * subscribed. The callback then should call {@code onNext}, {@code onError} or + * {@code onComplete} to signal a value or a terminal event. Signaling multiple {@code onNext} + * in a call will make the operator signal {@link IllegalStateException}. + * @param disposeState the {@link Consumer} that is called with the current state when the generator * terminates the sequence or it gets disposed - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code initialState}, {@code generator} or {@code disposeState} is {@code null} */ @CheckReturnValue @NonNull @@ -2050,15 +2114,16 @@ public static Observable generate( *
{@code generate} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the type of the per-Observer state + * @param the type of the per-{@link Observer} state * @param the generated value type - * @param initialState the Supplier to generate the initial state for each Observer - * @param generator the Function called with the current state whenever a particular downstream Observer has - * requested a value. The callback then should call {@code onNext}, {@code onError} or + * @param initialState the {@link Supplier} to generate the initial state for each {@code Observer} + * @param generator the {@link BiConsumer} called in a loop after a downstream {@code Observer} has + * subscribed. The callback then should call {@code onNext}, {@code onError} or * {@code onComplete} to signal a value or a terminal event and should return a (new) state for - * the next invocation. Signalling multiple {@code onNext} - * in a call will make the operator signal {@code IllegalStateException}. - * @return the new Observable instance + * the next invocation. Signaling multiple {@code onNext} + * in a call will make the operator signal {@link IllegalStateException}. + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code initialState} or {@code generator} is {@code null} */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -2081,17 +2146,18 @@ public static Observable generate(@NonNull Supplier initialState, @ *
{@code generate} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the type of the per-Observer state + * @param the type of the per-{@link Observer} state * @param the generated value type - * @param initialState the Supplier to generate the initial state for each Observer - * @param generator the Function called with the current state whenever a particular downstream Observer has - * requested a value. The callback then should call {@code onNext}, {@code onError} or + * @param initialState the {@link Supplier} to generate the initial state for each {@code Observer} + * @param generator the {@link BiConsumer} called in a loop after a downstream {@code Observer} has + * subscribed. The callback then should call {@code onNext}, {@code onError} or * {@code onComplete} to signal a value or a terminal event and should return a (new) state for - * the next invocation. Signalling multiple {@code onNext} - * in a call will make the operator signal {@code IllegalStateException}. - * @param disposeState the Consumer that is called with the current state when the generator + * the next invocation. Signaling multiple {@code onNext} + * in a call will make the operator signal {@link IllegalStateException}. + * @param disposeState the {@link Consumer} that is called with the current state when the generator * terminates the sequence or it gets disposed - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code initialState}, {@code generator} or {@code disposeState} is {@code null} */ @CheckReturnValue @NonNull @@ -2105,7 +2171,7 @@ public static Observable generate(@NonNull Supplier initialState, @ } /** - * Returns an Observable that emits a {@code 0L} after the {@code initialDelay} and ever increasing numbers + * Returns an {@code Observable} that emits a {@code 0L} after the {@code initialDelay} and ever increasing numbers * after each {@code period} of time thereafter. *

* @@ -2120,9 +2186,10 @@ public static Observable generate(@NonNull Supplier initialState, @ * the period of time between emissions of the subsequent numbers * @param unit * the time unit for both {@code initialDelay} and {@code period} - * @return an Observable that emits a 0L after the {@code initialDelay} and ever increasing numbers after + * @return an {@code Observable} that emits a 0L after the {@code initialDelay} and ever increasing numbers after * each {@code period} of time thereafter * @see ReactiveX operators documentation: Interval + * @throws NullPointerException if {@code unit} is {@code null} * @since 1.0.12 */ @CheckReturnValue @@ -2133,13 +2200,13 @@ public static Observable interval(long initialDelay, long period, @NonNull } /** - * Returns an Observable that emits a {@code 0L} after the {@code initialDelay} and ever increasing numbers + * Returns an {@code Observable} that emits a {@code 0L} after the {@code initialDelay} and ever increasing numbers * after each {@code period} of time thereafter, on a specified {@link Scheduler}. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param initialDelay @@ -2149,11 +2216,12 @@ public static Observable interval(long initialDelay, long period, @NonNull * @param unit * the time unit for both {@code initialDelay} and {@code period} * @param scheduler - * the Scheduler on which the waiting happens and items are emitted - * @return an Observable that emits a 0L after the {@code initialDelay} and ever increasing numbers after - * each {@code period} of time thereafter, while running on the given Scheduler + * the {@code Scheduler} on which the waiting happens and items are emitted + * @return an {@code Observable} that emits a 0L after the {@code initialDelay} and ever increasing numbers after + * each {@code period} of time thereafter, while running on the given {@code Scheduler} * @see ReactiveX operators documentation: Interval * @since 1.0.12 + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} */ @CheckReturnValue @NonNull @@ -2166,7 +2234,7 @@ public static Observable interval(long initialDelay, long period, @NonNull } /** - * Returns an Observable that emits a sequential number every specified interval of time. + * Returns an {@code Observable} that emits a sequential number every specified interval of time. *

* *

@@ -2178,7 +2246,7 @@ public static Observable interval(long initialDelay, long period, @NonNull * the period size in time units (see below) * @param unit * time units to use for the interval size - * @return an Observable that emits a sequential number each time interval + * @return an {@code Observable} that emits a sequential number each time interval * @see ReactiveX operators documentation: Interval */ @CheckReturnValue @@ -2189,13 +2257,13 @@ public static Observable interval(long period, @NonNull TimeUnit unit) { } /** - * Returns an Observable that emits a sequential number every specified interval of time, on a - * specified Scheduler. + * Returns an {@code Observable} that emits a sequential number every specified interval of time, on a + * specified {@link Scheduler}. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param period @@ -2203,8 +2271,8 @@ public static Observable interval(long period, @NonNull TimeUnit unit) { * @param unit * time units to use for the interval size * @param scheduler - * the Scheduler to use for scheduling the items - * @return an Observable that emits a sequential number each time interval + * the {@code Scheduler} to use for scheduling the items + * @return an {@code Observable} that emits a sequential number each time interval * @see ReactiveX operators documentation: Interval */ @CheckReturnValue @@ -2225,11 +2293,11 @@ public static Observable interval(long period, @NonNull TimeUnit unit, @No *
{@code intervalRange} by default operates on the {@link Schedulers#computation() computation} {@link Scheduler}.
*
* @param start that start value of the range - * @param count the number of values to emit in total, if zero, the operator emits an onComplete after the initial delay. - * @param initialDelay the initial delay before signalling the first value (the start) + * @param count the number of values to emit in total, if zero, the operator emits an {@code onComplete} after the initial delay. + * @param initialDelay the initial delay before signaling the first value (the start) * @param period the period between subsequent values - * @param unit the unit of measure of the initialDelay and period amounts - * @return the new Observable instance + * @param unit the unit of measure of the {@code initialDelay} and {@code period} amounts + * @return the new {@code Observable} instance */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.COMPUTATION) @@ -2248,12 +2316,16 @@ public static Observable intervalRange(long start, long count, long initia *
you provide the {@link Scheduler}.
*
* @param start that start value of the range - * @param count the number of values to emit in total, if zero, the operator emits an onComplete after the initial delay. - * @param initialDelay the initial delay before signalling the first value (the start) + * @param count the number of values to emit in total, if zero, the operator emits an {@code onComplete} after the initial delay. + * @param initialDelay the initial delay before signaling the first value (the start) * @param period the period between subsequent values - * @param unit the unit of measure of the initialDelay and period amounts + * @param unit the unit of measure of the {@code initialDelay} and {@code period} amounts * @param scheduler the target scheduler where the values and terminal signals will be emitted - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} + * @throws IllegalArgumentException + * if {@code count} is negative, or if {@code start} + {@code count} − 1 exceeds + * {@link Long#MAX_VALUE} */ @CheckReturnValue @NonNull @@ -2278,12 +2350,12 @@ public static Observable intervalRange(long start, long count, long initia } /** - * Returns an Observable that signals the given (constant reference) item and then completes. + * Returns an {@code Observable} that signals the given (constant reference) item and then completes. *

* *

* Note that the item is taken and re-emitted as is and not computed by any means by {@code just}. Use {@link #fromCallable(Callable)} - * to generate a single item on demand (when {@code Observer}s subscribe to it). + * to generate a single item on demand (when {@link Observer}s subscribe to it). *

* See the multi-parameter overloads of {@code just} to emit more than one (constant reference) items one after the other. * Use {@link #fromArray(Object...)} to emit an arbitrary number of items that are known upfront. @@ -2298,7 +2370,8 @@ public static Observable intervalRange(long start, long count, long initia * the item to emit * @param * the type of that item - * @return an Observable that emits {@code value} as a single item and then completes + * @return an {@code Observable} that emits {@code value} as a single item and then completes + * @throws NullPointerException if {@code item} is {@code null} * @see ReactiveX operators documentation: Just * @see #just(Object, Object) * @see #fromCallable(Callable) @@ -2314,7 +2387,7 @@ public static Observable just(@NonNull T item) { } /** - * Converts two items into an ObservableSource that emits those items. + * Converts two items into an {@code Observable} that emits those items. *

* *

@@ -2328,7 +2401,8 @@ public static Observable just(@NonNull T item) { * second item * @param * the type of these items - * @return an Observable that emits each item + * @return an {@code Observable} that emits each item + * @throws NullPointerException if {@code item1} or {@code item2} is {@code null} * @see ReactiveX operators documentation: Just */ @CheckReturnValue @@ -2342,7 +2416,7 @@ public static Observable just(@NonNull T item1, @NonNull T item2) { } /** - * Converts three items into an ObservableSource that emits those items. + * Converts three items into an {@code Observable} that emits those items. *

* *

@@ -2358,7 +2432,8 @@ public static Observable just(@NonNull T item1, @NonNull T item2) { * third item * @param * the type of these items - * @return an Observable that emits each item + * @return an {@code Observable} that emits each item + * @throws NullPointerException if {@code item1}, {@code item2} or {@code item3} is {@code null} * @see ReactiveX operators documentation: Just */ @CheckReturnValue @@ -2373,7 +2448,7 @@ public static Observable just(@NonNull T item1, @NonNull T item2, @NonNul } /** - * Converts four items into an ObservableSource that emits those items. + * Converts four items into an {@code Observable} that emits those items. *

* *

@@ -2391,7 +2466,8 @@ public static Observable just(@NonNull T item1, @NonNull T item2, @NonNul * fourth item * @param * the type of these items - * @return an Observable that emits each item + * @return an {@code Observable} that emits each item + * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3} or {@code item4} is {@code null} * @see ReactiveX operators documentation: Just */ @CheckReturnValue @@ -2407,7 +2483,7 @@ public static Observable just(@NonNull T item1, @NonNull T item2, @NonNul } /** - * Converts five items into an ObservableSource that emits those items. + * Converts five items into an {@code Observable} that emits those items. *

* *

@@ -2427,7 +2503,9 @@ public static Observable just(@NonNull T item1, @NonNull T item2, @NonNul * fifth item * @param * the type of these items - * @return an Observable that emits each item + * @return an {@code Observable} that emits each item + * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3}, + * {@code item4} or {@code item5} is {@code null} * @see ReactiveX operators documentation: Just */ @CheckReturnValue @@ -2444,7 +2522,7 @@ public static Observable just(@NonNull T item1, @NonNull T item2, @NonNul } /** - * Converts six items into an ObservableSource that emits those items. + * Converts six items into an {@code Observable} that emits those items. *

* *

@@ -2466,7 +2544,9 @@ public static Observable just(@NonNull T item1, @NonNull T item2, @NonNul * sixth item * @param * the type of these items - * @return an Observable that emits each item + * @return an {@code Observable} that emits each item + * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3}, + * {@code item4}, {@code item5} or {@code item6} is {@code null} * @see ReactiveX operators documentation: Just */ @CheckReturnValue @@ -2484,7 +2564,7 @@ public static Observable just(@NonNull T item1, @NonNull T item2, @NonNul } /** - * Converts seven items into an ObservableSource that emits those items. + * Converts seven items into an {@code Observable} that emits those items. *

* *

@@ -2508,7 +2588,10 @@ public static Observable just(@NonNull T item1, @NonNull T item2, @NonNul * seventh item * @param * the type of these items - * @return an Observable that emits each item + * @return an {@code Observable} that emits each item + * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3}, + * {@code item4}, {@code item5}, {@code item6} + * or {@code item7} is {@code null} * @see ReactiveX operators documentation: Just */ @CheckReturnValue @@ -2527,7 +2610,7 @@ public static Observable just(@NonNull T item1, @NonNull T item2, @NonNul } /** - * Converts eight items into an ObservableSource that emits those items. + * Converts eight items into an {@code Observable} that emits those items. *

* *

@@ -2553,7 +2636,10 @@ public static Observable just(@NonNull T item1, @NonNull T item2, @NonNul * eighth item * @param * the type of these items - * @return an Observable that emits each item + * @return an {@code Observable} that emits each item + * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3}, + * {@code item4}, {@code item5}, {@code item6} + * {@code item7} or {@code item8} is {@code null} * @see ReactiveX operators documentation: Just */ @CheckReturnValue @@ -2573,7 +2659,7 @@ public static Observable just(@NonNull T item1, @NonNull T item2, @NonNul } /** - * Converts nine items into an ObservableSource that emits those items. + * Converts nine items into an {@code Observable} that emits those items. *

* *

@@ -2601,7 +2687,10 @@ public static Observable just(@NonNull T item1, @NonNull T item2, @NonNul * ninth item * @param * the type of these items - * @return an Observable that emits each item + * @return an {@code Observable} that emits each item + * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3}, + * {@code item4}, {@code item5}, {@code item6} + * {@code item7}, {@code item8} or {@code item9} is {@code null} * @see ReactiveX operators documentation: Just */ @CheckReturnValue @@ -2622,7 +2711,7 @@ public static Observable just(@NonNull T item1, @NonNull T item2, @NonNul } /** - * Converts ten items into an ObservableSource that emits those items. + * Converts ten items into an {@code Observable} that emits those items. *

* *

@@ -2652,7 +2741,11 @@ public static Observable just(@NonNull T item1, @NonNull T item2, @NonNul * tenth item * @param * the type of these items - * @return an Observable that emits each item + * @return an {@code Observable} that emits each item + * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3}, + * {@code item4}, {@code item5}, {@code item6} + * {@code item7}, {@code item8}, {@code item9} + * or {@code item10} is {@code null} * @see ReactiveX operators documentation: Just */ @CheckReturnValue @@ -2674,24 +2767,24 @@ public static Observable just(@NonNull T item1, @NonNull T item2, @NonNul } /** - * Flattens an Iterable of ObservableSources into one ObservableSource, without any transformation, while limiting the - * number of concurrent subscriptions to these ObservableSources. + * Flattens an {@link Iterable} of {@link ObservableSource}s into one {@code Observable}, without any transformation, while limiting the + * number of concurrent subscriptions to these {@code ObservableSource}s. *

* *

- * You can combine the items emitted by multiple ObservableSources so that they appear as a single ObservableSource, by + * You can combine the items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by * using the {@code merge} method. *

*
Scheduler:
*
{@code merge} does not operate by default on a particular {@link Scheduler}.
*
Error handling:
- *
If any of the source {@code ObservableSource}s signal a {@code Throwable} via {@code onError}, the resulting + *
If any of the returned {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed. * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the * first one's error or, depending on the concurrency of the sources, may terminate with a - * {@code CompositeException} containing two or more of the various error signals. + * {@link CompositeException} containing two or more of the various error signals. * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via - * {@link RxJavaPlugins#onError(Throwable)} method as {@code UndeliverableException} errors. Similarly, {@code Throwable}s + * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a * (composite) error will be sent to the same global error handler. * Use {@link #mergeDelayError(Iterable, int, int)} to merge sources and terminate only when all source {@code ObservableSource}s @@ -2701,13 +2794,13 @@ public static Observable just(@NonNull T item1, @NonNull T item2, @NonNul * * @param the common element base type * @param sources - * the Iterable of ObservableSources + * the {@code Iterable} of {@code ObservableSource}s * @param maxConcurrency - * the maximum number of ObservableSources that may be subscribed to concurrently + * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently * @param bufferSize - * the number of items to prefetch from each inner ObservableSource - * @return an Observable that emits items that are the result of flattening the items emitted by the - * ObservableSources in the Iterable + * the number of items expected from each inner {@code ObservableSource} to be buffered + * @return an {@code Observable} that emits items that are the result of flattening the items emitted by the + * {@code ObservableSource}s in the {@code Iterable} * @throws IllegalArgumentException * if {@code maxConcurrent} is less than or equal to 0 * @see ReactiveX operators documentation: Merge @@ -2722,24 +2815,24 @@ public static Observable merge(@NonNull Iterable * *

- * You can combine the items emitted by multiple ObservableSources so that they appear as a single ObservableSource, by + * You can combine the items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by * using the {@code merge} method. *

*
Scheduler:
*
{@code mergeArray} does not operate by default on a particular {@link Scheduler}.
*
Error handling:
- *
If any of the source {@code ObservableSource}s signal a {@code Throwable} via {@code onError}, the resulting + *
If any of the {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed. * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the * first one's error or, depending on the concurrency of the sources, may terminate with a - * {@code CompositeException} containing two or more of the various error signals. + * {@link CompositeException} containing two or more of the various error signals. * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via - * {@link RxJavaPlugins#onError(Throwable)} method as {@code UndeliverableException} errors. Similarly, {@code Throwable}s + * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a * (composite) error will be sent to the same global error handler. * Use {@link #mergeArrayDelayError(int, int, ObservableSource...)} to merge sources and terminate only when all source {@code ObservableSource}s @@ -2749,13 +2842,13 @@ public static Observable merge(@NonNull Iterable the common element base type * @param sources - * the array of ObservableSources + * the array of {@code ObservableSource}s * @param maxConcurrency - * the maximum number of ObservableSources that may be subscribed to concurrently + * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently * @param bufferSize - * the number of items to prefetch from each inner ObservableSource - * @return an Observable that emits items that are the result of flattening the items emitted by the - * ObservableSources in the Iterable + * the number of items expected from each inner {@code ObservableSource} to be buffered + * @return an {@code Observable} that emits items that are the result of flattening the items emitted by the + * {@code ObservableSource}s in the array * @throws IllegalArgumentException * if {@code maxConcurrent} is less than or equal to 0 * @see ReactiveX operators documentation: Merge @@ -2771,23 +2864,23 @@ public static Observable mergeArray(int maxConcurrency, int bufferSize, @ } /** - * Flattens an Iterable of ObservableSources into one ObservableSource, without any transformation. + * Flattens an {@link Iterable} of {@link ObservableSource}s into one {@code Observable}, without any transformation. *

* *

- * You can combine the items emitted by multiple ObservableSources so that they appear as a single ObservableSource, by + * You can combine the items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by * using the {@code merge} method. *

*
Scheduler:
*
{@code merge} does not operate by default on a particular {@link Scheduler}.
*
Error handling:
- *
If any of the source {@code ObservableSource}s signal a {@code Throwable} via {@code onError}, the resulting + *
If any of the returned {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed. * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the * first one's error or, depending on the concurrency of the sources, may terminate with a - * {@code CompositeException} containing two or more of the various error signals. + * {@link CompositeException} containing two or more of the various error signals. * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via - * {@link RxJavaPlugins#onError(Throwable)} method as {@code UndeliverableException} errors. Similarly, {@code Throwable}s + * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a * (composite) error will be sent to the same global error handler. * Use {@link #mergeDelayError(Iterable)} to merge sources and terminate only when all source {@code ObservableSource}s @@ -2797,9 +2890,9 @@ public static Observable mergeArray(int maxConcurrency, int bufferSize, @ * * @param the common element base type * @param sources - * the Iterable of ObservableSources - * @return an Observable that emits items that are the result of flattening the items emitted by the - * ObservableSources in the Iterable + * the {@code Iterable} of {@code ObservableSource}s + * @return an {@code Observable} that emits items that are the result of flattening the items emitted by the + * {@code ObservableSource}s in the {@code Iterable} * @see ReactiveX operators documentation: Merge * @see #mergeDelayError(Iterable) */ @@ -2812,24 +2905,24 @@ public static Observable merge(@NonNull Iterable * *

- * You can combine the items emitted by multiple ObservableSources so that they appear as a single ObservableSource, by + * You can combine the items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by * using the {@code merge} method. *

*
Scheduler:
*
{@code merge} does not operate by default on a particular {@link Scheduler}.
*
Error handling:
- *
If any of the source {@code ObservableSource}s signal a {@code Throwable} via {@code onError}, the resulting + *
If any of the returned {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed. * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the * first one's error or, depending on the concurrency of the sources, may terminate with a - * {@code CompositeException} containing two or more of the various error signals. + * {@link CompositeException} containing two or more of the various error signals. * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via - * {@link RxJavaPlugins#onError(Throwable)} method as {@code UndeliverableException} errors. Similarly, {@code Throwable}s + * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a * (composite) error will be sent to the same global error handler. * Use {@link #mergeDelayError(Iterable, int)} to merge sources and terminate only when all source {@code ObservableSource}s @@ -2839,11 +2932,11 @@ public static Observable merge(@NonNull Iterable the common element base type * @param sources - * the Iterable of ObservableSources + * the {@code Iterable} of {@code ObservableSource}s * @param maxConcurrency - * the maximum number of ObservableSources that may be subscribed to concurrently - * @return an Observable that emits items that are the result of flattening the items emitted by the - * ObservableSources in the Iterable + * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently + * @return an {@code Observable} that emits items that are the result of flattening the items emitted by the + * {@code ObservableSource}s in the {@code Iterable} * @throws IllegalArgumentException * if {@code maxConcurrent} is less than or equal to 0 * @see ReactiveX operators documentation: Merge @@ -2858,24 +2951,24 @@ public static Observable merge(@NonNull Iterable * *

- * You can combine the items emitted by multiple ObservableSources so that they appear as a single ObservableSource, by + * You can combine the items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by * using the {@code merge} method. *

*
Scheduler:
*
{@code merge} does not operate by default on a particular {@link Scheduler}.
*
Error handling:
- *
If any of the source {@code ObservableSource}s signal a {@code Throwable} via {@code onError}, the resulting + *
If any of the returned {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed. * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the * first one's error or, depending on the concurrency of the sources, may terminate with a - * {@code CompositeException} containing two or more of the various error signals. + * {@link CompositeException} containing two or more of the various error signals. * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via - * {@link RxJavaPlugins#onError(Throwable)} method as {@code UndeliverableException} errors. Similarly, {@code Throwable}s + * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a * (composite) error will be sent to the same global error handler. * Use {@link #mergeDelayError(ObservableSource)} to merge sources and terminate only when all source {@code ObservableSource}s @@ -2885,10 +2978,11 @@ public static Observable merge(@NonNull Iterable the common element base type * @param sources - * an ObservableSource that emits ObservableSources - * @return an Observable that emits items that are the result of flattening the ObservableSources emitted by the - * {@code source} ObservableSource + * an {@code ObservableSource} that emits {@code ObservableSource}s + * @return an {@code Observable} that emits items that are the result of flattening the {@code ObservableSource}s emitted by the + * {@code source} {@code ObservableSource} * @see ReactiveX operators documentation: Merge + * @throws NullPointerException if {@code sources} is {@code null} * @see #mergeDelayError(ObservableSource) */ @CheckReturnValue @@ -2901,25 +2995,25 @@ public static Observable merge(@NonNull ObservableSource * *

- * You can combine the items emitted by multiple ObservableSources so that they appear as a single ObservableSource, by + * You can combine the items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by * using the {@code merge} method. *

*
Scheduler:
*
{@code merge} does not operate by default on a particular {@link Scheduler}.
*
Error handling:
- *
If any of the source {@code ObservableSource}s signal a {@code Throwable} via {@code onError}, the resulting + *
If any of the returned {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed. * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the * first one's error or, depending on the concurrency of the sources, may terminate with a - * {@code CompositeException} containing two or more of the various error signals. + * {@link CompositeException} containing two or more of the various error signals. * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via - * {@link RxJavaPlugins#onError(Throwable)} method as {@code UndeliverableException} errors. Similarly, {@code Throwable}s + * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a * (composite) error will be sent to the same global error handler. * Use {@link #mergeDelayError(ObservableSource, int)} to merge sources and terminate only when all source {@code ObservableSource}s @@ -2929,13 +3023,14 @@ public static Observable merge(@NonNull ObservableSource the common element base type * @param sources - * an ObservableSource that emits ObservableSources + * an {@code ObservableSource} that emits {@code ObservableSource}s * @param maxConcurrency - * the maximum number of ObservableSources that may be subscribed to concurrently - * @return an Observable that emits items that are the result of flattening the ObservableSources emitted by the - * {@code source} ObservableSource + * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently + * @return an {@code Observable} that emits items that are the result of flattening the {@code ObservableSource}s emitted by the + * {@code source} {@code ObservableSource} + * @throws NullPointerException if {@code sources} is {@code null} * @throws IllegalArgumentException - * if {@code maxConcurrent} is less than or equal to 0 + * if {@code maxConcurrency} is non-positive * @see ReactiveX operators documentation: Merge * @since 1.1.0 * @see #mergeDelayError(ObservableSource, int) @@ -2951,23 +3046,23 @@ public static Observable merge(@NonNull ObservableSource * *

- * You can combine items emitted by multiple ObservableSources so that they appear as a single ObservableSource, by + * You can combine items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by * using the {@code merge} method. *

*
Scheduler:
*
{@code merge} does not operate by default on a particular {@link Scheduler}.
*
Error handling:
- *
If any of the source {@code ObservableSource}s signal a {@code Throwable} via {@code onError}, the resulting + *
If any of the {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed. * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the * first one's error or, depending on the concurrency of the sources, may terminate with a - * {@code CompositeException} containing two or more of the various error signals. + * {@link CompositeException} containing two or more of the various error signals. * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via - * {@link RxJavaPlugins#onError(Throwable)} method as {@code UndeliverableException} errors. Similarly, {@code Throwable}s + * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a * (composite) error will be sent to the same global error handler. * Use {@link #mergeDelayError(ObservableSource, ObservableSource)} to merge sources and terminate only when all source {@code ObservableSource}s @@ -2977,10 +3072,11 @@ public static Observable merge(@NonNull ObservableSource the common element base type * @param source1 - * an ObservableSource to be merged + * an {@code ObservableSource} to be merged * @param source2 - * an ObservableSource to be merged - * @return an Observable that emits all of the items emitted by the source ObservableSources + * an {@code ObservableSource} to be merged + * @return an {@code Observable} that emits all of the items emitted by the {@code ObservableSource}s + * @throws NullPointerException if {@code source1} or {@code source2} is {@code null} * @see ReactiveX operators documentation: Merge * @see #mergeDelayError(ObservableSource, ObservableSource) */ @@ -2995,23 +3091,23 @@ public static Observable merge(@NonNull ObservableSource sou } /** - * Flattens three ObservableSources into a single ObservableSource, without any transformation. + * Flattens three {@link ObservableSource}s into a single {@code Observable}, without any transformation. *

* *

- * You can combine items emitted by multiple ObservableSources so that they appear as a single ObservableSource, by + * You can combine items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by * using the {@code merge} method. *

*
Scheduler:
*
{@code merge} does not operate by default on a particular {@link Scheduler}.
*
Error handling:
- *
If any of the source {@code ObservableSource}s signal a {@code Throwable} via {@code onError}, the resulting + *
If any of the {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed. * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the * first one's error or, depending on the concurrency of the sources, may terminate with a - * {@code CompositeException} containing two or more of the various error signals. + * {@link CompositeException} containing two or more of the various error signals. * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via - * {@link RxJavaPlugins#onError(Throwable)} method as {@code UndeliverableException} errors. Similarly, {@code Throwable}s + * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a * (composite) error will be sent to the same global error handler. * Use {@link #mergeDelayError(ObservableSource, ObservableSource, ObservableSource)} to merge sources and terminate only when all source {@code ObservableSource}s @@ -3021,12 +3117,13 @@ public static Observable merge(@NonNull ObservableSource sou * * @param the common element base type * @param source1 - * an ObservableSource to be merged + * an {@code ObservableSource} to be merged * @param source2 - * an ObservableSource to be merged + * an {@code ObservableSource} to be merged * @param source3 - * an ObservableSource to be merged - * @return an Observable that emits all of the items emitted by the source ObservableSources + * an {@code ObservableSource} to be merged + * @return an {@code Observable} that emits all of the items emitted by the {@code ObservableSource}s + * @throws NullPointerException if {@code source1}, {@code source2} or {@code source3} is {@code null} * @see ReactiveX operators documentation: Merge * @see #mergeDelayError(ObservableSource, ObservableSource, ObservableSource) */ @@ -3044,23 +3141,23 @@ public static Observable merge( } /** - * Flattens four ObservableSources into a single ObservableSource, without any transformation. + * Flattens four {@link ObservableSource}s into a single {@code Observable}, without any transformation. *

* *

- * You can combine items emitted by multiple ObservableSources so that they appear as a single ObservableSource, by + * You can combine items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by * using the {@code merge} method. *

*
Scheduler:
*
{@code merge} does not operate by default on a particular {@link Scheduler}.
*
Error handling:
- *
If any of the source {@code ObservableSource}s signal a {@code Throwable} via {@code onError}, the resulting + *
If any of the {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed. * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the * first one's error or, depending on the concurrency of the sources, may terminate with a - * {@code CompositeException} containing two or more of the various error signals. + * {@link CompositeException} containing two or more of the various error signals. * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via - * {@link RxJavaPlugins#onError(Throwable)} method as {@code UndeliverableException} errors. Similarly, {@code Throwable}s + * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a * (composite) error will be sent to the same global error handler. * Use {@link #mergeDelayError(ObservableSource, ObservableSource, ObservableSource, ObservableSource)} to merge sources and terminate only when all source {@code ObservableSource}s @@ -3070,14 +3167,15 @@ public static Observable merge( * * @param the common element base type * @param source1 - * an ObservableSource to be merged + * an {@code ObservableSource} to be merged * @param source2 - * an ObservableSource to be merged + * an {@code ObservableSource} to be merged * @param source3 - * an ObservableSource to be merged + * an {@code ObservableSource} to be merged * @param source4 - * an ObservableSource to be merged - * @return an Observable that emits all of the items emitted by the source ObservableSources + * an {@code ObservableSource} to be merged + * @return an {@code Observable} that emits all of the items emitted by the {@code ObservableSource}s + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code source4} is {@code null} * @see ReactiveX operators documentation: Merge * @see #mergeDelayError(ObservableSource, ObservableSource, ObservableSource, ObservableSource) */ @@ -3096,23 +3194,23 @@ public static Observable merge( } /** - * Flattens an Array of ObservableSources into one ObservableSource, without any transformation. + * Flattens an array of {@link ObservableSource}s into one {@code Observable}, without any transformation. *

* *

- * You can combine items emitted by multiple ObservableSources so that they appear as a single ObservableSource, by + * You can combine items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by * using the {@code merge} method. *

*
Scheduler:
*
{@code mergeArray} does not operate by default on a particular {@link Scheduler}.
*
Error handling:
- *
If any of the source {@code ObservableSource}s signal a {@code Throwable} via {@code onError}, the resulting + *
If any of the {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed. * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the * first one's error or, depending on the concurrency of the sources, may terminate with a - * {@code CompositeException} containing two or more of the various error signals. + * {@link CompositeException} containing two or more of the various error signals. * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via - * {@link RxJavaPlugins#onError(Throwable)} method as {@code UndeliverableException} errors. Similarly, {@code Throwable}s + * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a * (composite) error will be sent to the same global error handler. * Use {@link #mergeArrayDelayError(ObservableSource...)} to merge sources and terminate only when all source {@code ObservableSource}s @@ -3122,8 +3220,9 @@ public static Observable merge( * * @param the common element base type * @param sources - * the array of ObservableSources - * @return an Observable that emits all of the items emitted by the ObservableSources in the Array + * the array of {@code ObservableSource}s + * @return an {@code Observable} that emits all of the items emitted by the {@code ObservableSource}s in the array + * @throws NullPointerException if {@code sources} is {@code null} * @see ReactiveX operators documentation: Merge * @see #mergeArrayDelayError(ObservableSource...) */ @@ -3137,18 +3236,18 @@ public static Observable mergeArray(@NonNull ObservableSource - * This behaves like {@link #merge(ObservableSource)} except that if any of the merged ObservableSources notify of an + * This behaves like {@link #merge(ObservableSource)} except that if any of the merged {@code ObservableSource}s notify of an * error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from propagating that - * error notification until all of the merged ObservableSources have finished emitting items. + * error notification until all of the merged {@code ObservableSource}s have finished emitting items. *

* *

- * Even if multiple merged ObservableSources send {@code onError} notifications, {@code mergeDelayError} will only - * invoke the {@code onError} method of its Observers once. + * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only + * invoke the {@code onError} method of its {@code Observer}s once. *

*
Scheduler:
*
{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
@@ -3156,9 +3255,10 @@ public static Observable mergeArray(@NonNull ObservableSource the common element base type * @param sources - * the Iterable of ObservableSources - * @return an Observable that emits items that are the result of flattening the items emitted by the - * ObservableSources in the Iterable + * the {@code Iterable} of {@code ObservableSource}s + * @return an {@code Observable} that emits items that are the result of flattening the items emitted by the + * {@code ObservableSource}s in the {@code Iterable} + * @throws NullPointerException if {@code sources} is {@code null} * @see ReactiveX operators documentation: Merge */ @SuppressWarnings({ "unchecked", "rawtypes" }) @@ -3170,18 +3270,18 @@ public static Observable mergeDelayError(@NonNull Iterable - * This behaves like {@link #merge(ObservableSource)} except that if any of the merged ObservableSources notify of an + * This behaves like {@link #merge(ObservableSource)} except that if any of the merged {@code ObservableSource}s notify of an * error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from propagating that - * error notification until all of the merged ObservableSources have finished emitting items. + * error notification until all of the merged {@code ObservableSource}s have finished emitting items. *

* *

- * Even if multiple merged ObservableSources send {@code onError} notifications, {@code mergeDelayError} will only - * invoke the {@code onError} method of its Observers once. + * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only + * invoke the {@code onError} method of its {@code Observer}s once. *

*
Scheduler:
*
{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
@@ -3189,13 +3289,15 @@ public static Observable mergeDelayError(@NonNull Iterable the common element base type * @param sources - * the Iterable of ObservableSources + * the {@code Iterable} of {@code ObservableSource}s * @param maxConcurrency - * the maximum number of ObservableSources that may be subscribed to concurrently + * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently * @param bufferSize - * the number of items to prefetch from each inner ObservableSource - * @return an Observable that emits items that are the result of flattening the items emitted by the - * ObservableSources in the Iterable + * the number of items expected from each inner {@code ObservableSource} to be buffered + * @return an {@code Observable} that emits items that are the result of flattening the items emitted by the + * {@code ObservableSource}s in the {@code Iterable} + * @throws NullPointerException if {@code sources} is {@code null} + * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Merge */ @SuppressWarnings({ "unchecked", "rawtypes" }) @@ -3207,18 +3309,18 @@ public static Observable mergeDelayError(@NonNull Iterable - * This behaves like {@link #merge(ObservableSource)} except that if any of the merged ObservableSources notify of an + * This behaves like {@link #merge(ObservableSource)} except that if any of the merged {@code ObservableSource}s notify of an * error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from propagating that - * error notification until all of the merged ObservableSources have finished emitting items. + * error notification until all of the merged {@code ObservableSource}s have finished emitting items. *

* *

- * Even if multiple merged ObservableSources send {@code onError} notifications, {@code mergeDelayError} will only - * invoke the {@code onError} method of its Observers once. + * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only + * invoke the {@code onError} method of its {@code Observer}s once. *

*
Scheduler:
*
{@code mergeArrayDelayError} does not operate by default on a particular {@link Scheduler}.
@@ -3226,13 +3328,15 @@ public static Observable mergeDelayError(@NonNull Iterable the common element base type * @param sources - * the array of ObservableSources + * the array of {@code ObservableSource}s * @param maxConcurrency - * the maximum number of ObservableSources that may be subscribed to concurrently + * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently * @param bufferSize - * the number of items to prefetch from each inner ObservableSource - * @return an Observable that emits items that are the result of flattening the items emitted by the - * ObservableSources in the Iterable + * the number of items expected from each inner {@code ObservableSource} to be buffered + * @return an {@code Observable} that emits items that are the result of flattening the items emitted by the + * {@code ObservableSource}s in the array + * @throws NullPointerException if {@code sources} is {@code null} + * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Merge */ @SuppressWarnings({ "unchecked", "rawtypes" }) @@ -3245,18 +3349,18 @@ public static Observable mergeArrayDelayError(int maxConcurrency, int buf } /** - * Flattens an Iterable of ObservableSources into one ObservableSource, in a way that allows an Observer to receive all - * successfully emitted items from each of the source ObservableSources without being interrupted by an error - * notification from one of them, while limiting the number of concurrent subscriptions to these ObservableSources. + * Flattens an {@link Iterable} of {@link ObservableSource}s into one {@code Observable}, in a way that allows an {@link Observer} to receive all + * successfully emitted items from each of the returned {@code ObservableSource}s without being interrupted by an error + * notification from one of them, while limiting the number of concurrent subscriptions to these {@code ObservableSource}s. *

- * This behaves like {@link #merge(ObservableSource)} except that if any of the merged ObservableSources notify of an + * This behaves like {@link #merge(ObservableSource)} except that if any of the merged {@code ObservableSource}s notify of an * error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from propagating that - * error notification until all of the merged ObservableSources have finished emitting items. + * error notification until all of the merged {@code ObservableSource}s have finished emitting items. *

* *

- * Even if multiple merged ObservableSources send {@code onError} notifications, {@code mergeDelayError} will only - * invoke the {@code onError} method of its Observers once. + * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only + * invoke the {@code onError} method of its {@code Observer}s once. *

*
Scheduler:
*
{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
@@ -3264,11 +3368,11 @@ public static Observable mergeArrayDelayError(int maxConcurrency, int buf * * @param the common element base type * @param sources - * the Iterable of ObservableSources + * the {@code Iterable} of {@code ObservableSource}s * @param maxConcurrency - * the maximum number of ObservableSources that may be subscribed to concurrently - * @return an Observable that emits items that are the result of flattening the items emitted by the - * ObservableSources in the Iterable + * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently + * @return an {@code Observable} that emits items that are the result of flattening the items emitted by the + * {@code ObservableSource}s in the {@code Iterable} * @see ReactiveX operators documentation: Merge */ @SuppressWarnings({ "unchecked", "rawtypes" }) @@ -3280,18 +3384,18 @@ public static Observable mergeDelayError(@NonNull Iterable - * This behaves like {@link #merge(ObservableSource)} except that if any of the merged ObservableSources notify of an + * This behaves like {@link #merge(ObservableSource)} except that if any of the merged {@code ObservableSource}s notify of an * error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from propagating that - * error notification until all of the merged ObservableSources have finished emitting items. + * error notification until all of the merged {@code ObservableSource}s have finished emitting items. *

* *

- * Even if multiple merged ObservableSources send {@code onError} notifications, {@code mergeDelayError} will only - * invoke the {@code onError} method of its Observers once. + * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only + * invoke the {@code onError} method of its {@code Observer}s once. *

*
Scheduler:
*
{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
@@ -3299,9 +3403,10 @@ public static Observable mergeDelayError(@NonNull Iterable the common element base type * @param sources - * an ObservableSource that emits ObservableSources - * @return an Observable that emits all of the items emitted by the ObservableSources emitted by the - * {@code source} ObservableSource + * an {@code ObservableSource} that emits {@code ObservableSource}s + * @return an {@code Observable} that emits all of the items emitted by the {@code ObservableSource}s emitted by the + * {@code source} {@code ObservableSource} + * @throws NullPointerException if {@code sources} is {@code null} * @see ReactiveX operators documentation: Merge */ @CheckReturnValue @@ -3314,19 +3419,19 @@ public static Observable mergeDelayError(@NonNull ObservableSource - * This behaves like {@link #merge(ObservableSource)} except that if any of the merged ObservableSources notify of an + * This behaves like {@link #merge(ObservableSource)} except that if any of the merged {@code ObservableSource}s notify of an * error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from propagating that - * error notification until all of the merged ObservableSources have finished emitting items. + * error notification until all of the merged {@code ObservableSource}s have finished emitting items. *

* *

- * Even if multiple merged ObservableSources send {@code onError} notifications, {@code mergeDelayError} will only - * invoke the {@code onError} method of its Observers once. + * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only + * invoke the {@code onError} method of its {@code Observer}s once. *

*
Scheduler:
*
{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
@@ -3334,11 +3439,13 @@ public static Observable mergeDelayError(@NonNull ObservableSource the common element base type * @param sources - * an ObservableSource that emits ObservableSources + * an {@code ObservableSource} that emits {@code ObservableSource}s * @param maxConcurrency - * the maximum number of ObservableSources that may be subscribed to concurrently - * @return an Observable that emits all of the items emitted by the ObservableSources emitted by the - * {@code source} ObservableSource + * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently + * @return an {@code Observable} that emits all of the items emitted by the {@code ObservableSource}s emitted by the + * {@code source} {@code ObservableSource} + * @throws NullPointerException if {@code sources} is {@code null} + * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive * @see ReactiveX operators documentation: Merge * @since 2.0 */ @@ -3353,18 +3460,18 @@ public static Observable mergeDelayError(@NonNull ObservableSource - * This behaves like {@link #merge(ObservableSource, ObservableSource)} except that if any of the merged ObservableSources + * This behaves like {@link #merge(ObservableSource, ObservableSource)} except that if any of the merged {@code ObservableSource}s * notify of an error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from - * propagating that error notification until all of the merged ObservableSources have finished emitting items. + * propagating that error notification until all of the merged {@code ObservableSource}s have finished emitting items. *

* *

- * Even if both merged ObservableSources send {@code onError} notifications, {@code mergeDelayError} will only - * invoke the {@code onError} method of its Observers once. + * Even if both merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only + * invoke the {@code onError} method of its {@code Observer}s once. *

*
Scheduler:
*
{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
@@ -3372,10 +3479,11 @@ public static Observable mergeDelayError(@NonNull ObservableSource the common element base type * @param source1 - * an ObservableSource to be merged + * an {@code ObservableSource} to be merged * @param source2 - * an ObservableSource to be merged - * @return an Observable that emits all of the items that are emitted by the two source ObservableSources + * an {@code ObservableSource} to be merged + * @return an {@code Observable} that emits all of the items that are emitted by the two source {@code ObservableSource}s + * @throws NullPointerException if {@code source1} or {@code source2} is {@code null} * @see ReactiveX operators documentation: Merge */ @SuppressWarnings({ "unchecked", "rawtypes" }) @@ -3390,19 +3498,19 @@ public static Observable mergeDelayError( } /** - * Flattens three ObservableSources into one ObservableSource, in a way that allows an Observer to receive all - * successfully emitted items from all of the source ObservableSources without being interrupted by an error + * Flattens three {@link ObservableSource}s into one {@code Observable}, in a way that allows an {@link Observer} to receive all + * successfully emitted items from all of the {@code ObservableSource}s without being interrupted by an error * notification from one of them. *

* This behaves like {@link #merge(ObservableSource, ObservableSource, ObservableSource)} except that if any of the merged - * ObservableSources notify of an error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain - * from propagating that error notification until all of the merged ObservableSources have finished emitting + * {@code ObservableSource}s notify of an error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain + * from propagating that error notification until all of the merged {@code ObservableSource}s have finished emitting * items. *

* *

- * Even if multiple merged ObservableSources send {@code onError} notifications, {@code mergeDelayError} will only - * invoke the {@code onError} method of its Observers once. + * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only + * invoke the {@code onError} method of its {@code Observer}s once. *

*
Scheduler:
*
{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
@@ -3410,12 +3518,13 @@ public static Observable mergeDelayError( * * @param the common element base type * @param source1 - * an ObservableSource to be merged + * an {@code ObservableSource} to be merged * @param source2 - * an ObservableSource to be merged + * an {@code ObservableSource} to be merged * @param source3 - * an ObservableSource to be merged - * @return an Observable that emits all of the items that are emitted by the source ObservableSources + * an {@code ObservableSource} to be merged + * @return an {@code Observable} that emits all of the items that are emitted by the {@code ObservableSource}s + * @throws NullPointerException if {@code source1}, {@code source2} or {@code source3} is {@code null} * @see ReactiveX operators documentation: Merge */ @SuppressWarnings({ "unchecked", "rawtypes" }) @@ -3432,19 +3541,19 @@ public static Observable mergeDelayError( } /** - * Flattens four ObservableSources into one ObservableSource, in a way that allows an Observer to receive all - * successfully emitted items from all of the source ObservableSources without being interrupted by an error + * Flattens four {@link ObservableSource}s into one {@code Observable}, in a way that allows an {@link Observer} to receive all + * successfully emitted items from all of the {@code ObservableSource}s without being interrupted by an error * notification from one of them. *

* This behaves like {@link #merge(ObservableSource, ObservableSource, ObservableSource, ObservableSource)} except that if any of - * the merged ObservableSources notify of an error via {@link Observer#onError onError}, {@code mergeDelayError} - * will refrain from propagating that error notification until all of the merged ObservableSources have finished + * the merged {@code ObservableSource}s notify of an error via {@link Observer#onError onError}, {@code mergeDelayError} + * will refrain from propagating that error notification until all of the merged {@code ObservableSource}s have finished * emitting items. *

* *

- * Even if multiple merged ObservableSources send {@code onError} notifications, {@code mergeDelayError} will only - * invoke the {@code onError} method of its Observers once. + * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only + * invoke the {@code onError} method of its {@code Observer}s once. *

*
Scheduler:
*
{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
@@ -3452,14 +3561,15 @@ public static Observable mergeDelayError( * * @param the common element base type * @param source1 - * an ObservableSource to be merged + * an {@code ObservableSource} to be merged * @param source2 - * an ObservableSource to be merged + * an {@code ObservableSource} to be merged * @param source3 - * an ObservableSource to be merged + * an {@code ObservableSource} to be merged * @param source4 - * an ObservableSource to be merged - * @return an Observable that emits all of the items that are emitted by the source ObservableSources + * an {@code ObservableSource} to be merged + * @return an {@code Observable} that emits all of the items that are emitted by the {@code ObservableSource}s + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code source4} is {@code null} * @see ReactiveX operators documentation: Merge */ @SuppressWarnings({ "unchecked", "rawtypes" }) @@ -3477,18 +3587,18 @@ public static Observable mergeDelayError( } /** - * Flattens an Iterable of ObservableSources into one ObservableSource, in a way that allows an Observer to receive all - * successfully emitted items from each of the source ObservableSources without being interrupted by an error + * Flattens an array of {@link ObservableSource}s into one {@code Observable}, in a way that allows an {@link Observer} to receive all + * successfully emitted items from each of the {@code ObservableSource}s without being interrupted by an error * notification from one of them. *

- * This behaves like {@link #merge(ObservableSource)} except that if any of the merged ObservableSources notify of an + * This behaves like {@link #merge(ObservableSource)} except that if any of the merged {@code ObservableSource}s notify of an * error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from propagating that - * error notification until all of the merged ObservableSources have finished emitting items. + * error notification until all of the merged {@code ObservableSource}s have finished emitting items. *

* *

- * Even if multiple merged ObservableSources send {@code onError} notifications, {@code mergeDelayError} will only - * invoke the {@code onError} method of its Observers once. + * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only + * invoke the {@code onError} method of its {@code Observer}s once. *

*
Scheduler:
*
{@code mergeArrayDelayError} does not operate by default on a particular {@link Scheduler}.
@@ -3496,9 +3606,9 @@ public static Observable mergeDelayError( * * @param the common element base type * @param sources - * the Iterable of ObservableSources - * @return an Observable that emits items that are the result of flattening the items emitted by the - * ObservableSources in the Iterable + * the array of {@code ObservableSource}s + * @return an {@code Observable} that emits items that are the result of flattening the items emitted by the + * {@code ObservableSource}s in the array * @see ReactiveX operators documentation: Merge */ @SuppressWarnings({ "unchecked", "rawtypes" }) @@ -3511,19 +3621,19 @@ public static Observable mergeArrayDelayError(@NonNull ObservableSource * *

- * This ObservableSource is useful primarily for testing purposes. + * The returned {@code Observable} is useful primarily for testing purposes. *

*
Scheduler:
*
{@code never} does not operate by default on a particular {@link Scheduler}.
*
* * @param - * the type of items (not) emitted by the ObservableSource - * @return an Observable that never emits any items or sends any notifications to an {@link Observer} + * the type of items (not) emitted by the {@code Observable} + * @return an {@code Observable} that never emits any items or sends any notifications to an {@code Observer} * @see ReactiveX operators documentation: Never */ @CheckReturnValue @@ -3535,7 +3645,7 @@ public static Observable never() { } /** - * Returns an Observable that emits a sequence of Integers within a specified range. + * Returns an {@code Observable} that emits a sequence of {@link Integer}s within a specified range. *

* *

@@ -3544,12 +3654,12 @@ public static Observable never() { *
* * @param start - * the value of the first Integer in the sequence + * the value of the first {@code Integer} in the sequence * @param count - * the number of sequential Integers to generate - * @return an Observable that emits a range of sequential Integers + * the number of sequential {@code Integer}s to generate + * @return an {@code Observable} that emits a range of sequential {@code Integer}s * @throws IllegalArgumentException - * if {@code count} is less than zero, or if {@code start} + {@code count} − 1 exceeds + * if {@code count} is negative, or if {@code start} + {@code count} − 1 exceeds * {@link Integer#MAX_VALUE} * @see ReactiveX operators documentation: Range */ @@ -3573,7 +3683,7 @@ public static Observable range(int start, int count) { } /** - * Returns an Observable that emits a sequence of Longs within a specified range. + * Returns an {@code Observable} that emits a sequence of {@link Long}s within a specified range. *

* *

@@ -3582,12 +3692,12 @@ public static Observable range(int start, int count) { *
* * @param start - * the value of the first Long in the sequence + * the value of the first {@code Long} in the sequence * @param count - * the number of sequential Longs to generate - * @return an Observable that emits a range of sequential Longs + * the number of sequential {@code Long}s to generate + * @return an {@code Observable} that emits a range of sequential {@code Long}s * @throws IllegalArgumentException - * if {@code count} is less than zero, or if {@code start} + {@code count} − 1 exceeds + * if {@code count} is negative, or if {@code start} + {@code count} − 1 exceeds * {@link Long#MAX_VALUE} * @see ReactiveX operators documentation: Range */ @@ -3616,8 +3726,8 @@ public static Observable rangeLong(long start, long count) { } /** - * Returns a Single that emits a Boolean value that indicates whether two ObservableSource sequences are the - * same by comparing the items emitted by each ObservableSource pairwise. + * Returns a {@link Single} that emits a {@link Boolean} value that indicates whether two {@link ObservableSource} sequences are the + * same by comparing the items emitted by each {@code ObservableSource} pairwise. *

* *

@@ -3626,12 +3736,12 @@ public static Observable rangeLong(long start, long count) { *
* * @param source1 - * the first ObservableSource to compare + * the first {@code ObservableSource} to compare * @param source2 - * the second ObservableSource to compare + * the second {@code ObservableSource} to compare * @param - * the type of items emitted by each ObservableSource - * @return a Single that emits a Boolean value that indicates whether the two sequences are the same + * the type of items emitted by each {@code ObservableSource} + * @return a {@code Single} that emits a {@code Boolean} value that indicates whether the two sequences are the same * @see ReactiveX operators documentation: SequenceEqual */ @CheckReturnValue @@ -3642,8 +3752,8 @@ public static Single sequenceEqual(@NonNull ObservableSource * @@ -3653,14 +3763,14 @@ public static Single sequenceEqual(@NonNull ObservableSource * * @param source1 - * the first ObservableSource to compare + * the first {@code ObservableSource} to compare * @param source2 - * the second ObservableSource to compare + * the second {@code ObservableSource} to compare * @param isEqual - * a function used to compare items emitted by each ObservableSource + * a function used to compare items emitted by each {@code ObservableSource} * @param - * the type of items emitted by each ObservableSource - * @return a Single that emits a Boolean value that indicates whether the two ObservableSource two sequences + * the type of items emitted by each {@code ObservableSource} + * @return a {@code Single} that emits a {@code Boolean} value that indicates whether the two {@code ObservableSource} two sequences * are the same according to the specified function * @see ReactiveX operators documentation: SequenceEqual */ @@ -3674,8 +3784,8 @@ public static Single sequenceEqual( } /** - * Returns a Single that emits a Boolean value that indicates whether two ObservableSource sequences are the - * same by comparing the items emitted by each ObservableSource pairwise based on the results of a specified + * Returns a {@link Single} that emits a {@link Boolean} value that indicates whether two {@link ObservableSource} sequences are the + * same by comparing the items emitted by each {@code ObservableSource} pairwise based on the results of a specified * equality function. *

* @@ -3685,17 +3795,19 @@ public static Single sequenceEqual( *

* * @param source1 - * the first ObservableSource to compare + * the first {@code ObservableSource} to compare * @param source2 - * the second ObservableSource to compare + * the second {@code ObservableSource} to compare * @param isEqual - * a function used to compare items emitted by each ObservableSource + * a function used to compare items emitted by each {@code ObservableSource} * @param bufferSize - * the number of items to prefetch from the first and second source ObservableSource + * the number of items expected from the first and second source {@code ObservableSource} to be buffered * @param - * the type of items emitted by each ObservableSource - * @return an Observable that emits a Boolean value that indicates whether the two ObservableSource two sequences + * the type of items emitted by each {@code ObservableSource} + * @return a {@code Single} that emits a {@code Boolean} value that indicates whether the two {@code ObservableSource} two sequences * are the same according to the specified function + * @throws NullPointerException if {@code source1}, {@code source2} or {@code isEqual} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: SequenceEqual */ @CheckReturnValue @@ -3712,8 +3824,8 @@ public static Single sequenceEqual( } /** - * Returns a Single that emits a Boolean value that indicates whether two ObservableSource sequences are the - * same by comparing the items emitted by each ObservableSource pairwise. + * Returns a {@link Single} that emits a {@link Boolean} value that indicates whether two {@link ObservableSource} sequences are the + * same by comparing the items emitted by each {@code ObservableSource} pairwise. *

* *

@@ -3722,14 +3834,14 @@ public static Single sequenceEqual( *
* * @param source1 - * the first ObservableSource to compare + * the first {@code ObservableSource} to compare * @param source2 - * the second ObservableSource to compare + * the second {@code ObservableSource} to compare * @param bufferSize - * the number of items to prefetch from the first and second source ObservableSource + * the number of items expected from the first and second source {@code ObservableSource} to be buffered * @param - * the type of items emitted by each ObservableSource - * @return a Single that emits a Boolean value that indicates whether the two sequences are the same + * the type of items emitted by each {@code ObservableSource} + * @return a {@code Single} that emits a {@code Boolean} value that indicates whether the two sequences are the same * @see ReactiveX operators documentation: SequenceEqual */ @CheckReturnValue @@ -3741,18 +3853,18 @@ public static Single sequenceEqual(@NonNull ObservableSource * *

- * {@code switchOnNext} subscribes to an ObservableSource that emits ObservableSources. Each time it observes one of - * these emitted ObservableSources, the ObservableSource returned by {@code switchOnNext} begins emitting the items - * emitted by that ObservableSource. When a new ObservableSource is emitted, {@code switchOnNext} stops emitting items - * from the earlier-emitted ObservableSource and begins emitting items from the new one. + * {@code switchOnNext} subscribes to an {@code ObservableSource} that emits {@code ObservableSource}s. Each time it observes one of + * these emitted {@code ObservableSource}s, the {@code ObservableSource} returned by {@code switchOnNext} begins emitting the items + * emitted by that {@code ObservableSource}. When a new inner {@code ObservableSource} is emitted, {@code switchOnNext} stops emitting items + * from the earlier-emitted {@code ObservableSource} and begins emitting items from the new one. *

- * The resulting ObservableSource completes if both the outer ObservableSource and the last inner ObservableSource, if any, complete. - * If the outer ObservableSource signals an onError, the inner ObservableSource is disposed and the error delivered in-sequence. + * The resulting {@code Observable} completes if both the outer {@code ObservableSource} and the last inner {@code ObservableSource}, if any, complete. + * If the outer {@code ObservableSource} signals an {@code onError}, the inner {@code ObservableSource} is disposed and the error delivered in-sequence. *

*
Scheduler:
*
{@code switchOnNext} does not operate by default on a particular {@link Scheduler}.
@@ -3760,11 +3872,13 @@ public static Single sequenceEqual(@NonNull ObservableSource the item type * @param sources - * the source ObservableSource that emits ObservableSources + * the {@code ObservableSource} that emits {@code ObservableSource}s * @param bufferSize - * the number of items to prefetch from the inner ObservableSources - * @return an Observable that emits the items emitted by the ObservableSource most recently emitted by the source - * ObservableSource + * the expected number of items to cache from the inner {@code ObservableSource}s + * @return an {@code Observable} that emits the items emitted by the {@code ObservableSource} most recently emitted by the + * {@code sources} {@code ObservableSource} + * @throws NullPointerException if {@code sources} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Switch */ @SuppressWarnings({ "rawtypes", "unchecked" }) @@ -3778,18 +3892,18 @@ public static Observable switchOnNext(@NonNull ObservableSource * *

- * {@code switchOnNext} subscribes to an ObservableSource that emits ObservableSources. Each time it observes one of - * these emitted ObservableSources, the ObservableSource returned by {@code switchOnNext} begins emitting the items - * emitted by that ObservableSource. When a new ObservableSource is emitted, {@code switchOnNext} stops emitting items - * from the earlier-emitted ObservableSource and begins emitting items from the new one. + * {@code switchOnNext} subscribes to an {@code ObservableSource} that emits {@code ObservableSource}s. Each time it observes one of + * these emitted {@code ObservableSource}s, the {@code ObservableSource} returned by {@code switchOnNext} begins emitting the items + * emitted by that {@code ObservableSource}. When a new inner {@code ObservableSource} is emitted, {@code switchOnNext} stops emitting items + * from the earlier-emitted {@code ObservableSource} and begins emitting items from the new one. *

- * The resulting ObservableSource completes if both the outer ObservableSource and the last inner ObservableSource, if any, complete. - * If the outer ObservableSource signals an onError, the inner ObservableSource is disposed and the error delivered in-sequence. + * The resulting {@code Observable} completes if both the outer {@code ObservableSource} and the last inner {@code ObservableSource}, if any, complete. + * If the outer {@code ObservableSource} signals an {@code onError}, the inner {@code ObservableSource} is disposed and the error delivered in-sequence. *

*
Scheduler:
*
{@code switchOnNext} does not operate by default on a particular {@link Scheduler}.
@@ -3797,9 +3911,9 @@ public static Observable switchOnNext(@NonNull ObservableSource the item type * @param sources - * the source ObservableSource that emits ObservableSources - * @return an Observable that emits the items emitted by the ObservableSource most recently emitted by the source - * ObservableSource + * the {@code ObservableSource} that emits {@code ObservableSource}s + * @return an {@code Observable} that emits the items emitted by the {@code ObservableSource} most recently emitted by the {@code sources} + * {@code ObservableSource} * @see ReactiveX operators documentation: Switch */ @CheckReturnValue @@ -3810,19 +3924,19 @@ public static Observable switchOnNext(@NonNull ObservableSource * *

- * {@code switchOnNext} subscribes to an ObservableSource that emits ObservableSources. Each time it observes one of - * these emitted ObservableSources, the ObservableSource returned by {@code switchOnNext} begins emitting the items - * emitted by that ObservableSource. When a new ObservableSource is emitted, {@code switchOnNext} stops emitting items - * from the earlier-emitted ObservableSource and begins emitting items from the new one. + * {@code switchOnNext} subscribes to an {@code ObservableSource} that emits {@code ObservableSource}s. Each time it observes one of + * these emitted {@code ObservableSource}s, the {@code ObservableSource} returned by {@code switchOnNext} begins emitting the items + * emitted by that {@code ObservableSource}. When a new inner {@code ObservableSource} is emitted, {@code switchOnNext} stops emitting items + * from the earlier-emitted {@code ObservableSource} and begins emitting items from the new one. *

- * The resulting ObservableSource completes if both the main ObservableSource and the last inner ObservableSource, if any, complete. - * If the main ObservableSource signals an onError, the termination of the last inner ObservableSource will emit that error as is - * or wrapped into a CompositeException along with the other possible errors the former inner ObservableSources signalled. + * The resulting {@code Observable} completes if both the main {@code ObservableSource} and the last inner {@code ObservableSource}, if any, complete. + * If the main {@code ObservableSource} signals an {@code onError}, the termination of the last inner {@code ObservableSource} will emit that error as is + * or wrapped into a {@link CompositeException} along with the other possible errors the former inner {@code ObservableSource}s signaled. *

*
Scheduler:
*
{@code switchOnNextDelayError} does not operate by default on a particular {@link Scheduler}.
@@ -3830,9 +3944,9 @@ public static Observable switchOnNext(@NonNull ObservableSource the item type * @param sources - * the source ObservableSource that emits ObservableSources - * @return an Observable that emits the items emitted by the ObservableSource most recently emitted by the source - * ObservableSource + * the {@code ObservableSource} that emits {@code ObservableSource}s + * @return an {@code Observable} that emits the items emitted by the {@code ObservableSource} most recently emitted by the {@code sources} + * {@code ObservableSource} * @see ReactiveX operators documentation: Switch * @since 2.0 */ @@ -3844,19 +3958,19 @@ public static Observable switchOnNextDelayError(@NonNull ObservableSource } /** - * Converts an ObservableSource that emits ObservableSources into an ObservableSource that emits the items emitted by the - * most recently emitted of those ObservableSources and delays any exception until all ObservableSources terminate. + * Converts an {@link ObservableSource} that emits {@code ObservableSource}s into an {@code Observable} that emits the items emitted by the + * most recently emitted of those {@code ObservableSource}s and delays any exception until all {@code ObservableSource}s terminate. *

* *

- * {@code switchOnNext} subscribes to an ObservableSource that emits ObservableSources. Each time it observes one of - * these emitted ObservableSources, the ObservableSource returned by {@code switchOnNext} begins emitting the items - * emitted by that ObservableSource. When a new ObservableSource is emitted, {@code switchOnNext} stops emitting items - * from the earlier-emitted ObservableSource and begins emitting items from the new one. + * {@code switchOnNext} subscribes to an {@code ObservableSource} that emits {@code ObservableSource}s. Each time it observes one of + * these emitted {@code ObservableSource}s, the {@code ObservableSource} returned by {@code switchOnNext} begins emitting the items + * emitted by that {@code ObservableSource}. When a new inner {@code ObservableSource} is emitted, {@code switchOnNext} stops emitting items + * from the earlier-emitted {@code ObservableSource} and begins emitting items from the new one. *

- * The resulting ObservableSource completes if both the main ObservableSource and the last inner ObservableSource, if any, complete. - * If the main ObservableSource signals an onError, the termination of the last inner ObservableSource will emit that error as is - * or wrapped into a CompositeException along with the other possible errors the former inner ObservableSources signalled. + * The resulting {@code Observable} completes if both the main {@code ObservableSource} and the last inner {@code ObservableSource}, if any, complete. + * If the main {@code ObservableSource} signals an {@code onError}, the termination of the last inner {@code ObservableSource} will emit that error as is + * or wrapped into a {@link CompositeException} along with the other possible errors the former inner {@code ObservableSource}s signaled. *

*
Scheduler:
*
{@code switchOnNextDelayError} does not operate by default on a particular {@link Scheduler}.
@@ -3864,11 +3978,13 @@ public static Observable switchOnNextDelayError(@NonNull ObservableSource * * @param the item type * @param sources - * the source ObservableSource that emits ObservableSources - * @param prefetch - * the number of items to prefetch from the inner ObservableSources - * @return an Observable that emits the items emitted by the ObservableSource most recently emitted by the source - * ObservableSource + * the {@code ObservableSource} that emits {@code ObservableSource}s + * @param bufferSize + * the expected number of items to cache from the inner {@code ObservableSource}s + * @return an {@code Observable} that emits the items emitted by the {@code ObservableSource} most recently emitted by the {@code sources} + * {@code ObservableSource} + * @throws NullPointerException if {@code sources} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Switch * @since 2.0 */ @@ -3876,14 +3992,14 @@ public static Observable switchOnNextDelayError(@NonNull ObservableSource @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @NonNull - public static Observable switchOnNextDelayError(@NonNull ObservableSource> sources, int prefetch) { + public static Observable switchOnNextDelayError(@NonNull ObservableSource> sources, int bufferSize) { Objects.requireNonNull(sources, "sources is null"); - ObjectHelper.verifyPositive(prefetch, "prefetch"); - return RxJavaPlugins.onAssembly(new ObservableSwitchMap(sources, Functions.identity(), prefetch, true)); + ObjectHelper.verifyPositive(bufferSize, "bufferSize"); + return RxJavaPlugins.onAssembly(new ObservableSwitchMap(sources, Functions.identity(), bufferSize, true)); } /** - * Returns an Observable that emits {@code 0L} after a specified delay, and then completes. + * Returns an {@code Observable} that emits {@code 0L} after a specified delay, and then completes. *

* *

@@ -3895,7 +4011,7 @@ public static Observable switchOnNextDelayError(@NonNull ObservableSource * the initial delay before emitting a single {@code 0L} * @param unit * time units to use for {@code delay} - * @return an Observable that {@code 0L} after a specified delay, and then completes + * @return an {@code Observable} that {@code 0L} after a specified delay, and then completes * @see ReactiveX operators documentation: Timer */ @CheckReturnValue @@ -3906,13 +4022,13 @@ public static Observable timer(long delay, @NonNull TimeUnit unit) { } /** - * Returns an Observable that emits {@code 0L} after a specified delay, on a specified Scheduler, and then + * Returns an {@code Observable} that emits {@code 0L} after a specified delay, on a specified {@link Scheduler}, and then * completes. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param delay @@ -3920,11 +4036,10 @@ public static Observable timer(long delay, @NonNull TimeUnit unit) { * @param unit * time units to use for {@code delay} * @param scheduler - * the {@link Scheduler} to use for scheduling the item + * the {@code Scheduler} to use for scheduling the item * @throws NullPointerException - * if {@code unit} is null, or - * if {@code scheduler} is null - * @return an Observable that emits {@code 0L} after a specified delay, on a specified Scheduler, and then + * if {@code unit} or {@code scheduler} is {@code null} + * @return an {@code Observable} that emits {@code 0L} after a specified delay, on a specified {@code Scheduler}, and then * completes * @see ReactiveX operators documentation: Timer */ @@ -3939,16 +4054,20 @@ public static Observable timer(long delay, @NonNull TimeUnit unit, @NonNul } /** - * Create an Observable by wrapping an ObservableSource which has to be implemented according - * to the Reactive-Streams-based Observable specification by handling - * disposal correctly; no safeguards are provided by the Observable itself. + * Create an {@code Observable} by wrapping an {@link ObservableSource} which has to be implemented according + * to the {@code Observable} specification derived from the Reactive Streams specification by handling + * disposal correctly; no safeguards are provided by the {@code Observable} itself. *
*
Scheduler:
*
{@code unsafeCreate} by default doesn't operate on any particular {@link Scheduler}.
*
* @param the value type emitted - * @param onSubscribe the ObservableSource instance to wrap - * @return the new Observable instance + * @param onSubscribe the {@code ObservableSource} instance to wrap + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code onSubscribe} is {@code null} + * @throws IllegalArgumentException if the {@code onSubscribe} is already an {@code Observable}, use + * {@link #wrap(ObservableSource)} in this case + * @see #wrap(ObservableSource) */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -3962,8 +4081,9 @@ public static Observable unsafeCreate(@NonNull ObservableSource onSubs } /** - * Constructs an ObservableSource that creates a dependent resource object which is disposed of when the downstream - * calls dispose(). + * Constructs an {@code Observable} that creates a dependent resource object, an {@link ObservableSource} with + * that resource and calls the provided {@code resourceDisposer} function if this inner source terminates or the + * downstream disposes the flow. *

* *

@@ -3971,15 +4091,15 @@ public static Observable unsafeCreate(@NonNull ObservableSource onSubs *
{@code using} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the element type of the generated ObservableSource + * @param the element type of the generated {@code Observable} * @param the type of the resource associated with the output sequence * @param resourceSupplier - * the factory function to create a resource object that depends on the ObservableSource + * the factory function to create a resource object that depends on the {@code ObservableSource} * @param sourceSupplier - * the factory function to create an ObservableSource - * @param disposer + * the factory function to create an {@code ObservableSource} + * @param resourceDisposer * the function that will dispose of the resource - * @return the ObservableSource whose lifetime controls the lifetime of the dependent resource object + * @return the {@code ObservableSource} whose lifetime controls the lifetime of the dependent resource object * @see ReactiveX operators documentation: Using */ @CheckReturnValue @@ -3988,16 +4108,14 @@ public static Observable unsafeCreate(@NonNull ObservableSource onSubs public static Observable using( @NonNull Supplier resourceSupplier, @NonNull Function> sourceSupplier, - @NonNull Consumer disposer) { - return using(resourceSupplier, sourceSupplier, disposer, true); + @NonNull Consumer resourceDisposer) { + return using(resourceSupplier, sourceSupplier, resourceDisposer, true); } /** - * Constructs an ObservableSource that creates a dependent resource object which is disposed of just before - * termination if you have set {@code disposeEagerly} to {@code true} and a dispose() call does not occur - * before termination. Otherwise resource disposal will occur on a dispose() call. Eager disposal is - * particularly appropriate for a synchronous ObservableSource that reuses resources. {@code disposeAction} will - * only be called once per subscription. + * Constructs an {@code Observable} that creates a dependent resource object, an {@link ObservableSource} with + * that resource and calls the provided {@code disposer} function if this inner source terminates or the + * downstream disposes the flow; doing it before these end-states have been reached if {@code eager == true}, after otherwise. *

* *

@@ -4005,20 +4123,21 @@ public static Observable using( *
{@code using} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the element type of the generated ObservableSource + * @param the element type of the generated {@code ObservableSource} * @param the type of the resource associated with the output sequence * @param resourceSupplier - * the factory function to create a resource object that depends on the ObservableSource + * the factory function to create a resource object that depends on the {@code ObservableSource} * @param sourceSupplier - * the factory function to create an ObservableSource - * @param disposer + * the factory function to create an {@code ObservableSource} + * @param resourceDisposer * the function that will dispose of the resource * @param eager - * If {@code true} then resource disposal will happen either on a {@code dispose()} call before the upstream is disposed + * If {@code true}, the resource disposal will happen either on a {@code dispose()} call before the upstream is disposed * or just before the emission of a terminal event ({@code onComplete} or {@code onError}). - * If {@code false} the resource disposal will happen either on a {@code dispose()} call after the upstream is disposed + * If {@code false}, the resource disposal will happen either on a {@code dispose()} call after the upstream is disposed * or just after the emission of a terminal event ({@code onComplete} or {@code onError}). - * @return the ObservableSource whose lifetime controls the lifetime of the dependent resource object + * @return the {@code ObservableSource} whose lifetime controls the lifetime of the dependent resource object + * @throws NullPointerException if {@code resourceSupplier}, {@code sourceSupplier} and {@code resourceDisposer} is {@code null} * @see ReactiveX operators documentation: Using * @since 2.0 */ @@ -4028,15 +4147,15 @@ public static Observable using( public static Observable using( @NonNull Supplier resourceSupplier, @NonNull Function> sourceSupplier, - @NonNull Consumer disposer, boolean eager) { + @NonNull Consumer resourceDisposer, boolean eager) { Objects.requireNonNull(resourceSupplier, "resourceSupplier is null"); Objects.requireNonNull(sourceSupplier, "sourceSupplier is null"); - Objects.requireNonNull(disposer, "disposer is null"); - return RxJavaPlugins.onAssembly(new ObservableUsing(resourceSupplier, sourceSupplier, disposer, eager)); + Objects.requireNonNull(resourceDisposer, "resourceDisposer is null"); + return RxJavaPlugins.onAssembly(new ObservableUsing(resourceSupplier, sourceSupplier, resourceDisposer, eager)); } /** - * Wraps an ObservableSource into an Observable if not already an Observable. + * Wraps an {@link ObservableSource} into an {@code Observable} if not already an {@code Observable}. * *
*
Scheduler:
@@ -4044,9 +4163,9 @@ public static Observable using( *
* * @param the value type - * @param source the source ObservableSource instance - * @return the new Observable instance or the same as the source - * @throws NullPointerException if source is null + * @param source the {@code ObservableSource} instance to wrap or cast to {@code Observable} + * @return the new {@code Observable} instance or the same as the source + * @throws NullPointerException if {@code source} is {@code null} */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -4060,16 +4179,16 @@ public static Observable wrap(@NonNull ObservableSource source) { } /** - * Returns an Observable that emits the results of a specified combiner function applied to combinations of - * items emitted, in sequence, by an Iterable of other ObservableSources. + * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of + * items emitted, in sequence, by an {@link Iterable} of other {@link ObservableSource}s. *

- * {@code zip} applies this function in strict sequence, so the first item emitted by the new ObservableSource - * will be the result of the function applied to the first item emitted by each of the source ObservableSources; - * the second item emitted by the new ObservableSource will be the result of the function applied to the second - * item emitted by each of those ObservableSources; and so forth. + * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable} + * will be the result of the function applied to the first item emitted by each of the {@code ObservableSource}s; + * the second item emitted by the resulting {@code Observable} will be the result of the function applied to the second + * item emitted by each of those {@code ObservableSource}s; and so forth. *

- * The resulting {@code ObservableSource} returned from {@code zip} will invoke {@code onNext} as many times as - * the number of {@code onNext} invocations of the source ObservableSource that emits the fewest items. + * The resulting {@code Observable} returned from {@code zip} will invoke {@code onNext} as many times as + * the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest items. *

* The operator subscribes to its sources in order they are specified and completes eagerly if * one of the sources is shorter than the rest while disposing the other sources. Therefore, it @@ -4085,7 +4204,7 @@ public static Observable wrap(@NonNull ObservableSource source) { *

* Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a - * {@code Function} passed to the method would trigger a {@code ClassCastException}. + * {@code Function} passed to the method would trigger a {@link ClassCastException}. * *

* @@ -4097,11 +4216,12 @@ public static Observable wrap(@NonNull ObservableSource source) { * @param the common value type * @param the zipped result type * @param sources - * an Iterable of source ObservableSources + * an {@code Iterable} of source {@code ObservableSource}s * @param zipper - * a function that, when applied to an item emitted by each of the source ObservableSources, results in - * an item that will be emitted by the resulting ObservableSource - * @return an Observable that emits the zipped results + * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in + * an item that will be emitted by the resulting {@code Observable} + * @return an {@code Observable} that emits the zipped results + * @throws NullPointerException if {@code sources} or {@code zipper} is {@code null} * @see ReactiveX operators documentation: Zip */ @CheckReturnValue @@ -4114,16 +4234,16 @@ public static Observable zip(@NonNull Iterable - * {@code zip} applies this function in strict sequence, so the first item emitted by the new ObservableSource - * will be the result of the function applied to the first item emitted by each of the source ObservableSources; - * the second item emitted by the new ObservableSource will be the result of the function applied to the second - * item emitted by each of those ObservableSources; and so forth. + * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable} + * will be the result of the function applied to the first item emitted by each of the {@code ObservableSource}s; + * the second item emitted by the resulting {@code Observable} will be the result of the function applied to the second + * item emitted by each of those {@code ObservableSource}s; and so forth. *

- * The resulting {@code ObservableSource} returned from {@code zip} will invoke {@code onNext} as many times as - * the number of {@code onNext} invocations of the source ObservableSource that emits the fewest items. + * The resulting {@code Observable} returned from {@code zip} will invoke {@code onNext} as many times as + * the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest items. *

* The operator subscribes to its sources in order they are specified and completes eagerly if * one of the sources is shorter than the rest while disposing the other sources. Therefore, it @@ -4139,7 +4259,7 @@ public static Observable zip(@NonNull Iterable * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a - * {@code Function} passed to the method would trigger a {@code ClassCastException}. + * {@code Function} passed to the method would trigger a {@link ClassCastException}. * *

* @@ -4150,17 +4270,19 @@ public static Observable zip(@NonNull Iterable the common source value type * @param the zipped result type - * @return an Observable that emits the zipped results + * @return an {@code Observable} that emits the zipped results + * @throws NullPointerException if {@code sources} or {@code zipper} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Zip */ @CheckReturnValue @@ -4176,18 +4298,18 @@ public static Observable zip(@NonNull Iterable * *

- * {@code zip} applies this function in strict sequence, so the first item emitted by the new ObservableSource + * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable} * will be the result of the function applied to the first item emitted by {@code o1} and the first item - * emitted by {@code o2}; the second item emitted by the new ObservableSource will be the result of the function + * emitted by {@code o2}; the second item emitted by the resulting {@code Observable} will be the result of the function * applied to the second item emitted by {@code o1} and the second item emitted by {@code o2}; and so forth. *

- * The resulting {@code ObservableSource} returned from {@code zip} will invoke {@link Observer#onNext onNext} - * as many times as the number of {@code onNext} invocations of the source ObservableSource that emits the fewest + * The resulting {@code Observable} returned from {@code zip} will invoke {@link Observer#onNext onNext} + * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest * items. *

* The operator subscribes to its sources in order they are specified and completes eagerly if @@ -4210,13 +4332,14 @@ public static Observable zip(@NonNull Iterable the value type of the second source * @param the zipped result type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * a second source ObservableSource + * a second source {@code ObservableSource} * @param zipper - * a function that, when applied to an item emitted by each of the source ObservableSources, results - * in an item that will be emitted by the resulting ObservableSource - * @return an Observable that emits the zipped results + * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results + * in an item that will be emitted by the resulting {@code Observable} + * @return an {@code Observable} that emits the zipped results + * @throws NullPointerException if {@code source1}, {@code source2} or {@code zipper} is {@code null} * @see ReactiveX operators documentation: Zip */ @CheckReturnValue @@ -4232,18 +4355,18 @@ public static Observable zip( } /** - * Returns an Observable that emits the results of a specified combiner function applied to combinations of - * two items emitted, in sequence, by two other ObservableSources. + * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of + * two items emitted, in sequence, by two other {@link ObservableSource}s. *

* *

- * {@code zip} applies this function in strict sequence, so the first item emitted by the new ObservableSource + * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable} * will be the result of the function applied to the first item emitted by {@code o1} and the first item - * emitted by {@code o2}; the second item emitted by the new ObservableSource will be the result of the function + * emitted by {@code o2}; the second item emitted by the resulting {@code Observable} will be the result of the function * applied to the second item emitted by {@code o1} and the second item emitted by {@code o2}; and so forth. *

- * The resulting {@code ObservableSource} returned from {@code zip} will invoke {@link Observer#onNext onNext} - * as many times as the number of {@code onNext} invocations of the source ObservableSource that emits the fewest + * The resulting {@code Observable} returned from {@code zip} will invoke {@link Observer#onNext onNext} + * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest * items. *

* The operator subscribes to its sources in order they are specified and completes eagerly if @@ -4266,14 +4389,15 @@ public static Observable zip( * @param the value type of the second source * @param the zipped result type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * a second source ObservableSource + * a second source {@code ObservableSource} * @param zipper - * a function that, when applied to an item emitted by each of the source ObservableSources, results - * in an item that will be emitted by the resulting ObservableSource - * @param delayError delay errors from any of the source ObservableSources till the other terminates - * @return an Observable that emits the zipped results + * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results + * in an item that will be emitted by the resulting {@code Observable} + * @param delayError delay errors from any of the {@code ObservableSource}s till the other terminates + * @return an {@code Observable} that emits the zipped results + * @throws NullPointerException if {@code source1}, {@code source2} or {@code zipper} is {@code null} * @see ReactiveX operators documentation: Zip */ @CheckReturnValue @@ -4289,18 +4413,18 @@ public static Observable zip( } /** - * Returns an Observable that emits the results of a specified combiner function applied to combinations of - * two items emitted, in sequence, by two other ObservableSources. + * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of + * two items emitted, in sequence, by two other {@link ObservableSource}s. *

* *

- * {@code zip} applies this function in strict sequence, so the first item emitted by the new ObservableSource + * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable} * will be the result of the function applied to the first item emitted by {@code o1} and the first item - * emitted by {@code o2}; the second item emitted by the new ObservableSource will be the result of the function + * emitted by {@code o2}; the second item emitted by the resulting {@code Observable} will be the result of the function * applied to the second item emitted by {@code o1} and the second item emitted by {@code o2}; and so forth. *

- * The resulting {@code ObservableSource} returned from {@code zip} will invoke {@link Observer#onNext onNext} - * as many times as the number of {@code onNext} invocations of the source ObservableSource that emits the fewest + * The resulting {@code Observable} returned from {@code zip} will invoke {@link Observer#onNext onNext} + * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest * items. *

* The operator subscribes to its sources in order they are specified and completes eagerly if @@ -4323,15 +4447,16 @@ public static Observable zip( * @param the value type of the second source * @param the zipped result type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * a second source ObservableSource + * a second source {@code ObservableSource} * @param zipper - * a function that, when applied to an item emitted by each of the source ObservableSources, results - * in an item that will be emitted by the resulting ObservableSource - * @param delayError delay errors from any of the source ObservableSources till the other terminates - * @param bufferSize the number of elements to prefetch from each source ObservableSource - * @return an Observable that emits the zipped results + * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results + * in an item that will be emitted by the resulting {@code Observable} + * @param delayError delay errors from any of the {@code ObservableSource}s till the other terminates + * @param bufferSize the number of elements expected from each source {@code ObservableSource} to be buffered + * @return an {@code Observable} that emits the zipped results + * @throws NullPointerException if {@code source1}, {@code source2} or {@code zipper} is {@code null} * @see ReactiveX operators documentation: Zip */ @CheckReturnValue @@ -4347,19 +4472,19 @@ public static Observable zip( } /** - * Returns an Observable that emits the results of a specified combiner function applied to combinations of - * three items emitted, in sequence, by three other ObservableSources. + * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of + * three items emitted, in sequence, by three other {@link ObservableSource}s. *

* *

- * {@code zip} applies this function in strict sequence, so the first item emitted by the new ObservableSource + * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable} * will be the result of the function applied to the first item emitted by {@code o1}, the first item - * emitted by {@code o2}, and the first item emitted by {@code o3}; the second item emitted by the new - * ObservableSource will be the result of the function applied to the second item emitted by {@code o1}, the + * emitted by {@code o2}, and the first item emitted by {@code o3}; the second item emitted by the resulting + * {@code Observable} will be the result of the function applied to the second item emitted by {@code o1}, the * second item emitted by {@code o2}, and the second item emitted by {@code o3}; and so forth. *

- * The resulting {@code ObservableSource} returned from {@code zip} will invoke {@link Observer#onNext onNext} - * as many times as the number of {@code onNext} invocations of the source ObservableSource that emits the fewest + * The resulting {@code Observable} returned from {@code zip} will invoke {@link Observer#onNext onNext} + * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest * items. *

* The operator subscribes to its sources in order they are specified and completes eagerly if @@ -4383,15 +4508,16 @@ public static Observable zip( * @param the value type of the third source * @param the zipped result type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * a second source ObservableSource + * a second source {@code ObservableSource} * @param source3 - * a third source ObservableSource + * a third source {@code ObservableSource} * @param zipper - * a function that, when applied to an item emitted by each of the source ObservableSources, results in - * an item that will be emitted by the resulting ObservableSource - * @return an Observable that emits the zipped results + * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in + * an item that will be emitted by the resulting {@code Observable} + * @return an {@code Observable} that emits the zipped results + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code zipper} is {@code null} * @see ReactiveX operators documentation: Zip */ @CheckReturnValue @@ -4409,19 +4535,19 @@ public static Observable zip( } /** - * Returns an Observable that emits the results of a specified combiner function applied to combinations of - * four items emitted, in sequence, by four other ObservableSources. + * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of + * four items emitted, in sequence, by four other {@link ObservableSource}s. *

* *

- * {@code zip} applies this function in strict sequence, so the first item emitted by the new ObservableSource + * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable} * will be the result of the function applied to the first item emitted by {@code o1}, the first item * emitted by {@code o2}, the first item emitted by {@code o3}, and the first item emitted by {@code 04}; - * the second item emitted by the new ObservableSource will be the result of the function applied to the second - * item emitted by each of those ObservableSources; and so forth. + * the second item emitted by the resulting {@code Observable} will be the result of the function applied to the second + * item emitted by each of those {@code ObservableSource}s; and so forth. *

- * The resulting {@code ObservableSource} returned from {@code zip} will invoke {@link Observer#onNext onNext} - * as many times as the number of {@code onNext} invocations of the source ObservableSource that emits the fewest + * The resulting {@code Observable} returned from {@code zip} will invoke {@link Observer#onNext onNext} + * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest * items. *

* The operator subscribes to its sources in order they are specified and completes eagerly if @@ -4446,17 +4572,19 @@ public static Observable zip( * @param the value type of the fourth source * @param the zipped result type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * a second source ObservableSource + * a second source {@code ObservableSource} * @param source3 - * a third source ObservableSource + * a third source {@code ObservableSource} * @param source4 - * a fourth source ObservableSource + * a fourth source {@code ObservableSource} * @param zipper - * a function that, when applied to an item emitted by each of the source ObservableSources, results in - * an item that will be emitted by the resulting ObservableSource - * @return an Observable that emits the zipped results + * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in + * an item that will be emitted by the resulting {@code Observable} + * @return an {@code Observable} that emits the zipped results + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, + * {@code source4} or {@code zipper} is {@code null} * @see ReactiveX operators documentation: Zip */ @CheckReturnValue @@ -4475,19 +4603,19 @@ public static Observable zip( } /** - * Returns an Observable that emits the results of a specified combiner function applied to combinations of - * five items emitted, in sequence, by five other ObservableSources. + * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of + * five items emitted, in sequence, by five other {@link ObservableSource}s. *

* *

- * {@code zip} applies this function in strict sequence, so the first item emitted by the new ObservableSource + * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable} * will be the result of the function applied to the first item emitted by {@code o1}, the first item * emitted by {@code o2}, the first item emitted by {@code o3}, the first item emitted by {@code o4}, and - * the first item emitted by {@code o5}; the second item emitted by the new ObservableSource will be the result of - * the function applied to the second item emitted by each of those ObservableSources; and so forth. + * the first item emitted by {@code o5}; the second item emitted by the resulting {@code Observable} will be the result of + * the function applied to the second item emitted by each of those {@code ObservableSource}s; and so forth. *

- * The resulting {@code ObservableSource} returned from {@code zip} will invoke {@link Observer#onNext onNext} - * as many times as the number of {@code onNext} invocations of the source ObservableSource that emits the fewest + * The resulting {@code Observable} returned from {@code zip} will invoke {@link Observer#onNext onNext} + * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest * items. *

* The operator subscribes to its sources in order they are specified and completes eagerly if @@ -4513,19 +4641,21 @@ public static Observable zip( * @param the value type of the fifth source * @param the zipped result type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * a second source ObservableSource + * a second source {@code ObservableSource} * @param source3 - * a third source ObservableSource + * a third source {@code ObservableSource} * @param source4 - * a fourth source ObservableSource + * a fourth source {@code ObservableSource} * @param source5 - * a fifth source ObservableSource + * a fifth source {@code ObservableSource} * @param zipper - * a function that, when applied to an item emitted by each of the source ObservableSources, results in - * an item that will be emitted by the resulting ObservableSource - * @return an Observable that emits the zipped results + * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in + * an item that will be emitted by the resulting {@code Observable} + * @return an {@code Observable} that emits the zipped results + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, + * {@code source4}, {@code source5} or {@code zipper} is {@code null} * @see ReactiveX operators documentation: Zip */ @CheckReturnValue @@ -4545,18 +4675,18 @@ public static Observable zip( } /** - * Returns an Observable that emits the results of a specified combiner function applied to combinations of - * six items emitted, in sequence, by six other ObservableSources. + * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of + * six items emitted, in sequence, by six other {@link ObservableSource}s. *

* *

- * {@code zip} applies this function in strict sequence, so the first item emitted by the new ObservableSource - * will be the result of the function applied to the first item emitted by each source ObservableSource, the - * second item emitted by the new ObservableSource will be the result of the function applied to the second item - * emitted by each of those ObservableSources, and so forth. + * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable} + * will be the result of the function applied to the first item emitted by each source {@code ObservableSource}, the + * second item emitted by the resulting {@code Observable} will be the result of the function applied to the second item + * emitted by each of those {@code ObservableSource}s, and so forth. *

- * The resulting {@code ObservableSource} returned from {@code zip} will invoke {@link Observer#onNext onNext} - * as many times as the number of {@code onNext} invocations of the source ObservableSource that emits the fewest + * The resulting {@code Observable} returned from {@code zip} will invoke {@link Observer#onNext onNext} + * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest * items. *

* The operator subscribes to its sources in order they are specified and completes eagerly if @@ -4583,21 +4713,23 @@ public static Observable zip( * @param the value type of the sixth source * @param the zipped result type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * a second source ObservableSource + * a second source {@code ObservableSource} * @param source3 - * a third source ObservableSource + * a third source {@code ObservableSource} * @param source4 - * a fourth source ObservableSource + * a fourth source {@code ObservableSource} * @param source5 - * a fifth source ObservableSource + * a fifth source {@code ObservableSource} * @param source6 - * a sixth source ObservableSource + * a sixth source {@code ObservableSource} * @param zipper - * a function that, when applied to an item emitted by each of the source ObservableSources, results in - * an item that will be emitted by the resulting ObservableSource - * @return an Observable that emits the zipped results + * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in + * an item that will be emitted by the resulting {@code Observable} + * @return an {@code Observable} that emits the zipped results + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, + * {@code source4}, {@code source5}, {@code source6} or {@code zipper} is {@code null} * @see ReactiveX operators documentation: Zip */ @CheckReturnValue @@ -4618,18 +4750,18 @@ public static Observable zip( } /** - * Returns an Observable that emits the results of a specified combiner function applied to combinations of - * seven items emitted, in sequence, by seven other ObservableSources. + * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of + * seven items emitted, in sequence, by seven other {@link ObservableSource}s. *

* *

- * {@code zip} applies this function in strict sequence, so the first item emitted by the new ObservableSource - * will be the result of the function applied to the first item emitted by each source ObservableSource, the - * second item emitted by the new ObservableSource will be the result of the function applied to the second item - * emitted by each of those ObservableSources, and so forth. + * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable} + * will be the result of the function applied to the first item emitted by each source {@code ObservableSource}, the + * second item emitted by the resulting {@code Observable} will be the result of the function applied to the second item + * emitted by each of those {@code ObservableSource}s, and so forth. *

- * The resulting {@code ObservableSource} returned from {@code zip} will invoke {@link Observer#onNext onNext} - * as many times as the number of {@code onNext} invocations of the source ObservableSource that emits the fewest + * The resulting {@code Observable} returned from {@code zip} will invoke {@link Observer#onNext onNext} + * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest * items. *

* The operator subscribes to its sources in order they are specified and completes eagerly if @@ -4657,23 +4789,26 @@ public static Observable zip( * @param the value type of the seventh source * @param the zipped result type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * a second source ObservableSource + * a second source {@code ObservableSource} * @param source3 - * a third source ObservableSource + * a third source {@code ObservableSource} * @param source4 - * a fourth source ObservableSource + * a fourth source {@code ObservableSource} * @param source5 - * a fifth source ObservableSource + * a fifth source {@code ObservableSource} * @param source6 - * a sixth source ObservableSource + * a sixth source {@code ObservableSource} * @param source7 - * a seventh source ObservableSource + * a seventh source {@code ObservableSource} * @param zipper - * a function that, when applied to an item emitted by each of the source ObservableSources, results in - * an item that will be emitted by the resulting ObservableSource - * @return an Observable that emits the zipped results + * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in + * an item that will be emitted by the resulting {@code Observable} + * @return an {@code Observable} that emits the zipped results + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, + * {@code source4}, {@code source5}, {@code source6}, + * {@code source7} or {@code zipper} is {@code null} * @see ReactiveX operators documentation: Zip */ @CheckReturnValue @@ -4696,18 +4831,18 @@ public static Observable zip( } /** - * Returns an Observable that emits the results of a specified combiner function applied to combinations of - * eight items emitted, in sequence, by eight other ObservableSources. + * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of + * eight items emitted, in sequence, by eight other {@link ObservableSource}s. *

* *

- * {@code zip} applies this function in strict sequence, so the first item emitted by the new ObservableSource - * will be the result of the function applied to the first item emitted by each source ObservableSource, the - * second item emitted by the new ObservableSource will be the result of the function applied to the second item - * emitted by each of those ObservableSources, and so forth. + * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable} + * will be the result of the function applied to the first item emitted by each source {@code ObservableSource}, the + * second item emitted by the resulting {@code Observable} will be the result of the function applied to the second item + * emitted by each of those {@code ObservableSource}s, and so forth. *

- * The resulting {@code ObservableSource} returned from {@code zip} will invoke {@link Observer#onNext onNext} - * as many times as the number of {@code onNext} invocations of the source ObservableSource that emits the fewest + * The resulting {@code Observable} returned from {@code zip} will invoke {@link Observer#onNext onNext} + * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest * items. *

* The operator subscribes to its sources in order they are specified and completes eagerly if @@ -4736,25 +4871,28 @@ public static Observable zip( * @param the value type of the eighth source * @param the zipped result type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * a second source ObservableSource + * a second source {@code ObservableSource} * @param source3 - * a third source ObservableSource + * a third source {@code ObservableSource} * @param source4 - * a fourth source ObservableSource + * a fourth source {@code ObservableSource} * @param source5 - * a fifth source ObservableSource + * a fifth source {@code ObservableSource} * @param source6 - * a sixth source ObservableSource + * a sixth source {@code ObservableSource} * @param source7 - * a seventh source ObservableSource + * a seventh source {@code ObservableSource} * @param source8 - * an eighth source ObservableSource + * an eighth source {@code ObservableSource} * @param zipper - * a function that, when applied to an item emitted by each of the source ObservableSources, results in - * an item that will be emitted by the resulting ObservableSource - * @return an Observable that emits the zipped results + * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in + * an item that will be emitted by the resulting {@code Observable} + * @return an {@code Observable} that emits the zipped results + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, + * {@code source4}, {@code source5}, {@code source6}, + * {@code source7}, {@code source8} or {@code zipper} is {@code null} * @see ReactiveX operators documentation: Zip */ @CheckReturnValue @@ -4778,18 +4916,18 @@ public static Observable zip( } /** - * Returns an Observable that emits the results of a specified combiner function applied to combinations of - * nine items emitted, in sequence, by nine other ObservableSources. + * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of + * nine items emitted, in sequence, by nine other {@link ObservableSource}s. *

* *

- * {@code zip} applies this function in strict sequence, so the first item emitted by the new ObservableSource - * will be the result of the function applied to the first item emitted by each source ObservableSource, the - * second item emitted by the new ObservableSource will be the result of the function applied to the second item - * emitted by each of those ObservableSources, and so forth. + * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable} + * will be the result of the function applied to the first item emitted by each source {@code ObservableSource}, the + * second item emitted by the resulting {@code Observable} will be the result of the function applied to the second item + * emitted by each of those {@code ObservableSource}s, and so forth. *

- * The resulting {@code ObservableSource} returned from {@code zip} will invoke {@link Observer#onNext onNext} - * as many times as the number of {@code onNext} invocations of the source ObservableSource that emits the fewest + * The resulting {@code Observable} returned from {@code zip} will invoke {@link Observer#onNext onNext} + * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest * items. *

* The operator subscribes to its sources in order they are specified and completes eagerly if @@ -4819,27 +4957,30 @@ public static Observable zip( * @param the value type of the ninth source * @param the zipped result type * @param source1 - * the first source ObservableSource + * the first source {@code ObservableSource} * @param source2 - * a second source ObservableSource + * a second source {@code ObservableSource} * @param source3 - * a third source ObservableSource + * a third source {@code ObservableSource} * @param source4 - * a fourth source ObservableSource + * a fourth source {@code ObservableSource} * @param source5 - * a fifth source ObservableSource + * a fifth source {@code ObservableSource} * @param source6 - * a sixth source ObservableSource + * a sixth source {@code ObservableSource} * @param source7 - * a seventh source ObservableSource + * a seventh source {@code ObservableSource} * @param source8 - * an eighth source ObservableSource + * an eighth source {@code ObservableSource} * @param source9 - * a ninth source ObservableSource + * a ninth source {@code ObservableSource} * @param zipper - * a function that, when applied to an item emitted by each of the source ObservableSources, results in - * an item that will be emitted by the resulting ObservableSource - * @return an Observable that emits the zipped results + * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in + * an item that will be emitted by the resulting {@code Observable} + * @return an {@code Observable} that emits the zipped results + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, + * {@code source4}, {@code source5}, {@code source6}, + * {@code source7}, {@code source8}, {@code source9} or {@code zipper} is {@code null} * @see ReactiveX operators documentation: Zip */ @CheckReturnValue @@ -4864,16 +5005,16 @@ public static Observable zip( } /** - * Returns an Observable that emits the results of a specified combiner function applied to combinations of - * items emitted, in sequence, by an array of other ObservableSources. + * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of + * items emitted, in sequence, by an array of other {@link ObservableSource}s. *

- * {@code zip} applies this function in strict sequence, so the first item emitted by the new ObservableSource - * will be the result of the function applied to the first item emitted by each of the source ObservableSources; - * the second item emitted by the new ObservableSource will be the result of the function applied to the second - * item emitted by each of those ObservableSources; and so forth. + * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable} + * will be the result of the function applied to the first item emitted by each of the {@code ObservableSource}s; + * the second item emitted by the resulting {@code Observable} will be the result of the function applied to the second + * item emitted by each of those {@code ObservableSource}s; and so forth. *

- * The resulting {@code ObservableSource} returned from {@code zip} will invoke {@code onNext} as many times as - * the number of {@code onNext} invocations of the source ObservableSource that emits the fewest items. + * The resulting {@code Observable} returned from {@code zip} will invoke {@code onNext} as many times as + * the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest items. *

* The operator subscribes to its sources in order they are specified and completes eagerly if * one of the sources is shorter than the rest while disposing the other sources. Therefore, it @@ -4890,7 +5031,7 @@ public static Observable zip( *

* Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a - * {@code Function} passed to the method would trigger a {@code ClassCastException}. + * {@code Function} passed to the method would trigger a {@link ClassCastException}. * *

* @@ -4902,15 +5043,17 @@ public static Observable zip( * @param the common element type * @param the result type * @param sources - * an array of source ObservableSources + * an array of source {@code ObservableSource}s * @param zipper - * a function that, when applied to an item emitted by each of the source ObservableSources, results in - * an item that will be emitted by the resulting ObservableSource + * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in + * an item that will be emitted by the resulting {@code Observable} * @param delayError - * delay errors signalled by any of the source ObservableSource until all ObservableSources terminate + * delay errors signaled by any of the {@code ObservableSource} until all {@code ObservableSource}s terminate * @param bufferSize - * the number of elements to prefetch from each source ObservableSource - * @return an Observable that emits the zipped results + * the number of elements expected from each source {@code ObservableSource} to be buffered + * @return an {@code Observable} that emits the zipped results + * @throws NullPointerException if {@code sources} or {@code zipper} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Zip */ @CheckReturnValue @@ -4921,6 +5064,7 @@ public static Observable zipArray( @NonNull Function zipper, boolean delayError, int bufferSize, @NonNull ObservableSource... sources) { + Objects.requireNonNull(sources, "sources is null"); if (sources.length == 0) { return empty(); } @@ -4934,8 +5078,8 @@ public static Observable zipArray( // *************************************************************************************************** /** - * Returns a Single that emits a Boolean that indicates whether all of the items emitted by the source - * ObservableSource satisfy a condition. + * Returns a {@link Single} that emits a {@link Boolean} that indicates whether all of the items emitted by the current + * {@code Observable} satisfy a condition. *

* *

@@ -4944,9 +5088,10 @@ public static Observable zipArray( *
* * @param predicate - * a function that evaluates an item and returns a Boolean - * @return a Single that emits {@code true} if all items emitted by the source ObservableSource satisfy the + * a function that evaluates an item and returns a {@code Boolean} + * @return a {@code Single} that emits {@code true} if all items emitted by the current {@code Observable} satisfy the * predicate; otherwise, {@code false} + * @throws NullPointerException if {@code predicate} is {@code null} * @see ReactiveX operators documentation: All */ @CheckReturnValue @@ -4958,7 +5103,7 @@ public final Single all(@NonNull Predicate predicate) { } /** - * Mirrors the ObservableSource (current or provided) that first either emits an item or sends a termination + * Mirrors the current {@code Observable} or the other {@link ObservableSource} provided of which the first either emits an item or sends a termination * notification. *

* @@ -4968,10 +5113,11 @@ public final Single all(@NonNull Predicate predicate) { *

* * @param other - * an ObservableSource competing to react first. A subscription to this provided source will occur after + * an {@code ObservableSource} competing to react first. A subscription to this provided source will occur after * subscribing to the current source. - * @return an Observable that emits the same sequence as whichever of the source ObservableSources first + * @return an {@code Observable} that emits the same sequence as whichever of the current {@code Observable}s first * emitted an item or sent a termination notification + * @throws NullPointerException if {@code other} is {@code null} * @see ReactiveX operators documentation: Amb */ @CheckReturnValue @@ -4983,13 +5129,13 @@ public final Observable ambWith(@NonNull ObservableSource other) } /** - * Returns a Single that emits {@code true} if any item emitted by the source ObservableSource satisfies a + * Returns a {@link Single} that emits {@code true} if any item emitted by the current {@code Observable} satisfies a * specified condition, otherwise {@code false}. Note: this always emits {@code false} if the - * source ObservableSource is empty. + * current {@code Observable} is empty. *

* *

- * In Rx.Net this is the {@code any} Observer but we renamed it in RxJava to better match Java naming + * In Rx.Net this is the {@code any} {@link Observer} but we renamed it in RxJava to better match Java naming * idioms. *

*
Scheduler:
@@ -4997,9 +5143,10 @@ public final Observable ambWith(@NonNull ObservableSource other) *
* * @param predicate - * the condition to test items emitted by the source ObservableSource - * @return a Single that emits a Boolean that indicates whether any item emitted by the source - * ObservableSource satisfies the {@code predicate} + * the condition to test items emitted by the current {@code Observable} + * @return a {@code Single} that emits a {@link Boolean} that indicates whether any item emitted by the current + * {@code Observable} satisfies the {@code predicate} + * @throws NullPointerException if {@code predicate} is {@code null} * @see ReactiveX operators documentation: Contains */ @CheckReturnValue @@ -5011,8 +5158,8 @@ public final Single any(@NonNull Predicate predicate) { } /** - * Returns the first item emitted by this {@code Observable}, or throws - * {@code NoSuchElementException} if it emits no items. + * Returns the first item emitted by the current {@code Observable}, or throws + * {@link NoSuchElementException} if it emits no items. *

* *

@@ -5020,9 +5167,9 @@ public final Single any(@NonNull Predicate predicate) { *
{@code blockingFirst} does not operate by default on a particular {@link Scheduler}.
*
* - * @return the first item emitted by this {@code Observable} + * @return the first item emitted by the current {@code Observable} * @throws NoSuchElementException - * if this {@code Observable} emits no items + * if the current {@code Observable} emits no items * @see ReactiveX documentation: First */ @CheckReturnValue @@ -5039,7 +5186,7 @@ public final T blockingFirst() { } /** - * Returns the first item emitted by this {@code Observable}, or a default value if it emits no + * Returns the first item emitted by the current {@code Observable}, or a default value if it emits no * items. *

* @@ -5049,8 +5196,8 @@ public final T blockingFirst() { *

* * @param defaultItem - * a default value to return if this {@code Observable} emits no items - * @return the first item emitted by this {@code Observable}, or the default value if it emits no + * a default value to return if the current {@code Observable} emits no items + * @return the first item emitted by the current {@code Observable}, or the default value if it emits no * items * @see ReactiveX documentation: First */ @@ -5065,8 +5212,8 @@ public final T blockingFirst(@NonNull T defaultItem) { } /** - * Consumes the upstream {@code Observable} in a blocking fashion and invokes the given - * {@code Consumer} with each upstream item on the current thread until the + * Consumes the current {@code Observable} in a blocking fashion and invokes the given + * {@link Consumer} with each upstream item on the current thread until the * upstream terminates. *

* @@ -5087,7 +5234,7 @@ public final T blockingFirst(@NonNull T defaultItem) { *

* * @param onNext - * the {@link Consumer} to invoke for each item emitted by the {@code Observable} + * the {@code Consumer} to invoke for each item emitted by the {@code Observable} * @throws RuntimeException * if an error occurs * @see ReactiveX documentation: Subscribe @@ -5101,8 +5248,8 @@ public final void blockingForEach(@NonNull Consumer onNext) { } /** - * Consumes the upstream {@code Observable} in a blocking fashion and invokes the given - * {@code Consumer} with each upstream item on the current thread until the + * Consumes the current {@code Observable} in a blocking fashion and invokes the given + * {@link Consumer} with each upstream item on the current thread until the * upstream terminates. *

* @@ -5123,18 +5270,21 @@ public final void blockingForEach(@NonNull Consumer onNext) { *

* * @param onNext - * the {@link Consumer} to invoke for each item emitted by the {@code Observable} + * the {@code Consumer} to invoke for each item emitted by the {@code Observable} * @param capacityHint * the number of items expected to be buffered (allows reducing buffer reallocations) + * @throws NullPointerException if {@code onNext} is {@code null} + * @throws IllegalArgumentException if {@code capacityHint} is non-positive * @throws RuntimeException - * if an error occurs; {@link Error}s and {@link RuntimeException}s are rethrown - * as they are, checked {@link Exception}s are wrapped into {@code RuntimeException}s + * if an error occurs; {@code Error}s and {@code RuntimeException}s are rethrown + * as they are, checked {@code Exception}s are wrapped into {@code RuntimeException}s * @see ReactiveX documentation: Subscribe * @see #subscribe(Consumer) */ @SchedulerSupport(SchedulerSupport.NONE) @NonNull public final void blockingForEach(@NonNull Consumer onNext, int capacityHint) { + Objects.requireNonNull(onNext, "onNext is null"); Iterator it = blockingIterable(capacityHint).iterator(); while (it.hasNext()) { try { @@ -5148,7 +5298,9 @@ public final void blockingForEach(@NonNull Consumer onNext, int capac } /** - * Converts this {@code Observable} into an {@link Iterable}. + * Exposes the current {@code Observable} as an {@link Iterable} which, when iterated, + * subscribes to the current {@code Observable} and blocks + * until the current {@code Observable} emits items or terminates. *

* *

@@ -5156,7 +5308,7 @@ public final void blockingForEach(@NonNull Consumer onNext, int capac *
{@code blockingIterable} does not operate by default on a particular {@link Scheduler}.
*
* - * @return an {@link Iterable} version of this {@code Observable} + * @return the new {@code Iterable} instance * @see ReactiveX documentation: To */ @CheckReturnValue @@ -5167,7 +5319,9 @@ public final Iterable blockingIterable() { } /** - * Converts this {@code Observable} into an {@link Iterable}. + * Exposes the current {@code Observable} as an {@link Iterable} which, when iterated, + * subscribes to the current {@code Observable} and blocks + * until the current {@code Observable} emits items or terminates. *

* *

@@ -5176,7 +5330,8 @@ public final Iterable blockingIterable() { *
* * @param capacityHint the expected number of items to be buffered - * @return an {@link Iterable} version of this {@code Observable} + * @return the new {@code Iterable} instance + * @throws IllegalArgumentException if {@code capacityHint} is non-positive * @see ReactiveX documentation: To */ @CheckReturnValue @@ -5188,8 +5343,8 @@ public final Iterable blockingIterable(int capacityHint) { } /** - * Returns the last item emitted by this {@code Observable}, or throws - * {@code NoSuchElementException} if this {@code Observable} emits no items. + * Returns the last item emitted by the current {@code Observable}, or throws + * {@link NoSuchElementException} if the current {@code Observable} emits no items. *

* *

@@ -5201,9 +5356,9 @@ public final Iterable blockingIterable(int capacityHint) { * {@link Error}s are rethrown as they are.
*
* - * @return the last item emitted by this {@code Observable} + * @return the last item emitted by the current {@code Observable} * @throws NoSuchElementException - * if this {@code Observable} emits no items + * if the current {@code Observable} emits no items * @see ReactiveX documentation: Last */ @CheckReturnValue @@ -5220,7 +5375,7 @@ public final T blockingLast() { } /** - * Returns the last item emitted by this {@code Observable}, or a default value if it emits no + * Returns the last item emitted by the current {@code Observable}, or a default value if it emits no * items. *

* @@ -5234,7 +5389,7 @@ public final T blockingLast() { *

* * @param defaultItem - * a default value to return if this {@code Observable} emits no items + * a default value to return if the current {@code Observable} emits no items * @return the last item emitted by the {@code Observable}, or the default value if it emits no * items * @see ReactiveX documentation: Last @@ -5250,12 +5405,12 @@ public final T blockingLast(@NonNull T defaultItem) { } /** - * Returns an {@link Iterable} that returns the latest item emitted by this {@code Observable}, + * Returns an {@link Iterable} that returns the latest item emitted by the current {@code Observable}, * waiting if necessary for one to become available. *

* *

- * If this {@code Observable} produces items faster than {@code Iterator.next} takes them, + * If the current {@code Observable} produces items faster than {@code Iterator.next} takes them, * {@code onNext} events might be skipped, but {@code onError} or {@code onComplete} events are not. *

* Note also that an {@code onNext} directly followed by {@code onComplete} might hide the {@code onNext} @@ -5265,7 +5420,7 @@ public final T blockingLast(@NonNull T defaultItem) { *

{@code blockingLatest} does not operate by default on a particular {@link Scheduler}.
*
* - * @return an Iterable that always returns the latest item emitted by this {@code Observable} + * @return an {@code Iterable} that always returns the latest item emitted by the current {@code Observable} * @see ReactiveX documentation: First */ @CheckReturnValue @@ -5276,7 +5431,7 @@ public final Iterable blockingLatest() { } /** - * Returns an {@link Iterable} that always returns the item most recently emitted by this + * Returns an {@link Iterable} that always returns the item most recently emitted by the current * {@code Observable}. *

* @@ -5286,9 +5441,9 @@ public final Iterable blockingLatest() { *

* * @param initialValue - * the initial value that the {@link Iterable} sequence will yield if this + * the initial value that the {@code Iterable} sequence will yield if the current * {@code Observable} has not yet emitted an item - * @return an {@link Iterable} that on each iteration returns the item that this {@code Observable} + * @return an {@code Iterable} that on each iteration returns the item that the current {@code Observable} * has most recently emitted * @see ReactiveX documentation: First */ @@ -5300,7 +5455,7 @@ public final Iterable blockingMostRecent(@NonNull T initialValue) { } /** - * Returns an {@link Iterable} that blocks until this {@code Observable} emits another item, then + * Returns an {@link Iterable} that blocks until the current {@code Observable} emits another item, then * returns that item. *

* @@ -5309,8 +5464,8 @@ public final Iterable blockingMostRecent(@NonNull T initialValue) { *

{@code blockingNext} does not operate by default on a particular {@link Scheduler}.
*
* - * @return an {@link Iterable} that blocks upon each iteration until this {@code Observable} emits - * a new item, whereupon the Iterable returns that item + * @return an {@code Iterable} that blocks upon each iteration until the current {@code Observable} emits + * a new item, whereupon the {@code Iterable} returns that item * @see ReactiveX documentation: TakeLast */ @CheckReturnValue @@ -5321,8 +5476,8 @@ public final Iterable blockingNext() { } /** - * If this {@code Observable} completes after emitting a single item, return that item, otherwise - * throw a {@code NoSuchElementException}. + * If the current {@code Observable} completes after emitting a single item, return that item, otherwise + * throw a {@link NoSuchElementException}. *

* *

@@ -5334,7 +5489,7 @@ public final Iterable blockingNext() { * {@link Error}s are rethrown as they are.
*
* - * @return the single item emitted by this {@code Observable} + * @return the single item emitted by the current {@code Observable} * @see ReactiveX documentation: First */ @CheckReturnValue @@ -5349,8 +5504,8 @@ public final T blockingSingle() { } /** - * If this {@code Observable} completes after emitting a single item, return that item; if it emits - * more than one item, throw an {@code IllegalArgumentException}; if it emits no items, return a default + * If the current {@code Observable} completes after emitting a single item, return that item; if it emits + * more than one item, throw an {@link IllegalArgumentException}; if it emits no items, return a default * value. *

* @@ -5364,8 +5519,8 @@ public final T blockingSingle() { *

* * @param defaultItem - * a default value to return if this {@code Observable} emits no items - * @return the single item emitted by this {@code Observable}, or the default value if it emits no + * a default value to return if the current {@code Observable} emits no items + * @return the single item emitted by the current {@code Observable}, or the default value if it emits no * items * @see ReactiveX documentation: First */ @@ -5377,13 +5532,13 @@ public final T blockingSingle(@NonNull T defaultItem) { } /** - * Returns a {@link Future} representing the only value emitted by this {@code Observable}. + * Returns a {@link Future} representing the only value emitted by the current {@code Observable}. *

* *

- * If the {@link Observable} emits more than one item, {@link java.util.concurrent.Future} will receive an - * {@link java.lang.IndexOutOfBoundsException}. If the {@link Observable} is empty, {@link java.util.concurrent.Future} - * will receive an {@link java.util.NoSuchElementException}. The {@code Observable} source has to terminate in order + * If the {@code Observable} emits more than one item, {@code Future} will receive an + * {@link IndexOutOfBoundsException}. If the {@code Observable} is empty, {@code Future} + * will receive an {@link NoSuchElementException}. The {@code Observable} source has to terminate in order * for the returned {@code Future} to terminate as well. *

* If the {@code Observable} may emit more than one item, use {@code Observable.toList().toFuture()}. @@ -5392,8 +5547,9 @@ public final T blockingSingle(@NonNull T defaultItem) { *

{@code toFuture} does not operate by default on a particular {@link Scheduler}.
*
* - * @return a {@link Future} that expects a single item to be emitted by this {@code Observable} + * @return a {@code Future} that expects a single item to be emitted by the current {@code Observable} * @see ReactiveX documentation: To + * @see #singleOrErrorStage() */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -5403,7 +5559,7 @@ public final Future toFuture() { } /** - * Runs the source observable to a terminal event, ignoring any values and rethrowing any exception. + * Runs the current {@code Observable} to a terminal event, ignoring any values and rethrowing any exception. *

* *

@@ -5430,8 +5586,8 @@ public final void blockingSubscribe() { * *

* If the {@code Observable} emits an error, it is wrapped into an - * {@link io.reactivex.rxjava3.exceptions.OnErrorNotImplementedException OnErrorNotImplementedException} - * and routed to the RxJavaPlugins.onError handler. + * {@link OnErrorNotImplementedException} + * and routed to the {@link RxJavaPlugins#onError(Throwable)} handler. * Using the overloads {@link #blockingSubscribe(Consumer, Consumer)} * or {@link #blockingSubscribe(Consumer, Consumer, Action)} instead is recommended. *

@@ -5510,18 +5666,20 @@ public final void blockingSubscribe(@NonNull Consumer onNext, @NonNul *

* The a dispose() call is composed through. * @param observer the {@code Observer} instance to forward events and calls to in the current thread + * @throws NullPointerException if {@code observer} is {@code null} * @since 2.0 */ @SchedulerSupport(SchedulerSupport.NONE) public final void blockingSubscribe(@NonNull Observer observer) { + Objects.requireNonNull(observer, "observer is null"); ObservableBlockingSubscribe.subscribe(this, observer); } /** - * Returns an Observable that emits buffers of items it collects from the source ObservableSource. The resulting - * ObservableSource emits connected, non-overlapping buffers, each containing {@code count} items. When the source - * ObservableSource completes, the resulting ObservableSource emits the current buffer and propagates the notification - * from the source ObservableSource. Note that if the source ObservableSource issues an onError notification + * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits connected, non-overlapping buffers, each containing {@code count} items. When the current + * {@code Observable} completes, the resulting {@code Observable} emits the current buffer and propagates the notification + * from the current {@code Observable}. Note that if the current {@code Observable} issues an {@code onError} notification * the event is passed on immediately without first emitting the buffer it is in the process of assembling. *

* @@ -5532,8 +5690,9 @@ public final void blockingSubscribe(@NonNull Observer observer) { * * @param count * the maximum number of items in each buffer before it should be emitted - * @return an Observable that emits connected, non-overlapping buffers, each containing at most - * {@code count} items from the source ObservableSource + * @return an {@code Observable} that emits connected, non-overlapping buffers, each containing at most + * {@code count} items from the current {@code Observable} + * @throws IllegalArgumentException if {@code count} is non-positive * @see ReactiveX operators documentation: Buffer */ @CheckReturnValue @@ -5544,10 +5703,10 @@ public final void blockingSubscribe(@NonNull Observer observer) { } /** - * Returns an Observable that emits buffers of items it collects from the source ObservableSource. The resulting - * ObservableSource emits buffers every {@code skip} items, each containing {@code count} items. When the source - * ObservableSource completes, the resulting ObservableSource emits the current buffer and propagates the notification - * from the source ObservableSource. Note that if the source ObservableSource issues an onError notification + * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits buffers every {@code skip} items, each containing {@code count} items. When the current + * {@code Observable} completes, the resulting {@code Observable} emits the current buffer and propagates the notification + * from the current {@code Observable}. Note that if the current {@code Observable} issues an {@code onError} notification * the event is passed on immediately without first emitting the buffer it is in the process of assembling. *

* @@ -5559,11 +5718,12 @@ public final void blockingSubscribe(@NonNull Observer observer) { * @param count * the maximum size of each buffer before it should be emitted * @param skip - * how many items emitted by the source ObservableSource should be skipped before starting a new + * how many items emitted by the current {@code Observable} should be skipped before starting a new * buffer. Note that when {@code skip} and {@code count} are equal, this is the same operation as * {@link #buffer(int)}. - * @return an Observable that emits buffers for every {@code skip} item from the source ObservableSource and + * @return an {@code Observable} that emits buffers for every {@code skip} item from the current {@code Observable} and * containing at most {@code count} items + * @throws IllegalArgumentException if {@code count} or {@code skip} is non-positive * @see ReactiveX operators documentation: Buffer */ @CheckReturnValue @@ -5574,10 +5734,10 @@ public final void blockingSubscribe(@NonNull Observer observer) { } /** - * Returns an Observable that emits buffers of items it collects from the source ObservableSource. The resulting - * ObservableSource emits buffers every {@code skip} items, each containing {@code count} items. When the source - * ObservableSource completes, the resulting ObservableSource emits the current buffer and propagates the notification - * from the source ObservableSource. Note that if the source ObservableSource issues an onError notification + * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits buffers every {@code skip} items, each containing {@code count} items. When the current + * {@code Observable} completes, the resulting {@code Observable} emits the current buffer and propagates the notification + * from the current {@code Observable}. Note that if the current {@code Observable} issues an {@code onError} notification * the event is passed on immediately without first emitting the buffer it is in the process of assembling. *

* @@ -5590,14 +5750,16 @@ public final void blockingSubscribe(@NonNull Observer observer) { * @param count * the maximum size of each buffer before it should be emitted * @param skip - * how many items emitted by the source ObservableSource should be skipped before starting a new + * how many items emitted by the current {@code Observable} should be skipped before starting a new * buffer. Note that when {@code skip} and {@code count} are equal, this is the same operation as * {@link #buffer(int)}. * @param bufferSupplier * a factory function that returns an instance of the collection subclass to be used and returned * as the buffer - * @return an Observable that emits buffers for every {@code skip} item from the source ObservableSource and + * @return an {@code Observable} that emits buffers for every {@code skip} item from the current {@code Observable} and * containing at most {@code count} items + * @throws NullPointerException if {@code bufferSupplier} is {@code null} + * @throws IllegalArgumentException if {@code count} or {@code skip} is non-positive * @see ReactiveX operators documentation: Buffer */ @CheckReturnValue @@ -5611,10 +5773,10 @@ public final > Observable buffer(int count, i } /** - * Returns an Observable that emits buffers of items it collects from the source ObservableSource. The resulting - * ObservableSource emits connected, non-overlapping buffers, each containing {@code count} items. When the source - * ObservableSource completes, the resulting ObservableSource emits the current buffer and propagates the notification - * from the source ObservableSource. Note that if the source ObservableSource issues an onError notification + * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits connected, non-overlapping buffers, each containing {@code count} items. When the current + * {@code Observable} completes, the resulting {@code Observable} emits the current buffer and propagates the notification + * from the current {@code Observable}. Note that if the current {@code Observable} issues an {@code onError} notification * the event is passed on immediately without first emitting the buffer it is in the process of assembling. *

* @@ -5629,8 +5791,10 @@ public final > Observable buffer(int count, i * @param bufferSupplier * a factory function that returns an instance of the collection subclass to be used and returned * as the buffer - * @return an Observable that emits connected, non-overlapping buffers, each containing at most - * {@code count} items from the source ObservableSource + * @return an {@code Observable} that emits connected, non-overlapping buffers, each containing at most + * {@code count} items from the current {@code Observable} + * @throws NullPointerException if {@code bufferSupplier} is {@code null} + * @throws IllegalArgumentException if {@code count} is non-positive * @see ReactiveX operators documentation: Buffer */ @CheckReturnValue @@ -5641,11 +5805,11 @@ public final > Observable buffer(int count, i } /** - * Returns an Observable that emits buffers of items it collects from the source ObservableSource. The resulting - * ObservableSource starts a new buffer periodically, as determined by the {@code timeskip} argument. It emits - * each buffer after a fixed timespan, specified by the {@code timespan} argument. When the source - * ObservableSource completes, the resulting ObservableSource emits the current buffer and propagates the notification - * from the source ObservableSource. Note that if the source ObservableSource issues an onError notification + * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting + * {@code Observable} starts a new buffer periodically, as determined by the {@code timeskip} argument. It emits + * each buffer after a fixed timespan, specified by the {@code timespan} argument. When the current + * {@code Observable} completes, the resulting {@code Observable} emits the current buffer and propagates the notification + * from the current {@code Observable}. Note that if the current {@code Observable} issues an {@code onError} notification * the event is passed on immediately without first emitting the buffer it is in the process of assembling. *

* @@ -5660,8 +5824,9 @@ public final > Observable buffer(int count, i * the period of time after which a new buffer will be created * @param unit * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments - * @return an Observable that emits new buffers of items emitted by the source ObservableSource periodically after + * @return an {@code Observable} that emits new buffers of items emitted by the current {@code Observable} periodically after * a fixed timespan has elapsed + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: Buffer */ @CheckReturnValue @@ -5672,12 +5837,12 @@ public final > Observable buffer(int count, i } /** - * Returns an Observable that emits buffers of items it collects from the source ObservableSource. The resulting - * ObservableSource starts a new buffer periodically, as determined by the {@code timeskip} argument, and on the + * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting + * {@code Observable} starts a new buffer periodically, as determined by the {@code timeskip} argument, and on the * specified {@code scheduler}. It emits each buffer after a fixed timespan, specified by the - * {@code timespan} argument. When the source ObservableSource completes, the resulting ObservableSource emits the - * current buffer and propagates the notification from the source ObservableSource. Note that if the source - * ObservableSource issues an onError notification the event is passed on immediately without first emitting the + * {@code timespan} argument. When the current {@code Observable} completes, the resulting {@code Observable} emits the + * current buffer and propagates the notification from the current {@code Observable}. Note that if the current + * {@code Observable} issues an {@code onError} notification the event is passed on immediately without first emitting the * buffer it is in the process of assembling. *

* @@ -5693,9 +5858,10 @@ public final > Observable buffer(int count, i * @param unit * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments * @param scheduler - * the {@link Scheduler} to use when determining the end and start of a buffer - * @return an Observable that emits new buffers of items emitted by the source ObservableSource periodically after + * the {@code Scheduler} to use when determining the end and start of a buffer + * @return an {@code Observable} that emits new buffers of items emitted by the current {@code Observable} periodically after * a fixed timespan has elapsed + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Buffer */ @CheckReturnValue @@ -5706,12 +5872,12 @@ public final > Observable buffer(int count, i } /** - * Returns an Observable that emits buffers of items it collects from the source ObservableSource. The resulting - * ObservableSource starts a new buffer periodically, as determined by the {@code timeskip} argument, and on the + * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting + * {@code Observable} starts a new buffer periodically, as determined by the {@code timeskip} argument, and on the * specified {@code scheduler}. It emits each buffer after a fixed timespan, specified by the - * {@code timespan} argument. When the source ObservableSource completes, the resulting ObservableSource emits the - * current buffer and propagates the notification from the source ObservableSource. Note that if the source - * ObservableSource issues an onError notification the event is passed on immediately without first emitting the + * {@code timespan} argument. When the current {@code Observable} completes, the resulting {@code Observable} emits the + * current buffer and propagates the notification from the current {@code Observable}. Note that if the current + * {@code Observable} issues an {@code onError} notification the event is passed on immediately without first emitting the * buffer it is in the process of assembling. *

* @@ -5728,12 +5894,13 @@ public final > Observable buffer(int count, i * @param unit * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments * @param scheduler - * the {@link Scheduler} to use when determining the end and start of a buffer + * the {@code Scheduler} to use when determining the end and start of a buffer * @param bufferSupplier * a factory function that returns an instance of the collection subclass to be used and returned * as the buffer - * @return an Observable that emits new buffers of items emitted by the source ObservableSource periodically after + * @return an {@code Observable} that emits new buffers of items emitted by the current {@code Observable} periodically after * a fixed timespan has elapsed + * @throws NullPointerException if {@code unit}, {@code scheduler} or {@code bufferSupplier} is {@code null} * @see ReactiveX operators documentation: Buffer */ @CheckReturnValue @@ -5747,11 +5914,11 @@ public final > Observable buffer(int count, i } /** - * Returns an Observable that emits buffers of items it collects from the source ObservableSource. The resulting - * ObservableSource emits connected, non-overlapping buffers, each of a fixed duration specified by the - * {@code timespan} argument. When the source ObservableSource completes, the resulting ObservableSource emits the - * current buffer and propagates the notification from the source ObservableSource. Note that if the source - * ObservableSource issues an onError notification the event is passed on immediately without first emitting the + * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits connected, non-overlapping buffers, each of a fixed duration specified by the + * {@code timespan} argument. When the current {@code Observable} completes, the resulting {@code Observable} emits the + * current buffer and propagates the notification from the current {@code Observable}. Note that if the current + * {@code Observable} issues an {@code onError} notification the event is passed on immediately without first emitting the * buffer it is in the process of assembling. *

* @@ -5765,8 +5932,8 @@ public final > Observable buffer(int count, i * buffer * @param unit * the unit of time that applies to the {@code timespan} argument - * @return an Observable that emits connected, non-overlapping buffers of items emitted by the source - * ObservableSource within a fixed duration + * @return an {@code Observable} that emits connected, non-overlapping buffers of items emitted by the current + * {@code Observable} within a fixed duration * @see ReactiveX operators documentation: Buffer */ @CheckReturnValue @@ -5777,12 +5944,12 @@ public final > Observable buffer(int count, i } /** - * Returns an Observable that emits buffers of items it collects from the source ObservableSource. The resulting - * ObservableSource emits connected, non-overlapping buffers, each of a fixed duration specified by the + * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits connected, non-overlapping buffers, each of a fixed duration specified by the * {@code timespan} argument or a maximum size specified by the {@code count} argument (whichever is reached - * first). When the source ObservableSource completes, the resulting ObservableSource emits the current buffer and - * propagates the notification from the source ObservableSource. Note that if the source ObservableSource issues an - * onError notification the event is passed on immediately without first emitting the buffer it is in the process of + * first). When the current {@code Observable} completes, the resulting {@code Observable} emits the current buffer and + * propagates the notification from the current {@code Observable}. Note that if the current {@code Observable} issues an + * {@code onError} notification the event is passed on immediately without first emitting the buffer it is in the process of * assembling. *

* @@ -5798,8 +5965,8 @@ public final > Observable buffer(int count, i * the unit of time which applies to the {@code timespan} argument * @param count * the maximum size of each buffer before it is emitted - * @return an Observable that emits connected, non-overlapping buffers of items emitted by the source - * ObservableSource, after a fixed duration or when the buffer reaches maximum capacity (whichever occurs + * @return an {@code Observable} that emits connected, non-overlapping buffers of items emitted by the current + * {@code Observable}, after a fixed duration or when the buffer reaches maximum capacity (whichever occurs * first) * @see ReactiveX operators documentation: Buffer */ @@ -5811,12 +5978,12 @@ public final > Observable buffer(int count, i } /** - * Returns an Observable that emits buffers of items it collects from the source ObservableSource. The resulting - * ObservableSource emits connected, non-overlapping buffers, each of a fixed duration specified by the + * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits connected, non-overlapping buffers, each of a fixed duration specified by the * {@code timespan} argument as measured on the specified {@code scheduler}, or a maximum size specified by - * the {@code count} argument (whichever is reached first). When the source ObservableSource completes, the resulting - * ObservableSource emits the current buffer and propagates the notification from the source ObservableSource. Note - * that if the source ObservableSource issues an onError notification the event is passed on immediately without + * the {@code count} argument (whichever is reached first). When the current {@code Observable} completes, the resulting + * {@code Observable} emits the current buffer and propagates the notification from the current {@code Observable}. Note + * that if the current {@code Observable} issues an {@code onError} notification the event is passed on immediately without * first emitting the buffer it is in the process of assembling. *

* @@ -5831,11 +5998,11 @@ public final > Observable buffer(int count, i * @param unit * the unit of time which applies to the {@code timespan} argument * @param scheduler - * the {@link Scheduler} to use when determining the end and start of a buffer + * the {@code Scheduler} to use when determining the end and start of a buffer * @param count * the maximum size of each buffer before it is emitted - * @return an Observable that emits connected, non-overlapping buffers of items emitted by the source - * ObservableSource after a fixed duration or when the buffer reaches maximum capacity (whichever occurs + * @return an {@code Observable} that emits connected, non-overlapping buffers of items emitted by the current + * {@code Observable} after a fixed duration or when the buffer reaches maximum capacity (whichever occurs * first) * @see ReactiveX operators documentation: Buffer */ @@ -5847,12 +6014,12 @@ public final > Observable buffer(int count, i } /** - * Returns an Observable that emits buffers of items it collects from the source ObservableSource. The resulting - * ObservableSource emits connected, non-overlapping buffers, each of a fixed duration specified by the + * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits connected, non-overlapping buffers, each of a fixed duration specified by the * {@code timespan} argument as measured on the specified {@code scheduler}, or a maximum size specified by - * the {@code count} argument (whichever is reached first). When the source ObservableSource completes, the resulting - * ObservableSource emits the current buffer and propagates the notification from the source ObservableSource. Note - * that if the source ObservableSource issues an onError notification the event is passed on immediately without + * the {@code count} argument (whichever is reached first). When the current {@code Observable} completes, the resulting + * {@code Observable} emits the current buffer and propagates the notification from the current {@code Observable}. Note + * that if the current {@code Observable} issues an {@code onError} notification the event is passed on immediately without * first emitting the buffer it is in the process of assembling. *

* @@ -5868,17 +6035,19 @@ public final > Observable buffer(int count, i * @param unit * the unit of time which applies to the {@code timespan} argument * @param scheduler - * the {@link Scheduler} to use when determining the end and start of a buffer + * the {@code Scheduler} to use when determining the end and start of a buffer * @param count * the maximum size of each buffer before it is emitted * @param bufferSupplier * a factory function that returns an instance of the collection subclass to be used and returned * as the buffer - * @param restartTimerOnMaxSize if true the time window is restarted when the max capacity of the current buffer + * @param restartTimerOnMaxSize if {@code true}, the time window is restarted when the max capacity of the current buffer * is reached - * @return an Observable that emits connected, non-overlapping buffers of items emitted by the source - * ObservableSource after a fixed duration or when the buffer reaches maximum capacity (whichever occurs + * @return an {@code Observable} that emits connected, non-overlapping buffers of items emitted by the current + * {@code Observable} after a fixed duration or when the buffer reaches maximum capacity (whichever occurs * first) + * @throws NullPointerException if {@code unit}, {@code scheduler} or {@code bufferSupplier} is {@code null} + * @throws IllegalArgumentException if {@code count} is non-positive * @see ReactiveX operators documentation: Buffer */ @CheckReturnValue @@ -5897,11 +6066,11 @@ public final > Observable buffer(int count, i } /** - * Returns an Observable that emits buffers of items it collects from the source ObservableSource. The resulting - * ObservableSource emits connected, non-overlapping buffers, each of a fixed duration specified by the - * {@code timespan} argument and on the specified {@code scheduler}. When the source ObservableSource completes, - * the resulting ObservableSource emits the current buffer and propagates the notification from the source - * ObservableSource. Note that if the source ObservableSource issues an onError notification the event is passed on + * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits connected, non-overlapping buffers, each of a fixed duration specified by the + * {@code timespan} argument and on the specified {@code scheduler}. When the current {@code Observable} completes, + * the resulting {@code Observable} emits the current buffer and propagates the notification from the current + * {@code Observable}. Note that if the current {@code Observable} issues an {@code onError} notification the event is passed on * immediately without first emitting the buffer it is in the process of assembling. *

* @@ -5916,9 +6085,10 @@ public final > Observable buffer(int count, i * @param unit * the unit of time which applies to the {@code timespan} argument * @param scheduler - * the {@link Scheduler} to use when determining the end and start of a buffer - * @return an Observable that emits connected, non-overlapping buffers of items emitted by the source - * ObservableSource within a fixed duration + * the {@code Scheduler} to use when determining the end and start of a buffer + * @return an {@code Observable} that emits connected, non-overlapping buffers of items emitted by the current + * {@code Observable} within a fixed duration + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Buffer */ @CheckReturnValue @@ -5929,10 +6099,10 @@ public final > Observable buffer(int count, i } /** - * Returns an Observable that emits buffers of items it collects from the source ObservableSource. The resulting - * ObservableSource emits buffers that it creates when the specified {@code openingIndicator} ObservableSource emits an - * item, and closes when the ObservableSource returned from {@code closingIndicator} emits an item. If any of the - * source ObservableSource, {@code openingIndicator} or {@code closingIndicator} issues an onError notification the + * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits buffers that it creates when the specified {@code openingIndicator} {@link ObservableSource} emits an + * item, and closes when the {@code ObservableSource} returned from {@code closingIndicator} emits an item. If any of the + * current {@code Observable}, {@code openingIndicator} or {@code closingIndicator} issues an {@code onError} notification the * event is passed on immediately without first emitting the buffer it is in the process of assembling. *

* @@ -5941,15 +6111,16 @@ public final > Observable buffer(int count, i *

This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the element type of the buffer-opening ObservableSource - * @param the element type of the individual buffer-closing ObservableSources + * @param the element type of the buffer-opening {@code ObservableSource} + * @param the element type of the individual buffer-closing {@code ObservableSource}s * @param openingIndicator - * the ObservableSource that, when it emits an item, causes a new buffer to be created + * the {@code ObservableSource} that, when it emits an item, causes a new buffer to be created * @param closingIndicator - * the {@link Function} that is used to produce an ObservableSource for every buffer created. When this - * ObservableSource emits an item, the associated buffer is emitted. - * @return an Observable that emits buffers, containing items from the source ObservableSource, that are created - * and closed when the specified ObservableSources emit items + * the {@link Function} that is used to produce an {@code ObservableSource} for every buffer created. When this indicator + * {@code ObservableSource} emits an item, the associated buffer is emitted. + * @return an {@code Observable} that emits buffers, containing items from the current {@code Observable}, that are created + * and closed when the specified {@code ObservableSource}s emit items + * @throws NullPointerException if {@code openingIndicator} or {@code closingIndicator} is {@code null} * @see ReactiveX operators documentation: Buffer */ @CheckReturnValue @@ -5962,10 +6133,10 @@ public final > Observable buffer(int count, i } /** - * Returns an Observable that emits buffers of items it collects from the source ObservableSource. The resulting - * ObservableSource emits buffers that it creates when the specified {@code openingIndicator} ObservableSource emits an - * item, and closes when the ObservableSource returned from {@code closingIndicator} emits an item. If any of the - * source ObservableSource, {@code openingIndicator} or {@code closingIndicator} issues an onError notification the + * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits buffers that it creates when the specified {@code openingIndicator} {@link ObservableSource} emits an + * item, and closes when the {@code ObservableSource} returned from {@code closingIndicator} emits an item. If any of the + * current {@code Observable}, {@code openingIndicator} or {@code closingIndicator} issues an {@code onError} notification the * event is passed on immediately without first emitting the buffer it is in the process of assembling. *

* @@ -5975,18 +6146,19 @@ public final > Observable buffer(int count, i *

* * @param the collection subclass type to buffer into - * @param the element type of the buffer-opening ObservableSource - * @param the element type of the individual buffer-closing ObservableSources + * @param the element type of the buffer-opening {@code ObservableSource} + * @param the element type of the individual buffer-closing {@code ObservableSource}s * @param openingIndicator - * the ObservableSource that, when it emits an item, causes a new buffer to be created + * the {@code ObservableSource} that, when it emits an item, causes a new buffer to be created * @param closingIndicator - * the {@link Function} that is used to produce an ObservableSource for every buffer created. When this - * ObservableSource emits an item, the associated buffer is emitted. + * the {@link Function} that is used to produce an {@code ObservableSource} for every buffer created. When this indicator + * {@code ObservableSource} emits an item, the associated buffer is emitted. * @param bufferSupplier * a factory function that returns an instance of the collection subclass to be used and returned * as the buffer - * @return an Observable that emits buffers, containing items from the source ObservableSource, that are created - * and closed when the specified ObservableSources emit items + * @return an {@code Observable} that emits buffers, containing items from the current {@code Observable}, that are created + * and closed when the specified {@code ObservableSource}s emit items + * @throws NullPointerException if {@code openingIndicator}, {@code closingIndicator} or {@code bufferSupplier} is {@code null} * @see ReactiveX operators documentation: Buffer */ @CheckReturnValue @@ -6003,14 +6175,14 @@ public final > Observable buffer(int count, i } /** - * Returns an Observable that emits non-overlapping buffered items from the source ObservableSource each time the - * specified boundary ObservableSource emits an item. + * Returns an {@code Observable} that emits non-overlapping buffered items from the current {@code Observable} each time the + * specified boundary {@link ObservableSource} emits an item. *

* *

- * Completion of either the source or the boundary ObservableSource causes the returned ObservableSource to emit the - * latest buffer and complete. If either the source ObservableSource or the boundary ObservableSource issues an - * onError notification the event is passed on immediately without first emitting the buffer it is in the process of + * Completion of either the source or the boundary {@code ObservableSource} causes the returned {@code ObservableSource} to emit the + * latest buffer and complete. If either the current {@code Observable} or the boundary {@code ObservableSource} issues an + * {@code onError} notification the event is passed on immediately without first emitting the buffer it is in the process of * assembling. *

*
Scheduler:
@@ -6020,8 +6192,8 @@ public final > Observable buffer(int count, i * @param * the boundary value type (ignored) * @param boundary - * the boundary ObservableSource - * @return an Observable that emits buffered items from the source ObservableSource when the boundary ObservableSource + * the boundary {@code ObservableSource} + * @return an {@code Observable} that emits buffered items from the current {@code Observable} when the boundary {@code ObservableSource} * emits an item * @see #buffer(ObservableSource, int) * @see ReactiveX operators documentation: Buffer @@ -6034,14 +6206,14 @@ public final > Observable buffer(int count, i } /** - * Returns an Observable that emits non-overlapping buffered items from the source ObservableSource each time the - * specified boundary ObservableSource emits an item. + * Returns an {@code Observable} that emits non-overlapping buffered items from the current {@code Observable} each time the + * specified boundary {@link ObservableSource} emits an item. *

* *

- * Completion of either the source or the boundary ObservableSource causes the returned ObservableSource to emit the - * latest buffer and complete. If either the source ObservableSource or the boundary ObservableSource issues an - * onError notification the event is passed on immediately without first emitting the buffer it is in the process of + * Completion of either the source or the boundary {@code ObservableSource} causes the returned {@code ObservableSource} to emit the + * latest buffer and complete. If either the current {@code Observable} or the boundary {@code ObservableSource} issues an + * {@code onError} notification the event is passed on immediately without first emitting the buffer it is in the process of * assembling. *

*
Scheduler:
@@ -6051,12 +6223,14 @@ public final > Observable buffer(int count, i * @param * the boundary value type (ignored) * @param boundary - * the boundary ObservableSource + * the boundary {@code ObservableSource} * @param initialCapacity * the initial capacity of each buffer chunk - * @return an Observable that emits buffered items from the source ObservableSource when the boundary ObservableSource + * @return an {@code Observable} that emits buffered items from the current {@code Observable} when the boundary {@code ObservableSource} * emits an item * @see ReactiveX operators documentation: Buffer + * @throws NullPointerException if {@code boundary} is {@code null} + * @throws IllegalArgumentException if {@code initialCapacity} is non-positive * @see #buffer(ObservableSource) */ @CheckReturnValue @@ -6068,14 +6242,14 @@ public final > Observable buffer(int count, i } /** - * Returns an Observable that emits non-overlapping buffered items from the source ObservableSource each time the - * specified boundary ObservableSource emits an item. + * Returns an {@code Observable} that emits non-overlapping buffered items from the current {@code Observable} each time the + * specified boundary {@link ObservableSource} emits an item. *

* *

- * Completion of either the source or the boundary ObservableSource causes the returned ObservableSource to emit the - * latest buffer and complete. If either the source ObservableSource or the boundary ObservableSource issues an - * onError notification the event is passed on immediately without first emitting the buffer it is in the process of + * Completion of either the source or the boundary {@code ObservableSource} causes the returned {@code ObservableSource} to emit the + * latest buffer and complete. If either the current {@code Observable} or the boundary {@code ObservableSource} issues an + * {@code onError} notification the event is passed on immediately without first emitting the buffer it is in the process of * assembling. *

*
Scheduler:
@@ -6086,12 +6260,13 @@ public final > Observable buffer(int count, i * @param * the boundary value type (ignored) * @param boundary - * the boundary ObservableSource + * the boundary {@code ObservableSource} * @param bufferSupplier * a factory function that returns an instance of the collection subclass to be used and returned * as the buffer - * @return an Observable that emits buffered items from the source ObservableSource when the boundary ObservableSource + * @return an {@code Observable} that emits buffered items from the current {@code Observable} when the boundary {@code ObservableSource} * emits an item + * @throws NullPointerException if {@code boundary} or {@code bufferSupplier} is {@code null} * @see #buffer(ObservableSource, int) * @see ReactiveX operators documentation: Buffer */ @@ -6105,23 +6280,23 @@ public final > Observable buffer(int count, i } /** - * Returns an Observable that subscribes to this ObservableSource lazily, caches all of its events - * and replays them, in the same order as received, to all the downstream subscribers. + * Returns an {@code Observable} that subscribes to the current {@code Observable} lazily, caches all of its events + * and replays them, in the same order as received, to all the downstream observers. *

* *

- * This is useful when you want an ObservableSource to cache responses and you can't control the + * This is useful when you want an {@code Observable} to cache responses and you can't control the * subscribe/dispose behavior of all the {@link Observer}s. *

- * The operator subscribes only when the first downstream subscriber subscribes and maintains - * a single subscription towards this ObservableSource. In contrast, the operator family of {@link #replay()} + * The operator subscribes only when the first downstream observer subscribes and maintains + * a single subscription towards the current {@code Observable}. In contrast, the operator family of {@link #replay()} * that return a {@link ConnectableObservable} require an explicit call to {@link ConnectableObservable#connect()}. *

* Note: You sacrifice the ability to dispose the origin when you use the {@code cache} - * Observer so be careful not to use this Observer on ObservableSources that emit an infinite or very large number + * operator so be careful not to use this operator on {@code Observable}s that emit an infinite or very large number * of items that will use up memory. - * A possible workaround is to apply `takeUntil` with a predicate or - * another source before (and perhaps after) the application of cache(). + * A possible workaround is to apply {@code takeUntil} with a predicate or + * another source before (and perhaps after) the application of {@code cache()}. * 


      * AtomicBoolean shouldStop = new AtomicBoolean();
      *
@@ -6148,9 +6323,11 @@ public final > Observable buffer(int count, i
      *  
{@code cache} does not operate by default on a particular {@link Scheduler}.

      *
* - * @return an Observable that, when first subscribed to, caches all of its items and notifications for the + * @return an {@code Observable} that, when first subscribed to, caches all of its items and notifications for the * benefit of subsequent subscribers * @see ReactiveX operators documentation: Replay + * @see #takeUntil(Predicate) + * @see #takeUntil(ObservableSource) */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -6160,23 +6337,23 @@ public final Observable cache() { } /** - * Returns an Observable that subscribes to this ObservableSource lazily, caches all of its events - * and replays them, in the same order as received, to all the downstream subscribers. + * Returns an {@code Observable} that subscribes to the current {@code Observable} lazily, caches all of its events + * and replays them, in the same order as received, to all the downstream observers. *

* *

- * This is useful when you want an ObservableSource to cache responses and you can't control the + * This is useful when you want an {@code Observable} to cache responses and you can't control the * subscribe/dispose behavior of all the {@link Observer}s. *

- * The operator subscribes only when the first downstream subscriber subscribes and maintains - * a single subscription towards this ObservableSource. In contrast, the operator family of {@link #replay()} + * The operator subscribes only when the first downstream observer subscribes and maintains + * a single subscription towards the current {@code Observable}. In contrast, the operator family of {@link #replay()} * that return a {@link ConnectableObservable} require an explicit call to {@link ConnectableObservable#connect()}. *

* Note: You sacrifice the ability to dispose the origin when you use the {@code cache} - * Observer so be careful not to use this Observer on ObservableSources that emit an infinite or very large number + * operator so be careful not to use this operator on {@code Observable}s that emit an infinite or very large number * of items that will use up memory. * A possible workaround is to apply `takeUntil` with a predicate or - * another source before (and perhaps after) the application of cache(). + * another source before (and perhaps after) the application of {@code cache()}. * 


      * AtomicBoolean shouldStop = new AtomicBoolean();
      *
@@ -6207,9 +6384,12 @@ public final Observable cache() {
      * {@link #replay(int)} in combination with {@link ConnectableObservable#autoConnect()} or similar.
      *
      * @param initialCapacity hint for number of items to cache (for optimizing underlying data structure)
-     * @return an Observable that, when first subscribed to, caches all of its items and notifications for the
+     * @return an {@code Observable} that, when first subscribed to, caches all of its items and notifications for the
      *         benefit of subsequent subscribers
+     * @throws IllegalArgumentException if {@code initialCapacity} is non-positive
      * @see ReactiveX operators documentation: Replay
+     * @see #takeUntil(Predicate)
+     * @see #takeUntil(ObservableSource)
      */
     @CheckReturnValue
     @SchedulerSupport(SchedulerSupport.NONE)
@@ -6220,7 +6400,7 @@ public final Observable cacheWithInitialCapacity(int initialCapacity) {
     }
 
     /**
-     * Returns an Observable that emits the items emitted by the source ObservableSource, converted to the specified
+     * Returns an {@code Observable} that emits the items emitted by the current {@code Observable}, converted to the specified
      * type.
      * 

      * 
@@ -6231,10 +6411,11 @@ public final Observable cacheWithInitialCapacity(int initialCapacity) {
      *
      * @param  the output value type cast to
      * @param clazz
-     *            the target class type that {@code cast} will cast the items emitted by the source ObservableSource
-     *            into before emitting them from the resulting ObservableSource
-     * @return an Observable that emits each item from the source ObservableSource after converting it to the
+     *            the target class type that {@code cast} will cast the items emitted by the current {@code Observable}
+     *            into before emitting them from the resulting {@code Observable}
+     * @return an {@code Observable} that emits each item from the current {@code Observable} after converting it to the
      *         specified type
+     * @throws NullPointerException if {@code clazz} is {@code null}
      * @see ReactiveX operators documentation: Map
      */
     @CheckReturnValue
@@ -6246,8 +6427,8 @@ public final  Observable cast(@NonNull Class clazz) {
     }
 
     /**
-     * Collects items emitted by the finite source ObservableSource into a single mutable data structure and returns
-     * a Single that emits this structure.
+     * Collects items emitted by the finite source {@code Observable} into a single mutable data structure and returns
+     * a {@link Single} that emits this structure.
      * 

      * 
      * 

@@ -6255,7 +6436,7 @@ public final  Observable cast(@NonNull Class clazz) {
      * 

      * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to
      * be emitted. Sources that are infinite and never complete will never emit anything through this
-     * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}.
+     * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
      * 

      *  
Scheduler:

      *  
{@code collect} does not operate by default on a particular {@link Scheduler}.

@@ -6265,10 +6446,11 @@ public final  Observable cast(@NonNull Class clazz) {
      * @param initialValueSupplier
      *           the mutable data structure that will collect the items
      * @param collector
-     *           a function that accepts the {@code state} and an emitted item, and modifies {@code state}
+     *           a function that accepts the {@code state} and an emitted item, and modifies the accumulator accordingly
      *           accordingly
-     * @return a Single that emits the result of collecting the values emitted by the source ObservableSource
+     * @return a {@code Single} that emits the result of collecting the values emitted by the current {@code Observable}
      *         into a single mutable data structure
+     * @throws NullPointerException if {@code initialValueSupplier} or {@code collector} is {@code null}
      * @see ReactiveX operators documentation: Reduce
      */
     @CheckReturnValue
@@ -6281,8 +6463,8 @@ public final  Single collect(@NonNull Supplier initialValueSu
     }
 
     /**
-     * Collects items emitted by the finite source ObservableSource into a single mutable data structure and returns
-     * a Single that emits this structure.
+     * Collects items emitted by the finite source {@code Observable} into a single mutable data structure and returns
+     * a {@link Single} that emits this structure.
      * 

      * 
      * 

@@ -6290,7 +6472,7 @@ public final  Single collect(@NonNull Supplier initialValueSu
      * 

      * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to
      * be emitted. Sources that are infinite and never complete will never emit anything through this
-     * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}.
+     * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
      * 

      *  
Scheduler:

      *  
{@code collectInto} does not operate by default on a particular {@link Scheduler}.

@@ -6300,10 +6482,11 @@ public final  Single collect(@NonNull Supplier initialValueSu
      * @param initialValue
      *           the mutable data structure that will collect the items
      * @param collector
-     *           a function that accepts the {@code state} and an emitted item, and modifies {@code state}
+     *           a function that accepts the {@code state} and an emitted item, and modifies the accumulator accordingly
      *           accordingly
-     * @return a Single that emits the result of collecting the values emitted by the source ObservableSource
+     * @return a {@code Single} that emits the result of collecting the values emitted by the current {@code Observable}
      *         into a single mutable data structure
+     * @throws NullPointerException if {@code initialValue} or {@code collector} is {@code null}
      * @see ReactiveX operators documentation: Reduce
      */
     @CheckReturnValue
@@ -6315,22 +6498,23 @@ public final  Single collectInto(@NonNull U initialValue, @NonNull BiConsu
     }
 
     /**
-     * Transform an ObservableSource by applying a particular Transformer function to it.
+     * Transform the current {@code Observable} by applying a particular {@link ObservableTransformer} function to it.
      * 

-     * This method operates on the ObservableSource itself whereas {@link #lift} operates on the ObservableSource's
-     * Observers.
+     * This method operates on the {@code Observable} itself whereas {@link #lift} operates on the {@link ObservableSource}'s
+     * {@link Observer}s.
      * 

-     * If the operator you are creating is designed to act on the individual items emitted by a source
-     * ObservableSource, use {@link #lift}. If your operator is designed to transform the source ObservableSource as a whole
+     * If the operator you are creating is designed to act on the individual items emitted by the current
+     * {@code Observable}, use {@link #lift}. If your operator is designed to transform the current {@code Observable} as a whole
      * (for instance, by applying a particular set of existing RxJava operators to it) use {@code compose}.
      * 

      *  
Scheduler:

      *  
{@code compose} does not operate by default on a particular {@link Scheduler}.

      * 

      *
-     * @param  the value type of the output ObservableSource
-     * @param composer implements the function that transforms the source ObservableSource
-     * @return the source ObservableSource, transformed by the transformer function
+     * @param  the value type of the output {@code ObservableSource}
+     * @param composer implements the function that transforms the current {@code Observable}
+     * @return the current {@code Observable}, transformed by the transformer function
+     * @throws NullPointerException if {@code composer} is {@code null}
      * @see RxJava wiki: Implementing Your Own Operators
      */
     @SuppressWarnings("unchecked")
@@ -6342,9 +6526,9 @@ public final  Observable compose(@NonNull ObservableTransformer
      * 
      * 

@@ -6356,12 +6540,13 @@ public final  Observable compose(@NonNull ObservableTransformer{@code concatMap} does not operate by default on a particular {@link Scheduler}.
      * 

      *
-     * @param  the type of the inner ObservableSource sources and thus the output type
+     * @param  the type of the inner {@code ObservableSource} sources and thus the output type
      * @param mapper
-     *            a function that, when applied to an item emitted by the source ObservableSource, returns an
-     *            ObservableSource
-     * @return an Observable that emits the result of applying the transformation function to each item emitted
-     *         by the source ObservableSource and concatenating the ObservableSources obtained from this transformation
+     *            a function that, when applied to an item emitted by the current {@code Observable}, returns an
+     *            {@code ObservableSource}
+     * @return an {@code Observable} that emits the result of applying the transformation function to each item emitted
+     *         by the current {@code Observable} and concatenating the {@code ObservableSource}s obtained from this transformation
+     * @throws NullPointerException if {@code mapper} is {@code null}
      * @see ReactiveX operators documentation: FlatMap
      * @see #concatMap(Function, int, Scheduler)
      */
@@ -6373,9 +6558,9 @@ public final  Observable concatMap(@NonNull Function
      * 
      * 

@@ -6387,23 +6572,25 @@ public final  Observable concatMap(@NonNull Function{@code concatMap} does not operate by default on a particular {@link Scheduler}.
      * 

      *
-     * @param  the type of the inner ObservableSource sources and thus the output type
+     * @param  the type of the inner {@code ObservableSource} sources and thus the output type
      * @param mapper
-     *            a function that, when applied to an item emitted by the source ObservableSource, returns an
-     *            ObservableSource
-     * @param prefetch
-     *            the number of elements to prefetch from the current Observable
-     * @return an Observable that emits the result of applying the transformation function to each item emitted
-     *         by the source ObservableSource and concatenating the ObservableSources obtained from this transformation
+     *            a function that, when applied to an item emitted by the current {@code Observable}, returns an
+     *            {@code ObservableSource}
+     * @param bufferSize
+     *            the number of elements expected from the current {@code Observable} to be buffered
+     * @return an {@code Observable} that emits the result of applying the transformation function to each item emitted
+     *         by the current {@code Observable} and concatenating the {@code ObservableSource}s obtained from this transformation
+     * @throws NullPointerException if {@code mapper} is {@code null}
+     * @throws IllegalArgumentException if {@code bufferSize} is non-positive
      * @see ReactiveX operators documentation: FlatMap
      * @see #concatMap(Function, int, Scheduler)
      */
     @CheckReturnValue
     @SchedulerSupport(SchedulerSupport.NONE)
     @NonNull
-    public final  Observable concatMap(@NonNull Function> mapper, int prefetch) {
+    public final  Observable concatMap(@NonNull Function> mapper, int bufferSize) {
         Objects.requireNonNull(mapper, "mapper is null");
-        ObjectHelper.verifyPositive(prefetch, "prefetch");
+        ObjectHelper.verifyPositive(bufferSize, "bufferSize");
         if (this instanceof ScalarSupplier) {
             @SuppressWarnings("unchecked")
             T v = ((ScalarSupplier)this).get();
@@ -6412,13 +6599,13 @@ public final  Observable concatMap(@NonNull Function(this, mapper, prefetch, ErrorMode.IMMEDIATE));
+        return RxJavaPlugins.onAssembly(new ObservableConcatMap<>(this, mapper, bufferSize, ErrorMode.IMMEDIATE));
     }
 
     /**
-     * Returns a new Observable that emits items resulting from applying a function that you supply to each item
-     * emitted by the source ObservableSource, where that function returns an ObservableSource, and then emitting the items
-     * that result from concatenating those resulting ObservableSources.
+     * Returns a new {@code Observable} that emits items resulting from applying a function that you supply to each item
+     * emitted by the current {@code Observable}, where that function returns an {@link ObservableSource}, and then emitting the items
+     * that result from concatenating those returned {@code ObservableSource}s.
      * 

      * 
      * 

@@ -6429,33 +6616,35 @@ public final  Observable concatMap(@NonNull Function{@code concatMap} executes the given {@code mapper} function on the provided {@link Scheduler}.
      *
* - * @param the type of the inner ObservableSource sources and thus the output type + * @param the type of the inner {@code ObservableSource} sources and thus the output type * @param mapper - * a function that, when applied to an item emitted by the source ObservableSource, returns an - * ObservableSource - * @param prefetch - * the number of elements to prefetch from the current Observable + * a function that, when applied to an item emitted by the current {@code Observable}, returns an + * {@code ObservableSource} + * @param bufferSize + * the number of elements expected from the current {@code Observable} to be buffered * @param scheduler * the scheduler where the {@code mapper} function will be executed - * @return an Observable that emits the result of applying the transformation function to each item emitted - * by the source ObservableSource and concatenating the ObservableSources obtained from this transformation + * @return an {@code Observable} that emits the result of applying the transformation function to each item emitted + * by the current {@code Observable} and concatenating the {@code ObservableSource}s obtained from this transformation + * @throws NullPointerException if {@code mapper} or {@code scheduler} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @since 3.0.0 * @see ReactiveX operators documentation: FlatMap */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.CUSTOM) @NonNull - public final Observable concatMap(@NonNull Function> mapper, int prefetch, @NonNull Scheduler scheduler) { + public final Observable concatMap(@NonNull Function> mapper, int bufferSize, @NonNull Scheduler scheduler) { Objects.requireNonNull(mapper, "mapper is null"); - ObjectHelper.verifyPositive(prefetch, "prefetch"); + ObjectHelper.verifyPositive(bufferSize, "bufferSize"); Objects.requireNonNull(scheduler, "scheduler is null"); - return RxJavaPlugins.onAssembly(new ObservableConcatMapScheduler<>(this, mapper, prefetch, ErrorMode.IMMEDIATE, scheduler)); + return RxJavaPlugins.onAssembly(new ObservableConcatMapScheduler<>(this, mapper, bufferSize, ErrorMode.IMMEDIATE, scheduler)); } /** - * Maps each of the items into an ObservableSource, subscribes to them one after the other, + * Maps each of the items into an {@link ObservableSource}, subscribes to them one after the other, * one at a time and emits their values in order - * while delaying any error from either this or any of the inner ObservableSources + * while delaying any error from either this or any of the inner {@code ObservableSource}s * till all of them terminate. *

* @@ -6469,8 +6658,9 @@ public final Observable concatMap(@NonNull Function * * @param the result value type - * @param mapper the function that maps the items of this ObservableSource into the inner ObservableSources. - * @return the new ObservableSource instance with the concatenation behavior + * @param mapper the function that maps the items of the current {@code Observable} into the inner {@code ObservableSource}s. + * @return the new {@code Observable} instance with the concatenation behavior + * @throws NullPointerException if {@code mapper} is {@code null} * @see #concatMapDelayError(Function, boolean, int, Scheduler) */ @CheckReturnValue @@ -6481,9 +6671,9 @@ public final Observable concatMapDelayError(@NonNull Function * @@ -6497,22 +6687,24 @@ public final Observable concatMapDelayError(@NonNull Function * * @param the result value type - * @param mapper the function that maps the items of this ObservableSource into the inner ObservableSources. + * @param mapper the function that maps the items of the current {@code Observable} into the inner {@code ObservableSource}s. * @param tillTheEnd - * if true, all errors from the outer and inner ObservableSource sources are delayed until the end, - * if false, an error from the main source is signalled when the current ObservableSource source terminates - * @param prefetch - * the number of elements to prefetch from the current Observable - * @return the new ObservableSource instance with the concatenation behavior + * if {@code true}, all errors from the outer and inner {@code ObservableSource} sources are delayed until the end, + * if {@code false}, an error from the main source is signaled when the current {@code Observable} source terminates + * @param bufferSize + * the number of elements expected from the current {@code Observable} to be buffered + * @return the new {@code Observable} instance with the concatenation behavior + * @throws NullPointerException if {@code mapper} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see #concatMapDelayError(Function, boolean, int, Scheduler) */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @NonNull public final Observable concatMapDelayError(@NonNull Function> mapper, - boolean tillTheEnd, int prefetch) { + boolean tillTheEnd, int bufferSize) { Objects.requireNonNull(mapper, "mapper is null"); - ObjectHelper.verifyPositive(prefetch, "prefetch"); + ObjectHelper.verifyPositive(bufferSize, "bufferSize"); if (this instanceof ScalarSupplier) { @SuppressWarnings("unchecked") T v = ((ScalarSupplier)this).get(); @@ -6521,13 +6713,13 @@ public final Observable concatMapDelayError(@NonNull Function(this, mapper, prefetch, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY)); + return RxJavaPlugins.onAssembly(new ObservableConcatMap<>(this, mapper, bufferSize, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY)); } /** - * Maps each of the items into an ObservableSource, subscribes to them one after the other, + * Maps each of the items into an {@link ObservableSource}, subscribes to them one after the other, * one at a time and emits their values in order - * while delaying any error from either this or any of the inner ObservableSources + * while delaying any error from either this or any of the inner {@code ObservableSource}s * till all of them terminate. *

* @@ -6537,15 +6729,17 @@ public final Observable concatMapDelayError(@NonNull Function * * @param the result value type - * @param mapper the function that maps the items of this ObservableSource into the inner ObservableSources. + * @param mapper the function that maps the items of the current {@code Observable} into the inner {@code ObservableSource}s. * @param tillTheEnd - * if true, all errors from the outer and inner ObservableSource sources are delayed until the end, - * if false, an error from the main source is signalled when the current ObservableSource source terminates - * @param prefetch - * the number of elements to prefetch from the current Observable + * if {@code true}, all errors from the outer and inner {@code ObservableSource} sources are delayed until the end, + * if {@code false}, an error from the main source is signaled when the current {@code Observable} source terminates + * @param bufferSize + * the number of elements expected from the current {@code Observable} to be buffered * @param scheduler * the scheduler where the {@code mapper} function will be executed - * @return the new ObservableSource instance with the concatenation behavior + * @return the new {@code Observable} instance with the concatenation behavior + * @throws NullPointerException if {@code mapper} or {@code scheduler} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see #concatMapDelayError(Function, boolean, int) * @since 3.0.0 */ @@ -6553,19 +6747,19 @@ public final Observable concatMapDelayError(@NonNull Function Observable concatMapDelayError(@NonNull Function> mapper, - boolean tillTheEnd, int prefetch, @NonNull Scheduler scheduler) { + boolean tillTheEnd, int bufferSize, @NonNull Scheduler scheduler) { Objects.requireNonNull(mapper, "mapper is null"); - ObjectHelper.verifyPositive(prefetch, "prefetch"); + ObjectHelper.verifyPositive(bufferSize, "bufferSize"); Objects.requireNonNull(scheduler, "scheduler is null"); - return RxJavaPlugins.onAssembly(new ObservableConcatMapScheduler<>(this, mapper, prefetch, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, scheduler)); + return RxJavaPlugins.onAssembly(new ObservableConcatMapScheduler<>(this, mapper, bufferSize, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, scheduler)); } /** - * Maps a sequence of values into ObservableSources and concatenates these ObservableSources eagerly into a single - * ObservableSource. + * Maps a sequence of values into {@link ObservableSource}s and concatenates these {@code ObservableSource}s eagerly into a single + * {@code Observable} sequence. *

* Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the - * source ObservableSources. The operator buffers the values emitted by these ObservableSources and then drains them in + * current {@code Observable}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them in * order, each one after the previous one completes. *

* @@ -6574,9 +6768,10 @@ public final Observable concatMapDelayError(@NonNull FunctionThis method does not operate by default on a particular {@link Scheduler}. *

* @param the value type - * @param mapper the function that maps a sequence of values into a sequence of ObservableSources that will be + * @param mapper the function that maps a sequence of values into a sequence of {@code ObservableSource}s that will be * eagerly concatenated - * @return the new ObservableSource instance with the specified concatenation behavior + * @return the new {@code Observable} instance with the specified concatenation behavior + * @throws NullPointerException if {@code mapper} is {@code null} * @since 2.0 */ @CheckReturnValue @@ -6587,11 +6782,11 @@ public final Observable concatMapEager(@NonNull Function * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the - * source ObservableSources. The operator buffers the values emitted by these ObservableSources and then drains them in + * current {@code Observable}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them in * order, each one after the previous one completes. *

* @@ -6600,30 +6795,32 @@ public final Observable concatMapEager(@NonNull FunctionThis method does not operate by default on a particular {@link Scheduler}. *

* @param the value type - * @param mapper the function that maps a sequence of values into a sequence of ObservableSources that will be + * @param mapper the function that maps a sequence of values into a sequence of {@code ObservableSource}s that will be * eagerly concatenated - * @param maxConcurrency the maximum number of concurrent subscribed ObservableSources - * @param prefetch hints about the number of expected values from each inner ObservableSource, must be positive - * @return the new ObservableSource instance with the specified concatenation behavior + * @param maxConcurrency the maximum number of concurrent subscribed {@code ObservableSource}s + * @param bufferSize hints about the number of expected items from each inner {@code ObservableSource}, must be positive + * @return the new {@code Observable} instance with the specified concatenation behavior + * @throws NullPointerException if {@code mapper} is {@code null} + * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive * @since 2.0 */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @NonNull public final Observable concatMapEager(@NonNull Function> mapper, - int maxConcurrency, int prefetch) { + int maxConcurrency, int bufferSize) { Objects.requireNonNull(mapper, "mapper is null"); ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency"); - ObjectHelper.verifyPositive(prefetch, "prefetch"); - return RxJavaPlugins.onAssembly(new ObservableConcatMapEager<>(this, mapper, ErrorMode.IMMEDIATE, maxConcurrency, prefetch)); + ObjectHelper.verifyPositive(bufferSize, "bufferSize"); + return RxJavaPlugins.onAssembly(new ObservableConcatMapEager<>(this, mapper, ErrorMode.IMMEDIATE, maxConcurrency, bufferSize)); } /** - * Maps a sequence of values into ObservableSources and concatenates these ObservableSources eagerly into a single - * ObservableSource. + * Maps a sequence of values into {@link ObservableSource}s and concatenates these {@code ObservableSource}s eagerly into a single + * {@code Observable} sequence. *

* Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the - * source ObservableSources. The operator buffers the values emitted by these ObservableSources and then drains them in + * current {@code Observable}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them in * order, each one after the previous one completes. *

* @@ -6632,12 +6829,13 @@ public final Observable concatMapEager(@NonNull FunctionThis method does not operate by default on a particular {@link Scheduler}. *

* @param the value type - * @param mapper the function that maps a sequence of values into a sequence of ObservableSources that will be + * @param mapper the function that maps a sequence of values into a sequence of {@code ObservableSource}s that will be * eagerly concatenated * @param tillTheEnd - * if true, all errors from the outer and inner ObservableSource sources are delayed until the end, - * if false, an error from the main source is signalled when the current ObservableSource source terminates - * @return the new ObservableSource instance with the specified concatenation behavior + * if {@code true}, all errors from the outer and inner {@code ObservableSource} sources are delayed until the end, + * if {@code false}, an error from the main source is signaled when the current {@code Observable} source terminates + * @return the new {@code Observable} instance with the specified concatenation behavior + * @throws NullPointerException if {@code mapper} is {@code null} * @since 2.0 */ @CheckReturnValue @@ -6649,11 +6847,11 @@ public final Observable concatMapEagerDelayError(@NonNull Function * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the - * source ObservableSources. The operator buffers the values emitted by these ObservableSources and then drains them in + * current {@code Observable}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them in * order, each one after the previous one completes. *

* @@ -6662,32 +6860,34 @@ public final Observable concatMapEagerDelayError(@NonNull FunctionThis method does not operate by default on a particular {@link Scheduler}. *

* @param the value type - * @param mapper the function that maps a sequence of values into a sequence of ObservableSources that will be + * @param mapper the function that maps a sequence of values into a sequence of {@code ObservableSource}s that will be * eagerly concatenated * @param tillTheEnd - * if true, exceptions from the current Observable and all the inner ObservableSources are delayed until - * all of them terminate, if false, exception from the current Observable is delayed until the - * currently running ObservableSource terminates - * @param maxConcurrency the maximum number of concurrent subscribed ObservableSources - * @param prefetch - * the number of elements to prefetch from each source ObservableSource - * @return the new ObservableSource instance with the specified concatenation behavior + * if {@code true}, exceptions from the current {@code Observable} and all the inner {@code ObservableSource}s are delayed until + * all of them terminate, if {@code false}, exception from the current {@code Observable} is delayed until the + * currently running {@code ObservableSource} terminates + * @param maxConcurrency the maximum number of concurrent subscribed {@code ObservableSource}s + * @param bufferSize + * the number of elements expected from the current {@code Observable} and each inner {@code ObservableSource} to be buffered + * @return the new {@code Observable} instance with the specified concatenation behavior + * @throws NullPointerException if {@code mapper} is {@code null} + * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive * @since 2.0 */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @NonNull public final Observable concatMapEagerDelayError(@NonNull Function> mapper, - boolean tillTheEnd, int maxConcurrency, int prefetch) { + boolean tillTheEnd, int maxConcurrency, int bufferSize) { Objects.requireNonNull(mapper, "mapper is null"); ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency"); - ObjectHelper.verifyPositive(prefetch, "prefetch"); - return RxJavaPlugins.onAssembly(new ObservableConcatMapEager<>(this, mapper, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, maxConcurrency, prefetch)); + ObjectHelper.verifyPositive(bufferSize, "bufferSize"); + return RxJavaPlugins.onAssembly(new ObservableConcatMapEager<>(this, mapper, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, maxConcurrency, bufferSize)); } /** - * Maps each element of the upstream Observable into CompletableSources, subscribes to them one at a time in - * order and waits until the upstream and all CompletableSources complete. + * Maps each element of the current {@code Observable} into {@link CompletableSource}s, subscribes to them one at a time in + * order and waits until the upstream and all {@code CompletableSource}s complete. *

* *

@@ -6696,8 +6896,9 @@ public final Observable concatMapEagerDelayError(@NonNull Function *

History: 2.1.6 - experimental * @param mapper - * a function that, when applied to an item emitted by the source ObservableSource, returns a CompletableSource - * @return a Completable that signals {@code onComplete} when the upstream and all CompletableSources complete + * a function that, when applied to an item emitted by the current {@code Observable}, returns a {@code CompletableSource} + * @return a {@link Completable} that signals {@code onComplete} when the upstream and all {@code CompletableSource}s complete + * @throws NullPointerException if {@code mapper} is {@code null} * @since 2.2 */ @CheckReturnValue @@ -6708,8 +6909,8 @@ public final Completable concatMapCompletable(@NonNull Function * *

@@ -6718,12 +6919,14 @@ public final Completable concatMapCompletable(@NonNull Function *

History: 2.1.6 - experimental * @param mapper - * a function that, when applied to an item emitted by the source ObservableSource, returns a CompletableSource + * a function that, when applied to an item emitted by the current {@code Observable}, returns a {@code CompletableSource} * * @param capacityHint - * the number of upstream items expected to be buffered until the current CompletableSource, mapped from + * the number of upstream items expected to be buffered until the current {@code CompletableSource}, mapped from * the current item, completes. - * @return a Completable that signals {@code onComplete} when the upstream and all CompletableSources complete + * @return a {@link Completable} that signals {@code onComplete} when the upstream and all {@code CompletableSources} complete + * @throws NullPointerException if {@code mapper} is {@code null} + * @throws IllegalArgumentException if {@code capacityHint} is non-positive * @since 2.2 */ @CheckReturnValue @@ -6737,7 +6940,7 @@ public final Completable concatMapCompletable(@NonNull Function * @@ -6749,7 +6952,8 @@ public final Completable concatMapCompletable(@NonNull Function * @@ -6774,13 +6978,14 @@ public final Completable concatMapCompletableDelayError(@NonNull Function * @@ -6805,32 +7010,32 @@ public final Completable concatMapCompletableDelayError(@NonNull Function mapper, boolean tillTheEnd, int prefetch) { + public final Completable concatMapCompletableDelayError(@NonNull Function mapper, boolean tillTheEnd, int bufferSize) { Objects.requireNonNull(mapper, "mapper is null"); - ObjectHelper.verifyPositive(prefetch, "prefetch"); - return RxJavaPlugins.onAssembly(new ObservableConcatMapCompletable<>(this, mapper, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, prefetch)); + ObjectHelper.verifyPositive(bufferSize, "bufferSize"); + return RxJavaPlugins.onAssembly(new ObservableConcatMapCompletable<>(this, mapper, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, bufferSize)); } /** - * Returns an Observable that concatenate each item emitted by the source ObservableSource with the values in an - * Iterable corresponding to that item that is generated by a selector. + * Returns an {@code Observable} that concatenate each item emitted by the current {@code Observable} with the values in an + * {@link Iterable} corresponding to that item that is generated by a selector. *

* * @@ -6840,12 +7045,13 @@ public final Completable concatMapCompletableDelayError(@NonNull Function * * @param - * the type of item emitted by the resulting ObservableSource + * the type of item emitted by the resulting {@code Observable} * @param mapper - * a function that returns an Iterable sequence of values for when given an item emitted by the - * source ObservableSource - * @return an Observable that emits the results of concatenating the items emitted by the source ObservableSource with - * the values in the Iterables corresponding to those items, as generated by {@code collectionSelector} + * a function that returns an {@code Iterable} sequence of values for when given an item emitted by the + * current {@code Observable} + * @return an {@code Observable} that emits the results of concatenating the items emitted by the current {@code Observable} with + * the values in the {@code Iterable}s corresponding to those items + * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: FlatMap */ @CheckReturnValue @@ -6857,8 +7063,8 @@ public final Observable concatMapIterable(@NonNull Function * * @@ -6868,29 +7074,31 @@ public final Observable concatMapIterable(@NonNull Function * * @param - * the type of item emitted by the resulting ObservableSource + * the type of item emitted by the resulting {@code Observable} * @param mapper - * a function that returns an Iterable sequence of values for when given an item emitted by the - * source ObservableSource - * @param prefetch - * the number of elements to prefetch from the current Observable - * @return an Observable that emits the results of concatenating the items emitted by the source ObservableSource with - * the values in the Iterables corresponding to those items, as generated by {@code collectionSelector} + * a function that returns an {@code Iterable} sequence of values for when given an item emitted by the + * current {@code Observable} + * @param bufferSize + * the number of elements expected from the current {@code Observable} to be buffered + * @return an {@code Observable} that emits the results of concatenating the items emitted by the current {@code Observable} with + * the values in the {@code Iterable}s corresponding to those items + * @throws NullPointerException if {@code mapper} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: FlatMap */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @NonNull - public final Observable concatMapIterable(@NonNull Function> mapper, int prefetch) { + public final Observable concatMapIterable(@NonNull Function> mapper, int bufferSize) { Objects.requireNonNull(mapper, "mapper is null"); - ObjectHelper.verifyPositive(prefetch, "prefetch"); - return concatMap(ObservableInternalHelper.flatMapIntoIterable(mapper), prefetch); + ObjectHelper.verifyPositive(bufferSize, "bufferSize"); + return concatMap(ObservableInternalHelper.flatMapIntoIterable(mapper), bufferSize); } /** * Maps the upstream items into {@link MaybeSource}s and subscribes to them one after the * other succeeds or completes, emits their success value if available or terminates immediately if - * either this {@code Observable} or the current inner {@code MaybeSource} fail. + * either the current {@code Observable} or the current inner {@code MaybeSource} fail. *

* *

@@ -6902,7 +7110,8 @@ public final Observable concatMapIterable(@NonNull Function Observable concatMapMaybe(@NonNull Function * *
@@ -6929,11 +7138,11 @@ public final Observable concatMapMaybe(@NonNull Function Observable concatMapMaybe(@NonNull Function Observable concatMapMaybe(@NonNull Function> mapper, int prefetch) { + public final Observable concatMapMaybe(@NonNull Function> mapper, int bufferSize) { Objects.requireNonNull(mapper, "mapper is null"); - ObjectHelper.verifyPositive(prefetch, "prefetch"); - return RxJavaPlugins.onAssembly(new ObservableConcatMapMaybe<>(this, mapper, ErrorMode.IMMEDIATE, prefetch)); + ObjectHelper.verifyPositive(bufferSize, "bufferSize"); + return RxJavaPlugins.onAssembly(new ObservableConcatMapMaybe<>(this, mapper, ErrorMode.IMMEDIATE, bufferSize)); } /** * Maps the upstream items into {@link MaybeSource}s and subscribes to them one after the * other terminates, emits their success value if available and delaying all errors - * till both this {@code Observable} and all inner {@code MaybeSource}s terminate. + * till both the current {@code Observable} and all inner {@code MaybeSource}s terminate. *

* *

@@ -6962,7 +7171,8 @@ public final Observable concatMapMaybe(@NonNull Function Observable concatMapMaybeDelayError(@NonNull Function * *
@@ -6989,13 +7199,14 @@ public final Observable concatMapMaybeDelayError(@NonNull Function Observable concatMapMaybeDelayError(@NonNull Function * *
@@ -7022,33 +7233,33 @@ public final Observable concatMapMaybeDelayError(@NonNull Function Observable concatMapMaybeDelayError(@NonNull Function> mapper, boolean tillTheEnd, int prefetch) { + public final Observable concatMapMaybeDelayError(@NonNull Function> mapper, boolean tillTheEnd, int bufferSize) { Objects.requireNonNull(mapper, "mapper is null"); - ObjectHelper.verifyPositive(prefetch, "prefetch"); - return RxJavaPlugins.onAssembly(new ObservableConcatMapMaybe<>(this, mapper, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, prefetch)); + ObjectHelper.verifyPositive(bufferSize, "bufferSize"); + return RxJavaPlugins.onAssembly(new ObservableConcatMapMaybe<>(this, mapper, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, bufferSize)); } /** * Maps the upstream items into {@link SingleSource}s and subscribes to them one after the * other succeeds, emits their success values or terminates immediately if - * either this {@code Observable} or the current inner {@code SingleSource} fail. + * either the current {@code Observable} or the current inner {@code SingleSource} fail. *

* *

@@ -7060,7 +7271,8 @@ public final Observable concatMapMaybeDelayError(@NonNull Function Observable concatMapSingle(@NonNull Function * *
@@ -7087,11 +7299,11 @@ public final Observable concatMapSingle(@NonNull Function Observable concatMapSingle(@NonNull Function Observable concatMapSingle(@NonNull Function> mapper, int prefetch) { + public final Observable concatMapSingle(@NonNull Function> mapper, int bufferSize) { Objects.requireNonNull(mapper, "mapper is null"); - ObjectHelper.verifyPositive(prefetch, "prefetch"); - return RxJavaPlugins.onAssembly(new ObservableConcatMapSingle<>(this, mapper, ErrorMode.IMMEDIATE, prefetch)); + ObjectHelper.verifyPositive(bufferSize, "bufferSize"); + return RxJavaPlugins.onAssembly(new ObservableConcatMapSingle<>(this, mapper, ErrorMode.IMMEDIATE, bufferSize)); } /** * Maps the upstream items into {@link SingleSource}s and subscribes to them one after the * other succeeds or fails, emits their success values and delays all errors - * till both this {@code Observable} and all inner {@code SingleSource}s terminate. + * till both the current {@code Observable} and all inner {@code SingleSource}s terminate. *

* *

@@ -7120,7 +7332,8 @@ public final Observable concatMapSingle(@NonNull Function Observable concatMapSingleDelayError(@NonNull Function * *
@@ -7147,13 +7360,14 @@ public final Observable concatMapSingleDelayError(@NonNull Function Observable concatMapSingleDelayError(@NonNull Function * *
@@ -7180,32 +7394,32 @@ public final Observable concatMapSingleDelayError(@NonNull Function Observable concatMapSingleDelayError(@NonNull Function> mapper, boolean tillTheEnd, int prefetch) { + public final Observable concatMapSingleDelayError(@NonNull Function> mapper, boolean tillTheEnd, int bufferSize) { Objects.requireNonNull(mapper, "mapper is null"); - ObjectHelper.verifyPositive(prefetch, "prefetch"); - return RxJavaPlugins.onAssembly(new ObservableConcatMapSingle<>(this, mapper, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, prefetch)); + ObjectHelper.verifyPositive(bufferSize, "bufferSize"); + return RxJavaPlugins.onAssembly(new ObservableConcatMapSingle<>(this, mapper, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, bufferSize)); } /** - * Returns an Observable that emits the items emitted from the current ObservableSource, then the next, one after - * the other, without interleaving them. + * Returns an {@code Observable} that first emits the items emitted from the current {@code Observable}, then items + * from the {@code other} {@link ObservableSource} without interleaving them. *

* *

@@ -7214,9 +7428,10 @@ public final Observable concatMapSingleDelayError(@NonNull Function * * @param other - * an ObservableSource to be concatenated after the current - * @return an Observable that emits items emitted by the two source ObservableSources, one after the other, + * an {@code ObservableSource} to be concatenated after the current + * @return an {@code Observable} that emits items emitted by the two source {@code ObservableSource}s, one after the other, * without interleaving them + * @throws NullPointerException if {@code other} is {@code null} * @see ReactiveX operators documentation: Concat */ @CheckReturnValue @@ -7228,8 +7443,8 @@ public final Observable concatWith(@NonNull ObservableSource oth } /** - * Returns an {@code Observable} that emits the items from this {@code Observable} followed by the success item or error event - * of the other {@link SingleSource}. + * Returns an {@code Observable} that emits the items from the current {@code Observable} followed by the success item or error event + * of the {@code other} {@link SingleSource}. *

* *

@@ -7237,8 +7452,9 @@ public final Observable concatWith(@NonNull ObservableSource oth *
{@code concatWith} does not operate by default on a particular {@link Scheduler}.
*
*

History: 2.1.10 - experimental - * @param other the SingleSource whose signal should be emitted after this {@code Observable} completes normally. - * @return the new Observable instance + * @param other the {@code SingleSource} whose signal should be emitted after the current {@code Observable} completes normally. + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code other} is {@code null} * @since 2.2 */ @CheckReturnValue @@ -7250,7 +7466,7 @@ public final Observable concatWith(@NonNull SingleSource other) } /** - * Returns an {@code Observable} that emits the items from this {@code Observable} followed by the success item or terminal events + * Returns an {@code Observable} that emits the items from the current {@code Observable} followed by the success item or terminal events * of the other {@link MaybeSource}. *

* @@ -7259,8 +7475,9 @@ public final Observable concatWith(@NonNull SingleSource other) *

{@code concatWith} does not operate by default on a particular {@link Scheduler}.
*
*

History: 2.1.10 - experimental - * @param other the MaybeSource whose signal should be emitted after this Observable completes normally. - * @return the new Observable instance + * @param other the {@code MaybeSource} whose signal should be emitted after the current {@code Observable} completes normally. + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code other} is {@code null} * @since 2.2 */ @CheckReturnValue @@ -7272,7 +7489,7 @@ public final Observable concatWith(@NonNull MaybeSource other) { } /** - * Returns an {@code Observable} that emits items from this {@code Observable} and when it completes normally, the + * Returns an {@code Observable} that emits items from the current {@code Observable} and when it completes normally, the * other {@link CompletableSource} is subscribed to and the returned {@code Observable} emits its terminal events. *

* @@ -7282,7 +7499,8 @@ public final Observable concatWith(@NonNull MaybeSource other) { *

*

History: 2.1.10 - experimental * @param other the {@code CompletableSource} to subscribe to once the current {@code Observable} completes normally - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code other} is {@code null} * @since 2.2 */ @CheckReturnValue @@ -7294,7 +7512,7 @@ public final Observable concatWith(@NonNull CompletableSource other) { } /** - * Returns a Single that emits a Boolean that indicates whether the source ObservableSource emitted a + * Returns a {@link Single} that emits a {@link Boolean} that indicates whether the current {@code Observable} emitted a * specified item. *

* @@ -7304,9 +7522,10 @@ public final Observable concatWith(@NonNull CompletableSource other) { *

* * @param element - * the item to search for in the emissions from the source ObservableSource - * @return a Single that emits {@code true} if the specified item is emitted by the source ObservableSource, - * or {@code false} if the source ObservableSource completes without emitting that item + * the item to search for in the emissions from the current {@code Observable} + * @return a {@code Single} that emits {@code true} if the specified item is emitted by the current {@code Observable}, + * or {@code false} if the current {@code Observable} completes without emitting that item + * @throws NullPointerException if {@code element} is {@code null} * @see ReactiveX operators documentation: Contains */ @CheckReturnValue @@ -7318,8 +7537,8 @@ public final Single contains(@NonNull Object element) { } /** - * Returns a Single that counts the total number of items emitted by the source ObservableSource and emits - * this count as a 64-bit Long. + * Returns a {@link Single} that counts the total number of items emitted by the current {@code Observable} and emits + * this count as a 64-bit {@link Long}. *

* *

@@ -7327,8 +7546,8 @@ public final Single contains(@NonNull Object element) { *
{@code count} does not operate by default on a particular {@link Scheduler}.
*
* - * @return a Single that emits a single item: the number of items emitted by the source ObservableSource as a - * 64-bit Long item + * @return a {@code Single} that emits a single item: the number of items emitted by the current {@code Observable} as a + * 64-bit {@code Long} item * @see ReactiveX operators documentation: Count */ @CheckReturnValue @@ -7339,8 +7558,9 @@ public final Single count() { } /** - * Returns an Observable that mirrors the source ObservableSource, except that it drops items emitted by the - * source ObservableSource that are followed by another item within a computed debounce duration. + * Returns an {@code Observable} that mirrors the current {@code Observable}, except that it drops items emitted by the + * current {@code Observable} that are followed by another item within a computed debounce duration + * denoted by an item emission or completion from a generated inner {@link ObservableSource} for that original item. *

* *

@@ -7359,9 +7579,10 @@ public final Single count() { * @param * the debounce value type (ignored) * @param debounceSelector - * function to retrieve a sequence that indicates the throttle duration for each item - * @return an Observable that omits items emitted by the source ObservableSource that are followed by another item + * function to return a sequence that indicates the throttle duration for each item via its own emission or completion + * @return an {@code Observable} that omits items emitted by the current {@code Observable} that are followed by another item * within a computed debounce duration + * @throws NullPointerException if {@code debounceSelector} is {@code null} * @see ReactiveX operators documentation: Debounce */ @CheckReturnValue @@ -7373,16 +7594,16 @@ public final Observable debounce(@NonNull Function - * Note: If items keep being emitted by the source ObservableSource faster than the timeout then no items - * will be emitted by the resulting ObservableSource. + * Note: If items keep being emitted by the current {@code Observable} faster than the timeout then no items + * will be emitted by the resulting {@code Observable}. *

* *

- * Delivery of the item after the grace period happens on the {@code computation} {@code Scheduler}'s + * Delivery of the item after the grace period happens on the {@code computation} {@link Scheduler}'s * {@code Worker} which if takes too long, a newer item may arrive from the upstream, causing the * {@code Worker}'s task to get disposed, which may also interrupt any downstream blocking operation * (yielding an {@code InterruptedException}). It is recommended processing items @@ -7390,17 +7611,18 @@ public final Observable debounce(@NonNull Function *

Scheduler:
- *
{@code debounce} operates by default on the {@code computation} {@link Scheduler}.
+ *
{@code debounce} operates by default on the {@code computation} {@code Scheduler}.
*
* * @param timeout - * the length of the window of time that must pass after the emission of an item from the source - * ObservableSource in which that ObservableSource emits no items in order for the item to be emitted by the - * resulting ObservableSource + * the length of the window of time that must pass after the emission of an item from the current + * {@code Observable} in which the {@code Observable} emits no items in order for the item to be emitted by the + * resulting {@code Observable} * @param unit * the unit of time for the specified {@code timeout} - * @return an Observable that filters out items from the source ObservableSource that are too quickly followed by + * @return an {@code Observable} that filters out items from the current {@code Observable} that are too quickly followed by * newer items + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: Debounce * @see #throttleWithTimeout(long, TimeUnit) */ @@ -7412,12 +7634,12 @@ public final Observable debounce(long timeout, @NonNull TimeUnit unit) { } /** - * Returns an Observable that mirrors the source ObservableSource, except that it drops items emitted by the - * source ObservableSource that are followed by newer items before a timeout value expires on a specified - * Scheduler. The timer resets on each emission. + * Returns an {@code Observable} that mirrors the current {@code Observable}, except that it drops items emitted by the + * current {@code Observable} that are followed by newer items before a timeout value expires on a specified + * {@link Scheduler}. The timer resets on each emission. *

- * Note: If items keep being emitted by the source ObservableSource faster than the timeout then no items - * will be emitted by the resulting ObservableSource. + * Note: If items keep being emitted by the current {@code Observable} faster than the timeout then no items + * will be emitted by the resulting {@code Observable}. *

* *

@@ -7429,19 +7651,20 @@ public final Observable debounce(long timeout, @NonNull TimeUnit unit) { * {@code debounce} itself. *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param timeout - * the time each item has to be "the most recent" of those emitted by the source ObservableSource to + * the time each item has to be "the most recent" of those emitted by the current {@code Observable} to * ensure that it's not dropped * @param unit * the unit of time for the specified {@code timeout} * @param scheduler - * the {@link Scheduler} to use internally to manage the timers that handle the timeout for each + * the {@code Scheduler} to use internally to manage the timers that handle the timeout for each * item - * @return an Observable that filters out items from the source ObservableSource that are too quickly followed by + * @return an {@code Observable} that filters out items from the current {@code Observable} that are too quickly followed by * newer items + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Debounce * @see #throttleWithTimeout(long, TimeUnit, Scheduler) */ @@ -7455,8 +7678,8 @@ public final Observable debounce(long timeout, @NonNull TimeUnit unit, @NonNu } /** - * Returns an Observable that emits the items emitted by the source ObservableSource or a specified default item - * if the source ObservableSource is empty. + * Returns an {@code Observable} that emits the items emitted by the current {@code Observable} or a specified default item + * if the current {@code Observable} is empty. *

* *

@@ -7465,9 +7688,10 @@ public final Observable debounce(long timeout, @NonNull TimeUnit unit, @NonNu *
* * @param defaultItem - * the item to emit if the source ObservableSource emits no items - * @return an Observable that emits either the specified default item if the source ObservableSource emits no - * items, or the items emitted by the source ObservableSource + * the item to emit if the current {@code Observable} emits no items + * @return an {@code Observable} that emits either the specified default item if the current {@code Observable} emits no + * items, or the items emitted by the current {@code Observable} + * @throws NullPointerException if {@code defaultItem} is {@code null} * @see ReactiveX operators documentation: DefaultIfEmpty */ @CheckReturnValue @@ -7479,13 +7703,13 @@ public final Observable defaultIfEmpty(@NonNull T defaultItem) { } /** - * Returns an Observable that delays the emissions of the source ObservableSource via another ObservableSource on a - * per-item basis. + * Returns an {@code Observable} that delays the emissions of the current {@code Observable} via + * a per-item derived {@link ObservableSource}'s item emission or termination, on a per source item basis. *

* *

- * Note: the resulting ObservableSource will immediately propagate any {@code onError} notification - * from the source ObservableSource. + * Note: the resulting {@code Observable} will immediately propagate any {@code onError} notification + * from the current {@code Observable}. *

*
Scheduler:
*
This version of {@code delay} does not operate by default on a particular {@link Scheduler}.
@@ -7494,11 +7718,12 @@ public final Observable defaultIfEmpty(@NonNull T defaultItem) { * @param * the item delay value type (ignored) * @param itemDelay - * a function that returns an ObservableSource for each item emitted by the source ObservableSource, which is - * then used to delay the emission of that item by the resulting ObservableSource until the ObservableSource + * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable}, which is + * then used to delay the emission of that item by the resulting {@code Observable} until the {@code ObservableSource} * returned from {@code itemDelay} emits an item - * @return an Observable that delays the emissions of the source ObservableSource via another ObservableSource on a + * @return an {@code Observable} that delays the emissions of the current {@code Observable} via another {@code ObservableSource} on a * per-item basis + * @throws NullPointerException if {@code itemDelay} is {@code null} * @see ReactiveX operators documentation: Delay */ @CheckReturnValue @@ -7510,8 +7735,8 @@ public final Observable delay(@NonNull Function * *
@@ -7523,8 +7748,11 @@ public final Observable delay(@NonNull FunctionReactiveX operators documentation: Delay + * @see #delay(long, TimeUnit, boolean) + * @see #delay(long, TimeUnit, Scheduler) */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.COMPUTATION) @@ -7534,8 +7762,8 @@ public final Observable delay(long delay, @NonNull TimeUnit unit) { } /** - * Returns an Observable that emits the items emitted by the source ObservableSource shifted forward in time by a - * specified delay. If {@code delayError} is true, error notifications will also be delayed. + * Returns an {@code Observable} that emits the items emitted by the current {@code Observable} shifted forward in time by a + * specified delay. If {@code delayError} is {@code true}, error notifications will also be delayed. *

* *

@@ -7548,10 +7776,12 @@ public final Observable delay(long delay, @NonNull TimeUnit unit) { * @param unit * the {@link TimeUnit} in which {@code period} is defined * @param delayError - * if true, the upstream exception is signalled with the given delay, after all preceding normal elements, - * if false, the upstream exception is signalled immediately - * @return the source ObservableSource shifted in time by the specified delay + * if {@code true}, the upstream exception is signaled with the given delay, after all preceding normal elements, + * if {@code false}, the upstream exception is signaled immediately + * @return the current {@code Observable} shifted in time by the specified delay + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: Delay + * @see #delay(long, TimeUnit, Scheduler, boolean) */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.COMPUTATION) @@ -7561,8 +7791,8 @@ public final Observable delay(long delay, @NonNull TimeUnit unit, boolean del } /** - * Returns an Observable that emits the items emitted by the source ObservableSource shifted forward in time by a - * specified delay. Error notifications from the source ObservableSource are not delayed. + * Returns an {@code Observable} that emits the items emitted by the current {@code Observable} shifted forward in time by a + * specified delay. An error notification from the current {@code Observable} is not delayed. *

* *

@@ -7575,8 +7805,9 @@ public final Observable delay(long delay, @NonNull TimeUnit unit, boolean del * @param unit * the time unit of {@code delay} * @param scheduler - * the {@link Scheduler} to use for delaying - * @return the source ObservableSource shifted in time by the specified delay + * the {@code Scheduler} to use for delaying + * @return the current {@code Observable} shifted in time by the specified delay + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Delay */ @CheckReturnValue @@ -7587,8 +7818,8 @@ public final Observable delay(long delay, @NonNull TimeUnit unit, @NonNull Sc } /** - * Returns an Observable that emits the items emitted by the source ObservableSource shifted forward in time by a - * specified delay. If {@code delayError} is true, error notifications will also be delayed. + * Returns an {@code Observable} that emits the items emitted by the current {@code Observable} shifted forward in time by a + * specified delay. If {@code delayError} is {@code true}, error notifications will also be delayed. *

* *

@@ -7601,11 +7832,12 @@ public final Observable delay(long delay, @NonNull TimeUnit unit, @NonNull Sc * @param unit * the time unit of {@code delay} * @param scheduler - * the {@link Scheduler} to use for delaying + * the {@code Scheduler} to use for delaying * @param delayError - * if true, the upstream exception is signalled with the given delay, after all preceding normal elements, - * if false, the upstream exception is signalled immediately - * @return the source ObservableSource shifted in time by the specified delay + * if {@code true}, the upstream exception is signaled with the given delay, after all preceding normal elements, + * if {@code false}, the upstream exception is signaled immediately + * @return the current {@code Observable} shifted in time by the specified delay + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Delay */ @CheckReturnValue @@ -7619,13 +7851,13 @@ public final Observable delay(long delay, @NonNull TimeUnit unit, @NonNull Sc } /** - * Returns an Observable that delays the subscription to and emissions from the source ObservableSource via another - * ObservableSource on a per-item basis. + * Returns an {@code Observable} that delays the subscription to and emissions from the current {@code Observable} via + * {@link ObservableSource}s for the subscription itself and on a per-item basis. *

* *

- * Note: the resulting ObservableSource will immediately propagate any {@code onError} notification - * from the source ObservableSource. + * Note: the resulting {@code Observable} will immediately propagate any {@code onError} notification + * from the current {@code Observable}. *

*
Scheduler:
*
This version of {@code delay} does not operate by default on a particular {@link Scheduler}.
@@ -7636,14 +7868,15 @@ public final Observable delay(long delay, @NonNull TimeUnit unit, @NonNull Sc * @param * the item delay value type (ignored) * @param subscriptionDelay - * a function that returns an ObservableSource that triggers the subscription to the source ObservableSource + * a function that returns an {@code ObservableSource} that triggers the subscription to the current {@code Observable} * once it emits any item * @param itemDelay - * a function that returns an ObservableSource for each item emitted by the source ObservableSource, which is - * then used to delay the emission of that item by the resulting ObservableSource until the ObservableSource + * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable}, which is + * then used to delay the emission of that item by the resulting {@code Observable} until the {@code ObservableSource} * returned from {@code itemDelay} emits an item - * @return an Observable that delays the subscription and emissions of the source ObservableSource via another - * ObservableSource on a per-item basis + * @return an {@code Observable} that delays the subscription and emissions of the current {@code Observable} via another + * {@code ObservableSource} on a per-item basis + * @throws NullPointerException if {@code subscriptionDelay} or {@code itemDelay} is {@code null} * @see ReactiveX operators documentation: Delay */ @CheckReturnValue @@ -7655,8 +7888,8 @@ public final Observable delay(@NonNull ObservableSource subscriptio } /** - * Returns an Observable that delays the subscription to this Observable - * until the other Observable emits an element or completes normally. + * Returns an {@code Observable} that delays the subscription to the current {@code Observable} + * until the other {@link ObservableSource} emits an element or completes normally. *

* *

@@ -7664,11 +7897,12 @@ public final Observable delay(@NonNull ObservableSource subscriptio *
This method does not operate by default on a particular {@link Scheduler}.
*
* - * @param the value type of the other Observable, irrelevant - * @param other the other Observable that should trigger the subscription - * to this Observable. - * @return an Observable that delays the subscription to this Observable - * until the other Observable emits an element or completes normally. + * @param the value type of the other {@code Observable}, irrelevant + * @param other the other {@code ObservableSource} that should trigger the subscription + * to the current {@code Observable}. + * @return an {@code Observable} that delays the subscription to the current {@code Observable} + * until the other {@code ObservableSource} emits an element or completes normally. + * @throws NullPointerException if {@code other} is {@code null} * @since 2.0 */ @CheckReturnValue @@ -7680,7 +7914,7 @@ public final Observable delaySubscription(@NonNull ObservableSource ot } /** - * Returns an Observable that delays the subscription to the source ObservableSource by a given amount of time. + * Returns an {@code Observable} that delays the subscription to the current {@code Observable} by a given amount of time. *

* *

@@ -7692,7 +7926,8 @@ public final Observable delaySubscription(@NonNull ObservableSource ot * the time to delay the subscription * @param unit * the time unit of {@code delay} - * @return an Observable that delays the subscription to the source ObservableSource by the given amount + * @return an {@code Observable} that delays the subscription to the current {@code Observable} by the given amount + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: Delay */ @CheckReturnValue @@ -7703,13 +7938,13 @@ public final Observable delaySubscription(long delay, @NonNull TimeUnit unit) } /** - * Returns an Observable that delays the subscription to the source ObservableSource by a given amount of time, - * both waiting and subscribing on a given Scheduler. + * Returns an {@code Observable} that delays the subscription to the current {@code Observable} by a given amount of time, + * both waiting and subscribing on a given {@link Scheduler}. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param delay @@ -7717,9 +7952,10 @@ public final Observable delaySubscription(long delay, @NonNull TimeUnit unit) * @param unit * the time unit of {@code delay} * @param scheduler - * the Scheduler on which the waiting and subscription will happen - * @return an Observable that delays the subscription to the source ObservableSource by a given - * amount, waiting and subscribing on the given Scheduler + * the {@code Scheduler} on which the waiting and subscription will happen + * @return an {@code Observable} that delays the subscription to the current {@code Observable} by a given + * amount, waiting and subscribing on the given {@code Scheduler} + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Delay */ @CheckReturnValue @@ -7730,9 +7966,9 @@ public final Observable delaySubscription(long delay, @NonNull TimeUnit unit, } /** - * Returns an Observable that reverses the effect of {@link #materialize materialize} by transforming the + * Returns an {@code Observable} that reverses the effect of {@link #materialize materialize} by transforming the * {@link Notification} objects extracted from the source items via a selector function - * into their respective {@code Observer} signal types. + * into their respective {@link Observer} signal types. *

* *

@@ -7744,7 +7980,7 @@ public final Observable delaySubscription(long delay, @NonNull TimeUnit unit, *

* When the upstream signals an {@link Notification#createOnError(Throwable) onError} or * {@link Notification#createOnComplete() onComplete} item, the - * returned Observable disposes of the flow and terminates with that type of terminal event: + * returned {@code Observable} disposes of the flow and terminates with that type of terminal event: * 


      * Observable.just(createOnNext(1), createOnComplete(), createOnNext(2))
      * .doOnDispose(() -> System.out.println("Disposed!"));
@@ -7769,10 +8005,11 @@ public final Observable delaySubscription(long delay, @NonNull TimeUnit unit,
      * 
History: 2.2.4 - experimental
      *
      * @param  the output value type
-     * @param selector function that returns the upstream item and should return a Notification to signal
+     * @param selector function that returns the upstream item and should return a {@code Notification} to signal
      * the corresponding {@code Observer} event to the downstream.
-     * @return an Observable that emits the items and notifications embedded in the {@link Notification} objects
-     *         selected from the items emitted by the source ObservableSource
+     * @return an {@code Observable} that emits the items and notifications embedded in the {@code Notification} objects
+     *         selected from the items emitted by the current {@code Observable}
+     * @throws NullPointerException if {@code selector} is {@code null}
      * @see ReactiveX operators documentation: Dematerialize
      * @since 3.0.0
      */
@@ -7785,7 +8022,7 @@ public final  Observable dematerialize(@NonNull Function
      * 
@@ -7794,13 +8031,13 @@ public final  Observable dematerialize(@NonNull Function
-     * By default, {@code distinct()} uses an internal {@link java.util.HashSet} per Observer to remember
+     * By default, {@code distinct()} uses an internal {@link HashSet} per {@link Observer} to remember
      * previously seen items and uses {@link java.util.Set#add(Object)} returning {@code false} as the
      * indicator for duplicates.
      * 

      * Note that this internal {@code HashSet} may grow unbounded as items won't be removed from it by
      * the operator. Therefore, using very long or infinite upstream (with very distinct elements) may lead
-     * to {@code OutOfMemoryError}.
+     * to {@link OutOfMemoryError}.
      * 

      * Customizing the retention policy can happen only by providing a custom {@link java.util.Collection} implementation
      * to the {@link #distinct(Function, Supplier)} overload.
@@ -7809,7 +8046,7 @@ public final  Observable dematerialize(@NonNull Function{@code distinct} does not operate by default on a particular {@link Scheduler}.
      *
* - * @return an Observable that emits only those items emitted by the source ObservableSource that are distinct from + * @return an {@code Observable} that emits only those items emitted by the current {@code Observable} that are distinct from * each other * @see ReactiveX operators documentation: Distinct * @see #distinct(Function) @@ -7823,7 +8060,7 @@ public final Observable distinct() { } /** - * Returns an Observable that emits all items emitted by the source ObservableSource that are distinct according + * Returns an {@code Observable} that emits all items emitted by the current {@code Observable} that are distinct according * to a key selector function and based on {@link Object#equals(Object)} comparison of the objects * returned by the key selector function. *

@@ -7833,13 +8070,13 @@ public final Observable distinct() { * and {@link Object#hashCode()} to provide meaningful comparison between the key objects as the default * Java implementation only considers reference equivalence. *

- * By default, {@code distinct()} uses an internal {@link java.util.HashSet} per Observer to remember + * By default, {@code distinct()} uses an internal {@link HashSet} per {@link Observer} to remember * previously seen keys and uses {@link java.util.Set#add(Object)} returning {@code false} as the * indicator for duplicates. *

* Note that this internal {@code HashSet} may grow unbounded as keys won't be removed from it by * the operator. Therefore, using very long or infinite upstream (with very distinct keys) may lead - * to {@code OutOfMemoryError}. + * to {@link OutOfMemoryError}. *

* Customizing the retention policy can happen only by providing a custom {@link java.util.Collection} implementation * to the {@link #distinct(Function, Supplier)} overload. @@ -7852,7 +8089,8 @@ public final Observable distinct() { * @param keySelector * a function that projects an emitted item to a key value that is used to decide whether an item * is distinct from another one or not - * @return an Observable that emits those items emitted by the source ObservableSource that have distinct keys + * @return an {@code Observable} that emits those items emitted by the current {@code Observable} that have distinct keys + * @throws NullPointerException if {@code keySelector} is {@code null} * @see ReactiveX operators documentation: Distinct * @see #distinct(Function, Supplier) */ @@ -7864,7 +8102,7 @@ public final Observable distinct(@NonNull Function keySelec } /** - * Returns an Observable that emits all items emitted by the source ObservableSource that are distinct according + * Returns an {@code Observable} that emits all items emitted by the current {@code Observable} that are distinct according * to a key selector function and based on {@link Object#equals(Object)} comparison of the objects * returned by the key selector function. *

@@ -7883,9 +8121,10 @@ public final Observable distinct(@NonNull Function keySelec * a function that projects an emitted item to a key value that is used to decide whether an item * is distinct from another one or not * @param collectionSupplier - * function called for each individual Observer to return a Collection subtype for holding the extracted - * keys and whose add() method's return indicates uniqueness. - * @return an Observable that emits those items emitted by the source ObservableSource that have distinct keys + * function called for each individual {@link Observer} to return a {@link Collection} subtype for holding the extracted + * keys and whose {@code add()} method's return indicates uniqueness. + * @return an {@code Observable} that emits those items emitted by the current {@code Observable} that have distinct keys + * @throws NullPointerException if {@code keySelector} or {@code collectionSupplier} is {@code null} * @see ReactiveX operators documentation: Distinct */ @CheckReturnValue @@ -7898,7 +8137,7 @@ public final Observable distinct(@NonNull Function keySelec } /** - * Returns an Observable that emits all items emitted by the source ObservableSource that are distinct from their + * Returns an {@code Observable} that emits all items emitted by the current {@code Observable} that are distinct from their * immediate predecessors based on {@link Object#equals(Object)} comparison. *

* @@ -7914,7 +8153,7 @@ public final Observable distinct(@NonNull Function keySelec *

* Note that if element type {@code T} in the flow is mutable, the comparison of the previous and current * item may yield unexpected results if the items are mutated externally. Common cases are mutable - * {@code CharSequence}s or {@code List}s where the objects will actually have the same + * {@link CharSequence}s or {@link List}s where the objects will actually have the same * references when they are modified and {@code distinctUntilChanged} will evaluate subsequent items as same. * To avoid such situation, it is recommended that mutable data is converted to an immutable one, * for example using {@code map(CharSequence::toString)} or {@code map(list -> Collections.unmodifiableList(new ArrayList<>(list)))}. @@ -7923,7 +8162,7 @@ public final Observable distinct(@NonNull Function keySelec *

{@code distinctUntilChanged} does not operate by default on a particular {@link Scheduler}.
*
* - * @return an Observable that emits those items from the source ObservableSource that are distinct from their + * @return an {@code Observable} that emits those items from the current {@code Observable} that are distinct from their * immediate predecessors * @see ReactiveX operators documentation: Distinct * @see #distinctUntilChanged(BiPredicate) @@ -7936,7 +8175,7 @@ public final Observable distinctUntilChanged() { } /** - * Returns an Observable that emits all items emitted by the source ObservableSource that are distinct from their + * Returns an {@code Observable} that emits all items emitted by the current {@code Observable} that are distinct from their * immediate predecessors, according to a key selector function and based on {@link Object#equals(Object)} comparison * of those objects returned by the key selector function. *

@@ -7954,7 +8193,7 @@ public final Observable distinctUntilChanged() { *

* Note that if element type {@code T} in the flow is mutable, the comparison of the previous and current * item may yield unexpected results if the items are mutated externally. Common cases are mutable - * {@code CharSequence}s or {@code List}s where the objects will actually have the same + * {@link CharSequence}s or {@link List}s where the objects will actually have the same * references when they are modified and {@code distinctUntilChanged} will evaluate subsequent items as same. * To avoid such situation, it is recommended that mutable data is converted to an immutable one, * for example using {@code map(CharSequence::toString)} or {@code map(list -> Collections.unmodifiableList(new ArrayList<>(list)))}. @@ -7967,8 +8206,9 @@ public final Observable distinctUntilChanged() { * @param keySelector * a function that projects an emitted item to a key value that is used to decide whether an item * is distinct from another one or not - * @return an Observable that emits those items from the source ObservableSource whose keys are distinct from + * @return an {@code Observable} that emits those items from the current {@code Observable} whose keys are distinct from * those of their immediate predecessors + * @throws NullPointerException if {@code keySelector} is {@code null} * @see ReactiveX operators documentation: Distinct */ @CheckReturnValue @@ -7980,7 +8220,7 @@ public final Observable distinctUntilChanged(@NonNull Function * @@ -7990,7 +8230,7 @@ public final Observable distinctUntilChanged(@NonNull Function * Note that if element type {@code T} in the flow is mutable, the comparison of the previous and current * item may yield unexpected results if the items are mutated externally. Common cases are mutable - * {@code CharSequence}s or {@code List}s where the objects will actually have the same + * {@link CharSequence}s or {@link List}s where the objects will actually have the same * references when they are modified and {@code distinctUntilChanged} will evaluate subsequent items as same. * To avoid such situation, it is recommended that mutable data is converted to an immutable one, * for example using {@code map(CharSequence::toString)} or {@code map(list -> Collections.unmodifiableList(new ArrayList<>(list)))}. @@ -8000,9 +8240,10 @@ public final Observable distinctUntilChanged(@NonNull Function * * @param comparer the function that receives the previous item and the current item and is - * expected to return true if the two are equal, thus skipping the current value. - * @return an Observable that emits those items from the source ObservableSource that are distinct from their + * expected to return {@code true} if the two are equal, thus skipping the current value. + * @return an {@code Observable} that emits those items from the current {@code Observable} that are distinct from their * immediate predecessors + * @throws NullPointerException if {@code comparer} is {@code null} * @see ReactiveX operators documentation: Distinct * @since 2.0 */ @@ -8015,8 +8256,9 @@ public final Observable distinctUntilChanged(@NonNull BiPredicateNote that the {@code onAfterNext} action is shared between subscriptions and as such + * Calls the specified {@link Consumer} with the current item after this item has been emitted to the downstream. + *

+ * Note that the {@code onAfterNext} action is shared between subscriptions and as such * should be thread-safe. *

* @@ -8027,8 +8269,9 @@ public final Observable distinctUntilChanged(@NonNull BiPredicateThis operator supports boundary-limited synchronous or asynchronous queue-fusion. *

*

History: 2.0.1 - experimental - * @param onAfterNext the Consumer that will be called after emitting an item from upstream to the downstream - * @return the new Observable instance + * @param onAfterNext the {@code Consumer} that will be called after emitting an item from upstream to the downstream + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code onAfterNext} is {@code null} * @since 2.1 */ @CheckReturnValue @@ -8040,7 +8283,7 @@ public final Observable doAfterNext(@NonNull Consumer onAfterNext) } /** - * Registers an {@link Action} to be called when this ObservableSource invokes either + * Registers an {@link Action} to be called when the current {@code Observable} invokes either * {@link Observer#onComplete onComplete} or {@link Observer#onError onError}. *

* @@ -8049,23 +8292,24 @@ public final Observable doAfterNext(@NonNull Consumer onAfterNext) *

{@code doAfterTerminate} does not operate by default on a particular {@link Scheduler}.
*
* - * @param onFinally - * an {@link Action} to be invoked when the source ObservableSource finishes - * @return an Observable that emits the same items as the source ObservableSource, then invokes the - * {@link Action} + * @param onAfterTerminate + * an {@code Action} to be invoked after the current {@code Observable} finishes + * @return an {@code Observable} that emits the same items as the current {@code Observable}, then invokes the + * {@code Action} + * @throws NullPointerException if {@code onAfterTerminate} is {@code null} * @see ReactiveX operators documentation: Do * @see #doOnTerminate(Action) */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @NonNull - public final Observable doAfterTerminate(@NonNull Action onFinally) { - Objects.requireNonNull(onFinally, "onFinally is null"); - return doOnEach(Functions.emptyConsumer(), Functions.emptyConsumer(), Functions.EMPTY_ACTION, onFinally); + public final Observable doAfterTerminate(@NonNull Action onAfterTerminate) { + Objects.requireNonNull(onAfterTerminate, "onAfterTerminate is null"); + return doOnEach(Functions.emptyConsumer(), Functions.emptyConsumer(), Functions.EMPTY_ACTION, onAfterTerminate); } /** - * Calls the specified action after this Observable signals onError or onCompleted or gets disposed by + * Calls the specified action after the current {@code Observable} signals {@code onError} or {@code onCompleted} or gets disposed by * the downstream. *

In case of a race between a terminal event and a dispose call, the provided {@code onFinally} action * is executed once per subscription. @@ -8080,8 +8324,9 @@ public final Observable doAfterTerminate(@NonNull Action onFinally) { *

This operator supports boundary-limited synchronous or asynchronous queue-fusion.
*
*

History: 2.0.1 - experimental - * @param onFinally the action called when this Observable terminates or gets disposed - * @return the new Observable instance + * @param onFinally the action called when the current {@code Observable} terminates or gets disposed + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code onFinally} is {@code null} * @since 2.1 */ @CheckReturnValue @@ -8093,13 +8338,13 @@ public final Observable doFinally(@NonNull Action onFinally) { } /** - * Calls the dispose {@code Action} if the downstream disposes the sequence. + * Calls the given shared {@link Action} if the downstream disposes the sequence. *

* The action is shared between subscriptions and thus may be called concurrently from multiple * threads; the action must be thread safe. *

* If the action throws a runtime exception, that exception is rethrown by the {@code dispose()} call, - * sometimes as a {@code CompositeException} if there were multiple exceptions along the way. + * sometimes as a {@link CompositeException} if there were multiple exceptions along the way. *

* *

@@ -8108,9 +8353,9 @@ public final Observable doFinally(@NonNull Action onFinally) { *
* * @param onDispose - * the action that gets called when the source {@code ObservableSource}'s Disposable is disposed - * @return the source {@code ObservableSource} modified so as to call this Action when appropriate - * @throws NullPointerException if onDispose is null + * the action that gets called when the current {@code Observable}'s {@link Disposable} is disposed + * @return the current {@code Observable} modified so as to call this {@code Action} when appropriate + * @throws NullPointerException if {@code onDispose} is {@code null} * @see ReactiveX operators documentation: Do */ @CheckReturnValue @@ -8121,7 +8366,7 @@ public final Observable doOnDispose(@NonNull Action onDispose) { } /** - * Modifies the source ObservableSource so that it invokes an action when it calls {@code onComplete}. + * Returns an {@code Observable} that invokes an {@link Action} when the current {@code Observable} calls {@code onComplete}. *

* *

@@ -8130,8 +8375,9 @@ public final Observable doOnDispose(@NonNull Action onDispose) { *
* * @param onComplete - * the action to invoke when the source ObservableSource calls {@code onComplete} - * @return the source ObservableSource with the side-effecting behavior applied + * the action to invoke when the current {@code Observable} calls {@code onComplete} + * @return the current {@code Observable} with the side-effecting behavior applied + * @throws NullPointerException if {@code onComplete} is {@code null} * @see ReactiveX operators documentation: Do */ @CheckReturnValue @@ -8142,8 +8388,8 @@ public final Observable doOnComplete(@NonNull Action onComplete) { } /** - * Calls the appropriate onXXX consumer (shared between all subscribers) whenever a signal with the same type - * passes through, before forwarding them to downstream. + * Calls the appropriate {@code onXXX} consumer (shared between all {@link Observer}s) whenever a signal with the same type + * passes through, before forwarding them to the downstream. *

* *

@@ -8151,7 +8397,8 @@ public final Observable doOnComplete(@NonNull Action onComplete) { *
{@code doOnEach} does not operate by default on a particular {@link Scheduler}.
*
* - * @return the source ObservableSource with the side-effecting behavior applied + * @return the current {@code Observable} with the side-effecting behavior applied + * @throws NullPointerException if {@code onNext}, {@code onError}, {@code onComplete} or {@code onAfterTerminate} is {@code null} * @see ReactiveX operators documentation: Do */ @CheckReturnValue @@ -8166,7 +8413,8 @@ private Observable doOnEach(@NonNull Consumer onNext, @NonNull Con } /** - * Modifies the source ObservableSource so that it invokes an action for each item it emits. + * Returns an {@code Observable} that invokes a {@link Consumer} with the appropriate {@link Notification} + * object when the current {@code Observable} signals an item or terminates. *

* *

@@ -8175,8 +8423,9 @@ private Observable doOnEach(@NonNull Consumer onNext, @NonNull Con *
* * @param onNotification - * the action to invoke for each item emitted by the source ObservableSource - * @return the source ObservableSource with the side-effecting behavior applied + * the action to invoke for each item emitted by the current {@code Observable} + * @return the current {@code Observable} with the side-effecting behavior applied + * @throws NullPointerException if {@code onNotification} is {@code null} * @see ReactiveX operators documentation: Do */ @CheckReturnValue @@ -8193,7 +8442,8 @@ public final Observable doOnEach(@NonNull Consumer> o } /** - * Modifies the source ObservableSource so that it notifies an Observer for each item and terminal event it emits. + * Returns an {@code Observable} that forwards the items and terminal events of the current + * {@code Observable} to its {@link Observer}s and to the given shared {@code Observer} instance. *

* In case the {@code onError} of the supplied observer throws, the downstream will receive a composite * exception containing the original exception and the exception thrown by {@code onError}. If either the @@ -8207,9 +8457,10 @@ public final Observable doOnEach(@NonNull Consumer> o *

* * @param observer - * the observer to be notified about onNext, onError and onComplete events on its - * respective methods before the actual downstream Observer gets notified. - * @return the source ObservableSource with the side-effecting behavior applied + * the observer to be notified about {@code onNext}, {@code onError} and {@code onComplete} events on its + * respective methods before the actual downstream {@code Observer} gets notified. + * @return the current {@code Observable} with the side-effecting behavior applied + * @throws NullPointerException if {@code observer} is {@code null} * @see ReactiveX operators documentation: Do */ @CheckReturnValue @@ -8225,7 +8476,7 @@ public final Observable doOnEach(@NonNull Observer observer) { } /** - * Modifies the source ObservableSource so that it invokes an action if it calls {@code onError}. + * Modifies the current {@code Observable} so that it invokes an action if it calls {@code onError}. *

* In case the {@code onError} action throws, the downstream will receive a composite exception containing * the original exception and the exception thrown by {@code onError}. @@ -8237,8 +8488,9 @@ public final Observable doOnEach(@NonNull Observer observer) { *

* * @param onError - * the action to invoke if the source ObservableSource calls {@code onError} - * @return the source ObservableSource with the side-effecting behavior applied + * the action to invoke if the current {@code Observable} calls {@code onError} + * @return the current {@code Observable} with the side-effecting behavior applied + * @throws NullPointerException if {@code onError} is {@code null} * @see ReactiveX operators documentation: Do */ @CheckReturnValue @@ -8249,7 +8501,7 @@ public final Observable doOnError(@NonNull Consumer onErro } /** - * Calls the appropriate onXXX method (shared between all Observer) for the lifecycle events of + * Calls the appropriate {@code onXXX} method (shared between all {@link Observer}s) for the lifecycle events of * the sequence (subscription, disposal). *

* @@ -8259,10 +8511,11 @@ public final Observable doOnError(@NonNull Consumer onErro *

* * @param onSubscribe - * a Consumer called with the Disposable sent via Observer.onSubscribe() + * a {@link Consumer} called with the {@link Disposable} sent via {@link Observer#onSubscribe(Disposable)} * @param onDispose - * called when the downstream disposes the Disposable via dispose() - * @return the source ObservableSource with the side-effecting behavior applied + * called when the downstream disposes the {@code Disposable} via {@code dispose()} + * @return the current {@code Observable} with the side-effecting behavior applied + * @throws NullPointerException if {@code onSubscribe} or {@code onDispose} is {@code null} * @see ReactiveX operators documentation: Do */ @CheckReturnValue @@ -8275,7 +8528,7 @@ public final Observable doOnLifecycle(@NonNull Consumer o } /** - * Modifies the source ObservableSource so that it invokes an action when it calls {@code onNext}. + * Modifies the current {@code Observable} so that it invokes an action when it calls {@code onNext}. *

* *

@@ -8284,8 +8537,9 @@ public final Observable doOnLifecycle(@NonNull Consumer o *
* * @param onNext - * the action to invoke when the source ObservableSource calls {@code onNext} - * @return the source ObservableSource with the side-effecting behavior applied + * the action to invoke when the current {@code Observable} calls {@code onNext} + * @return the current {@code Observable} with the side-effecting behavior applied + * @throws NullPointerException if {@code onNext} is {@code null} * @see ReactiveX operators documentation: Do */ @CheckReturnValue @@ -8296,9 +8550,9 @@ public final Observable doOnNext(@NonNull Consumer onNext) { } /** - * Modifies the source {@code ObservableSource} so that it invokes the given action when it is subscribed from - * its subscribers. Each subscription will result in an invocation of the given action except when the - * source {@code ObservableSource} is reference counted, in which case the source {@code ObservableSource} will invoke + * Returns an {@code Observable} so that it invokes the given {@link Consumer} when the current {@code Observable} is subscribed from + * its {@link Observer}s. Each subscription will result in an invocation of the given action except when the + * current {@code Observable} is reference counted, in which case the current {@code Observable} will invoke * the given action for the first subscription. *

* @@ -8308,8 +8562,9 @@ public final Observable doOnNext(@NonNull Consumer onNext) { *

* * @param onSubscribe - * the Consumer that gets called when an Observer subscribes to the current {@code Observable} - * @return the source {@code ObservableSource} modified so as to call this Consumer when appropriate + * the {@code Consumer} that gets called when an {@code Observer} subscribes to the current {@code Observable} + * @return the current {@code Observable} modified so as to call this {@code Consumer} whenever it gets subscribed + * @throws NullPointerException if {@code onSubscribe} is {@code null} * @see ReactiveX operators documentation: Do */ @CheckReturnValue @@ -8320,7 +8575,7 @@ public final Observable doOnSubscribe(@NonNull Consumer o } /** - * Modifies the source ObservableSource so that it invokes an action when it calls {@code onComplete} or + * Returns an {@code Observable} so that it invokes an action when the current {@code Observable} calls {@code onComplete} or * {@code onError}. *

* @@ -8333,8 +8588,9 @@ public final Observable doOnSubscribe(@NonNull Consumer o *

* * @param onTerminate - * the action to invoke when the source ObservableSource calls {@code onComplete} or {@code onError} - * @return the source ObservableSource with the side-effecting behavior applied + * the action to invoke when the current {@code Observable} calls {@code onComplete} or {@code onError} + * @return the current {@code Observable} with the side-effecting behavior applied + * @throws NullPointerException if {@code onTerminate} is {@code null} * @see ReactiveX operators documentation: Do * @see #doAfterTerminate(Action) */ @@ -8349,8 +8605,8 @@ public final Observable doOnTerminate(@NonNull Action onTerminate) { } /** - * Returns a Maybe that emits the single item at a specified index in a sequence of emissions from - * this Observable or completes if this Observable signals fewer elements than index. + * Returns a {@link Maybe} that emits the single item at a specified index in a sequence of emissions from + * the current {@code Observable} or completes if the current {@code Observable} signals fewer elements than index. *

* *

@@ -8360,10 +8616,10 @@ public final Observable doOnTerminate(@NonNull Action onTerminate) { * * @param index * the zero-based index of the item to retrieve - * @return a Maybe that emits a single item: the item at the specified position in the sequence of - * those emitted by the source ObservableSource + * @return a {@code Maybe} that emits a single item: the item at the specified position in the sequence of + * those emitted by the current {@code Observable} * @throws IndexOutOfBoundsException - * if {@code index} is less than 0 + * if {@code index} is negative * @see ReactiveX operators documentation: ElementAt */ @CheckReturnValue @@ -8377,8 +8633,8 @@ public final Maybe elementAt(long index) { } /** - * Returns a Single that emits the item found at a specified index in a sequence of emissions from - * this Observable, or a default item if that index is out of range. + * Returns a {@link Single} that emits the item found at a specified index in a sequence of emissions from + * the current {@code Observable}, or a default item if that index is out of range. *

* *

@@ -8390,10 +8646,11 @@ public final Maybe elementAt(long index) { * the zero-based index of the item to retrieve * @param defaultItem * the default item - * @return a Single that emits the item at the specified position in the sequence emitted by the source - * ObservableSource, or the default item if that index is outside the bounds of the source sequence + * @return a {@code Single} that emits the item at the specified position in the sequence emitted by the current + * {@code Observable}, or the default item if that index is outside the bounds of the source sequence + * @throws NullPointerException if {@code defaultItem} is {@code null} * @throws IndexOutOfBoundsException - * if {@code index} is less than 0 + * if {@code index} is negative * @see ReactiveX operators documentation: ElementAt */ @CheckReturnValue @@ -8408,8 +8665,8 @@ public final Single elementAt(long index, @NonNull T defaultItem) { } /** - * Returns a Single that emits the item found at a specified index in a sequence of emissions from this Observable - * or signals a {@link NoSuchElementException} if this Observable signals fewer elements than index. + * Returns a {@link Single} that emits the item found at a specified index in a sequence of emissions from the current {@code Observable} + * or signals a {@link NoSuchElementException} if the current {@code Observable} signals fewer elements than index. *

* *

@@ -8419,10 +8676,10 @@ public final Single elementAt(long index, @NonNull T defaultItem) { * * @param index * the zero-based index of the item to retrieve - * @return a Single that emits the item at the specified position in the sequence emitted by the source - * ObservableSource, or the default item if that index is outside the bounds of the source sequence + * @return a {@code Single} that emits the item at the specified position in the sequence emitted by the current + * {@code Observable}, or the default item if that index is outside the bounds of the source sequence * @throws IndexOutOfBoundsException - * if {@code index} is less than 0 + * if {@code index} is negative * @see ReactiveX operators documentation: ElementAt */ @CheckReturnValue @@ -8436,7 +8693,7 @@ public final Single elementAtOrError(long index) { } /** - * Filters items emitted by an ObservableSource by only emitting those that satisfy a specified predicate. + * Filters items emitted by the current {@code Observable} by only emitting those that satisfy a specified {@link Predicate}. *

* *

@@ -8445,10 +8702,11 @@ public final Single elementAtOrError(long index) { *
* * @param predicate - * a function that evaluates each item emitted by the source ObservableSource, returning {@code true} + * a function that evaluates each item emitted by the current {@code Observable}, returning {@code true} * if it passes the filter - * @return an Observable that emits only those items emitted by the source ObservableSource that the filter + * @return an {@code Observable} that emits only those items emitted by the current {@code Observable} that the filter * evaluates as {@code true} + * @throws NullPointerException if {@code predicate} is {@code null} * @see ReactiveX operators documentation: Filter */ @CheckReturnValue @@ -8460,8 +8718,8 @@ public final Observable filter(@NonNull Predicate predicate) { } /** - * Returns a Maybe that emits only the very first item emitted by the source ObservableSource, or - * completes if the source ObservableSource is empty. + * Returns a {@link Maybe} that emits only the very first item emitted by the current {@code Observable}, or + * completes if the current {@code Observable} is empty. *

* *

@@ -8469,7 +8727,7 @@ public final Observable filter(@NonNull Predicate predicate) { *
{@code firstElement} does not operate by default on a particular {@link Scheduler}.
*
* - * @return the new Maybe instance + * @return the new {@code Maybe} instance * @see ReactiveX operators documentation: First */ @CheckReturnValue @@ -8480,8 +8738,8 @@ public final Maybe firstElement() { } /** - * Returns a Single that emits only the very first item emitted by the source ObservableSource, or a default item - * if the source ObservableSource completes without emitting any items. + * Returns a {@link Single} that emits only the very first item emitted by the current {@code Observable}, or a default item + * if the current {@code Observable} completes without emitting any items. *

* *

@@ -8490,8 +8748,9 @@ public final Maybe firstElement() { *
* * @param defaultItem - * the default item to emit if the source ObservableSource doesn't emit anything - * @return the new Single instance + * the default item to emit if the current {@code Observable} doesn't emit anything + * @return the new {@code Single} instance + * @throws NullPointerException if {@code defaultItem} is {@code null} * @see ReactiveX operators documentation: First */ @CheckReturnValue @@ -8502,8 +8761,8 @@ public final Single first(@NonNull T defaultItem) { } /** - * Returns a Single that emits only the very first item emitted by this Observable or - * signals a {@link NoSuchElementException} if this Observable is empty. + * Returns a {@link Single} that emits only the very first item emitted by the current {@code Observable} or + * signals a {@link NoSuchElementException} if the current {@code Observable} is empty. *

* *

@@ -8511,7 +8770,7 @@ public final Single first(@NonNull T defaultItem) { *
{@code firstOrError} does not operate by default on a particular {@link Scheduler}.
*
* - * @return the new Single instance + * @return the new {@code Single} instance * @see ReactiveX operators documentation: First */ @CheckReturnValue @@ -8522,9 +8781,9 @@ public final Single firstOrError() { } /** - * Returns an Observable that emits items based on applying a function that you supply to each item emitted - * by the source ObservableSource, where that function returns an ObservableSource, and then merging those resulting - * ObservableSources and emitting the results of this merger. + * Returns an {@code Observable} that emits items based on applying a function that you supply to each item emitted + * by the current {@code Observable}, where that function returns an {@link ObservableSource}, and then merging those returned + * {@code ObservableSource}s and emitting the results of this merger. *

* *

@@ -8532,13 +8791,14 @@ public final Single firstOrError() { *
{@code flatMap} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the value type of the inner ObservableSources and the output type + * @param the value type of the inner {@code ObservableSource}s and the output type * @param mapper - * a function that, when applied to an item emitted by the source ObservableSource, returns an - * ObservableSource - * @return an Observable that emits the result of applying the transformation function to each item emitted - * by the source ObservableSource and merging the results of the ObservableSources obtained from this + * a function that, when applied to an item emitted by the current {@code Observable}, returns an + * {@code ObservableSource} + * @return an {@code Observable} that emits the result of applying the transformation function to each item emitted + * by the current {@code Observable} and merging the results of the {@code ObservableSource}s obtained from this * transformation + * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: FlatMap */ @CheckReturnValue @@ -8549,9 +8809,9 @@ public final Observable flatMap(@NonNull Function * *
@@ -8559,16 +8819,17 @@ public final Observable flatMap(@NonNull Function{@code flatMap} does not operate by default on a particular {@link Scheduler}. *
* - * @param the value type of the inner ObservableSources and the output type + * @param the value type of the inner {@code ObservableSource}s and the output type * @param mapper - * a function that, when applied to an item emitted by the source ObservableSource, returns an - * ObservableSource + * a function that, when applied to an item emitted by the current {@code Observable}, returns an + * {@code ObservableSource} * @param delayErrors - * if true, exceptions from the current Observable and all inner ObservableSources are delayed until all of them terminate - * if false, the first one signalling an exception will terminate the whole sequence immediately - * @return an Observable that emits the result of applying the transformation function to each item emitted - * by the source ObservableSource and merging the results of the ObservableSources obtained from this + * if {@code true}, exceptions from the current {@code Observable} and all inner {@code ObservableSource}s are delayed until all of them terminate + * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately + * @return an {@code Observable} that emits the result of applying the transformation function to each item emitted + * by the current {@code Observable} and merging the results of the {@code ObservableSource}s obtained from this * transformation + * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: FlatMap */ @CheckReturnValue @@ -8579,10 +8840,10 @@ public final Observable flatMap(@NonNull Function * *
@@ -8590,18 +8851,20 @@ public final Observable flatMap(@NonNull Function{@code flatMap} does not operate by default on a particular {@link Scheduler}. *
* - * @param the value type of the inner ObservableSources and the output type + * @param the value type of the inner {@code ObservableSource}s and the output type * @param mapper - * a function that, when applied to an item emitted by the source ObservableSource, returns an - * ObservableSource + * a function that, when applied to an item emitted by the current {@code Observable}, returns an + * {@code ObservableSource} * @param maxConcurrency - * the maximum number of ObservableSources that may be subscribed to concurrently + * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently * @param delayErrors - * if true, exceptions from the current Observable and all inner ObservableSources are delayed until all of them terminate - * if false, the first one signalling an exception will terminate the whole sequence immediately - * @return an Observable that emits the result of applying the transformation function to each item emitted - * by the source ObservableSource and merging the results of the ObservableSources obtained from this + * if {@code true}, exceptions from the current {@code Observable} and all inner {@code ObservableSource}s are delayed until all of them terminate + * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately + * @return an {@code Observable} that emits the result of applying the transformation function to each item emitted + * by the current {@code Observable} and merging the results of the {@code ObservableSource}s obtained from this * transformation + * @throws NullPointerException if {@code mapper} is {@code null} + * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive * @see ReactiveX operators documentation: FlatMap * @since 2.0 */ @@ -8613,10 +8876,10 @@ public final Observable flatMap(@NonNull Function * *
@@ -8624,20 +8887,22 @@ public final Observable flatMap(@NonNull Function{@code flatMap} does not operate by default on a particular {@link Scheduler}. *
* - * @param the value type of the inner ObservableSources and the output type + * @param the value type of the inner {@code ObservableSource}s and the output type * @param mapper - * a function that, when applied to an item emitted by the source ObservableSource, returns an - * ObservableSource + * a function that, when applied to an item emitted by the current {@code Observable}, returns an + * {@code ObservableSource} * @param maxConcurrency - * the maximum number of ObservableSources that may be subscribed to concurrently + * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently * @param delayErrors - * if true, exceptions from the current Observable and all inner ObservableSources are delayed until all of them terminate - * if false, the first one signalling an exception will terminate the whole sequence immediately + * if {@code true}, exceptions from the current {@code Observable} and all inner {@code ObservableSource}s are delayed until all of them terminate + * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately * @param bufferSize - * the number of elements to prefetch from each inner ObservableSource - * @return an Observable that emits the result of applying the transformation function to each item emitted - * by the source ObservableSource and merging the results of the ObservableSources obtained from this + * the number of elements expected from each inner {@code ObservableSource} to be buffered + * @return an {@code Observable} that emits the result of applying the transformation function to each item emitted + * by the current {@code Observable} and merging the results of the {@code ObservableSource}s obtained from this * transformation + * @throws NullPointerException if {@code mapper} is {@code null} + * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive * @see ReactiveX operators documentation: FlatMap * @since 2.0 */ @@ -8661,8 +8926,8 @@ public final Observable flatMap(@NonNull Function * *
@@ -8673,15 +8938,16 @@ public final Observable flatMap(@NonNull Function * the result type * @param onNextMapper - * a function that returns an ObservableSource to merge for each item emitted by the source ObservableSource + * a function that returns an {@code ObservableSource} to merge for each item emitted by the current {@code Observable} * @param onErrorMapper - * a function that returns an ObservableSource to merge for an onError notification from the source - * ObservableSource + * a function that returns an {@code ObservableSource} to merge for an {@code onError} notification from the current + * {@code Observable} * @param onCompleteSupplier - * a function that returns an ObservableSource to merge for an onComplete notification from the source - * ObservableSource - * @return an Observable that emits the results of merging the ObservableSources returned from applying the - * specified functions to the emissions and notifications of the source ObservableSource + * a function that returns an {@code ObservableSource} to merge for an {@code onComplete} notification from the current + * {@code Observable} + * @return an {@code Observable} that emits the results of merging the {@code ObservableSource}s returned from applying the + * specified functions to the emissions and notifications of the current {@code Observable} + * @throws NullPointerException if {@code onNextMapper} or {@code onErrorMapper} or {@code onCompleteSupplier} is {@code null} * @see ReactiveX operators documentation: FlatMap */ @CheckReturnValue @@ -8698,9 +8964,9 @@ public final Observable flatMap( } /** - * Returns an Observable that applies a function to each item emitted or notification raised by the source - * ObservableSource and then flattens the ObservableSources returned from these functions and emits the resulting items, - * while limiting the maximum number of concurrent subscriptions to these ObservableSources. + * Returns an {@code Observable} that applies a function to each item emitted or notification raised by the current + * {@code Observable} and then flattens the {@link ObservableSource}s returned from these functions and emits the resulting items, + * while limiting the maximum number of concurrent subscriptions to these {@code ObservableSource}s. *

* *

@@ -8711,17 +8977,19 @@ public final Observable flatMap( * @param * the result type * @param onNextMapper - * a function that returns an ObservableSource to merge for each item emitted by the source ObservableSource + * a function that returns an {@code ObservableSource} to merge for each item emitted by the current {@code Observable} * @param onErrorMapper - * a function that returns an ObservableSource to merge for an onError notification from the source - * ObservableSource + * a function that returns an {@code ObservableSource} to merge for an {@code onError} notification from the current + * {@code Observable} * @param onCompleteSupplier - * a function that returns an ObservableSource to merge for an onComplete notification from the source - * ObservableSource + * a function that returns an {@code ObservableSource} to merge for an {@code onComplete} notification from the current + * {@code Observable} * @param maxConcurrency - * the maximum number of ObservableSources that may be subscribed to concurrently - * @return an Observable that emits the results of merging the ObservableSources returned from applying the - * specified functions to the emissions and notifications of the source ObservableSource + * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently + * @return an {@code Observable} that emits the results of merging the {@code ObservableSource}s returned from applying the + * specified functions to the emissions and notifications of the current {@code Observable} + * @throws NullPointerException if {@code onNextMapper} or {@code onErrorMapper} or {@code onCompleteSupplier} is {@code null} + * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive * @see ReactiveX operators documentation: FlatMap * @since 2.0 */ @@ -8740,10 +9008,10 @@ public final Observable flatMap( } /** - * Returns an Observable that emits items based on applying a function that you supply to each item emitted - * by the source ObservableSource, where that function returns an ObservableSource, and then merging those resulting - * ObservableSources and emitting the results of this merger, while limiting the maximum number of concurrent - * subscriptions to these ObservableSources. + * Returns an {@code Observable} that emits items based on applying a function that you supply to each item emitted + * by the current {@code Observable}, where that function returns an {@link ObservableSource}, and then merging those returned + * {@code ObservableSource}s and emitting the results of this merger, while limiting the maximum number of concurrent + * subscriptions to these {@code ObservableSource}s. *

* *

@@ -8751,15 +9019,17 @@ public final Observable flatMap( *
{@code flatMap} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the value type of the inner ObservableSources and the output type + * @param the value type of the inner {@code ObservableSource}s and the output type * @param mapper - * a function that, when applied to an item emitted by the source ObservableSource, returns an - * ObservableSource + * a function that, when applied to an item emitted by the current {@code Observable}, returns an + * {@code ObservableSource} * @param maxConcurrency - * the maximum number of ObservableSources that may be subscribed to concurrently - * @return an Observable that emits the result of applying the transformation function to each item emitted - * by the source ObservableSource and merging the results of the ObservableSources obtained from this + * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently + * @return an {@code Observable} that emits the result of applying the transformation function to each item emitted + * by the current {@code Observable} and merging the results of the {@code ObservableSource}s obtained from this * transformation + * @throws NullPointerException if {@code mapper} is {@code null} + * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive * @see ReactiveX operators documentation: FlatMap * @since 2.0 */ @@ -8771,8 +9041,8 @@ public final Observable flatMap(@NonNull Function * *
@@ -8781,29 +9051,30 @@ public final Observable flatMap(@NonNull Function * * @param - * the type of items emitted by the collection ObservableSource + * the type of items emitted by the collection {@code ObservableSource} * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param mapper - * a function that returns an ObservableSource for each item emitted by the source ObservableSource - * @param resultSelector - * a function that combines one item emitted by each of the source and collection ObservableSources and - * returns an item to be emitted by the resulting ObservableSource - * @return an Observable that emits the results of applying a function to a pair of values emitted by the - * source ObservableSource and the collection ObservableSource + * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable} + * @param combiner + * a function that combines one item emitted by each of the source and collection {@code ObservableSource}s and + * returns an item to be emitted by the resulting {@code Observable} + * @return an {@code Observable} that emits the results of applying a function to a pair of values emitted by the + * current {@code Observable} and the inner {@code ObservableSource}s + * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null} * @see ReactiveX operators documentation: FlatMap */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @NonNull public final Observable flatMap(@NonNull Function> mapper, - @NonNull BiFunction resultSelector) { - return flatMap(mapper, resultSelector, false, bufferSize(), bufferSize()); + @NonNull BiFunction combiner) { + return flatMap(mapper, combiner, false, bufferSize(), bufferSize()); } /** - * Returns an Observable that emits the results of a specified function to the pair of values emitted by the - * source ObservableSource and a specified collection ObservableSource. + * Returns an {@code Observable} that emits the results of a specified function to the pair of values emitted by the + * current {@code Observable} and the mapped inner {@link ObservableSource}. *

* *

@@ -8812,19 +9083,20 @@ public final Observable flatMap(@NonNull Function * * @param - * the type of items emitted by the collection ObservableSource + * the type of items emitted by the collection {@code ObservableSource} * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param mapper - * a function that returns an ObservableSource for each item emitted by the source ObservableSource + * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable} * @param combiner - * a function that combines one item emitted by each of the source and collection ObservableSources and - * returns an item to be emitted by the resulting ObservableSource + * a function that combines one item emitted by each of the source and collection {@code ObservableSource}s and + * returns an item to be emitted by the resulting {@code Observable} * @param delayErrors - * if true, exceptions from the current Observable and all inner ObservableSources are delayed until all of them terminate - * if false, the first one signalling an exception will terminate the whole sequence immediately - * @return an Observable that emits the results of applying a function to a pair of values emitted by the - * source ObservableSource and the collection ObservableSource + * if {@code true}, exceptions from the current {@code Observable} and all inner {@code ObservableSource}s are delayed until all of them terminate + * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately + * @return an {@code Observable} that emits the results of applying a function to a pair of values emitted by the + * current {@code Observable} and the inner {@code ObservableSource}s + * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null} * @see ReactiveX operators documentation: FlatMap */ @CheckReturnValue @@ -8836,9 +9108,9 @@ public final Observable flatMap(@NonNull Function * *
@@ -8847,21 +9119,23 @@ public final Observable flatMap(@NonNull Function * * @param - * the type of items emitted by the collection ObservableSource + * the type of items emitted by the collection {@code ObservableSource} * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param mapper - * a function that returns an ObservableSource for each item emitted by the source ObservableSource + * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable} * @param combiner - * a function that combines one item emitted by each of the source and collection ObservableSources and - * returns an item to be emitted by the resulting ObservableSource + * a function that combines one item emitted by each of the source and collection {@code ObservableSource}s and + * returns an item to be emitted by the resulting {@code Observable} * @param maxConcurrency - * the maximum number of ObservableSources that may be subscribed to concurrently + * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently * @param delayErrors - * if true, exceptions from the current Observable and all inner ObservableSources are delayed until all of them terminate - * if false, the first one signalling an exception will terminate the whole sequence immediately - * @return an Observable that emits the results of applying a function to a pair of values emitted by the - * source ObservableSource and the collection ObservableSource + * if {@code true}, exceptions from the current {@code Observable} and all inner {@code ObservableSource}s are delayed until all of them terminate + * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately + * @return an {@code Observable} that emits the results of applying a function to a pair of values emitted by the + * current {@code Observable} and the inner {@code ObservableSource} + * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null} + * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive * @see ReactiveX operators documentation: FlatMap * @since 2.0 */ @@ -8874,9 +9148,9 @@ public final Observable flatMap(@NonNull Function * *
@@ -8885,23 +9159,25 @@ public final Observable flatMap(@NonNull Function * * @param - * the type of items emitted by the collection ObservableSource + * the type of items emitted by the collection {@code ObservableSource} * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param mapper - * a function that returns an ObservableSource for each item emitted by the source ObservableSource + * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable} * @param combiner - * a function that combines one item emitted by each of the source and collection ObservableSources and - * returns an item to be emitted by the resulting ObservableSource + * a function that combines one item emitted by each of the source and collection {@code ObservableSource}s and + * returns an item to be emitted by the resulting {@code Observable} * @param maxConcurrency - * the maximum number of ObservableSources that may be subscribed to concurrently + * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently * @param delayErrors - * if true, exceptions from the current Observable and all inner ObservableSources are delayed until all of them terminate - * if false, the first one signalling an exception will terminate the whole sequence immediately + * if {@code true}, exceptions from the current {@code Observable} and all inner {@code ObservableSource}s are delayed until all of them terminate + * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately * @param bufferSize - * the number of elements to prefetch from the inner ObservableSources. - * @return an Observable that emits the results of applying a function to a pair of values emitted by the - * source ObservableSource and the collection ObservableSource + * the number of elements expected from the inner {@code ObservableSource} to be buffered + * @return an {@code Observable} that emits the results of applying a function to a pair of values emitted by the + * current {@code Observable} and the inner {@code ObservableSource} + * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null} + * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive * @see ReactiveX operators documentation: FlatMap * @since 2.0 */ @@ -8916,9 +9192,9 @@ public final Observable flatMap(@NonNull Function * *
@@ -8927,18 +9203,20 @@ public final Observable flatMap(@NonNull Function * * @param - * the type of items emitted by the collection ObservableSource + * the type of items emitted by the collection {@code ObservableSource} * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param mapper - * a function that returns an ObservableSource for each item emitted by the source ObservableSource + * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable} * @param combiner - * a function that combines one item emitted by each of the source and collection ObservableSources and - * returns an item to be emitted by the resulting ObservableSource + * a function that combines one item emitted by each of the source and collection {@code ObservableSource}s and + * returns an item to be emitted by the resulting {@code Observable} * @param maxConcurrency - * the maximum number of ObservableSources that may be subscribed to concurrently - * @return an Observable that emits the results of applying a function to a pair of values emitted by the - * source ObservableSource and the collection ObservableSource + * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently + * @return an {@code Observable} that emits the results of applying a function to a pair of values emitted by the + * current {@code Observable} and the inner {@code ObservableSource}s + * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null} + * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive * @see ReactiveX operators documentation: FlatMap * @since 2.0 */ @@ -8951,16 +9229,17 @@ public final Observable flatMap(@NonNull Function * *
*
Scheduler:
*
{@code flatMapCompletable} does not operate by default on a particular {@link Scheduler}.
*
- * @param mapper the function that received each source value and transforms them into CompletableSources. - * @return the new Completable instance + * @param mapper the function that received each source value and transforms them into {@code CompletableSource}s. + * @throws NullPointerException if {@code mapper} is {@code null} + * @return the new {@link Completable} instance */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -8970,18 +9249,19 @@ public final Completable flatMapCompletable(@NonNull Function * *
*
Scheduler:
*
{@code flatMapCompletable} does not operate by default on a particular {@link Scheduler}.
*
- * @param mapper the function that received each source value and transforms them into CompletableSources. - * @param delayErrors if true errors from the upstream and inner CompletableSources are delayed until each of them - * terminates. - * @return the new Completable instance + * @param mapper the function that received each source value and transforms them into {@code CompletableSource}s. + * @param delayErrors if {@code true}, errors from the upstream and inner {@code CompletableSource}s are delayed until all of them + * terminate. + * @return the new {@link Completable} instance + * @throws NullPointerException if {@code mapper} is {@code null} */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -8992,8 +9272,8 @@ public final Completable flatMapCompletable(@NonNull Function * *
@@ -9002,12 +9282,12 @@ public final Completable flatMapCompletable(@NonNull Function * * @param - * the type of item emitted by the resulting Iterable + * the output type and the element type of the {@code Iterable}s * @param mapper - * a function that returns an Iterable sequence of values for when given an item emitted by the - * source ObservableSource - * @return an Observable that emits the results of merging the items emitted by the source ObservableSource with - * the values in the Iterables corresponding to those items, as generated by {@code collectionSelector} + * a function that returns an {@code Iterable} sequence of values for when given an item emitted by the + * current {@code Observable} + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: FlatMap */ @CheckReturnValue @@ -9019,8 +9299,10 @@ public final Observable flatMapIterable(@NonNull Function * *
@@ -9029,32 +9311,32 @@ public final Observable flatMapIterable(@NonNull Function * * @param - * the collection element type + * the element type of the {@code Iterable}s * @param - * the type of item emitted by the resulting Iterable + * the output type as determined by the {@code resultSelector} function * @param mapper - * a function that returns an Iterable sequence of values for each item emitted by the source - * ObservableSource - * @param resultSelector - * a function that returns an item based on the item emitted by the source ObservableSource and the - * Iterable returned for that item by the {@code collectionSelector} - * @return an Observable that emits the items returned by {@code resultSelector} for each item in the source - * ObservableSource + * a function that returns an {@code Iterable} sequence of values for each item emitted by the current + * {@code Observable} + * @param combiner + * a function that returns an item based on the item emitted by the current {@code Observable} and the + * next item of the {@code Iterable} returned for that original item by the {@code mapper} + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null} * @see ReactiveX operators documentation: FlatMap */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @NonNull public final Observable flatMapIterable(@NonNull Function> mapper, - @NonNull BiFunction resultSelector) { + @NonNull BiFunction combiner) { Objects.requireNonNull(mapper, "mapper is null"); - Objects.requireNonNull(resultSelector, "resultSelector is null"); - return flatMap(ObservableInternalHelper.flatMapIntoIterable(mapper), resultSelector, false, bufferSize(), bufferSize()); + Objects.requireNonNull(combiner, "combiner is null"); + return flatMap(ObservableInternalHelper.flatMapIntoIterable(mapper), combiner, false, bufferSize(), bufferSize()); } /** - * Maps each element of the upstream Observable into MaybeSources, subscribes to all of them - * and merges their onSuccess values, in no particular order, into a single Observable sequence. + * Maps each element of the current {@code Observable} into {@link MaybeSource}s, subscribes to all of them + * and merges their {@code onSuccess} values, in no particular order, into a single {@code Observable} sequence. *

* *

@@ -9062,8 +9344,9 @@ public final Observable flatMapIterable(@NonNull Function{@code flatMapMaybe} does not operate by default on a particular {@link Scheduler}. *
* @param the result value type - * @param mapper the function that received each source value and transforms them into MaybeSources. - * @return the new Observable instance + * @param mapper the function that received each source value and transforms them into {@code MaybeSource}s. + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code mapper} is {@code null} */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -9073,8 +9356,8 @@ public final Observable flatMapMaybe(@NonNull Function * @@ -9083,10 +9366,11 @@ public final Observable flatMapMaybe(@NonNull Function{@code flatMapMaybe} does not operate by default on a particular {@link Scheduler}. *
* @param the result value type - * @param mapper the function that received each source value and transforms them into MaybeSources. - * @param delayErrors if true errors from the upstream and inner MaybeSources are delayed until each of them - * terminates. - * @return the new Observable instance + * @param mapper the function that received each source value and transforms them into {@code MaybeSource}s. + * @param delayErrors if {@code true}, errors from the upstream and inner {@code MaybeSource}s are delayed until all of them + * terminate. + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code mapper} is {@code null} */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -9097,8 +9381,8 @@ public final Observable flatMapMaybe(@NonNull Function * *
@@ -9106,8 +9390,9 @@ public final Observable flatMapMaybe(@NonNull Function{@code flatMapSingle} does not operate by default on a particular {@link Scheduler}. *
* @param the result value type - * @param mapper the function that received each source value and transforms them into SingleSources. - * @return the new Observable instance + * @param mapper the function that received each source value and transforms them into {@code SingleSource}s. + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code mapper} is {@code null} */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -9117,8 +9402,8 @@ public final Observable flatMapSingle(@NonNull Function * @@ -9127,10 +9412,11 @@ public final Observable flatMapSingle(@NonNull Function{@code flatMapSingle} does not operate by default on a particular {@link Scheduler}. *
* @param the result value type - * @param mapper the function that received each source value and transforms them into SingleSources. - * @param delayErrors if true errors from the upstream and inner SingleSources are delayed until each of them + * @param mapper the function that received each source value and transforms them into {@code SingleSource}s. + * @param delayErrors if {@code true}, errors from the upstream and inner {@code SingleSource}s are delayed until each of them * terminates. - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code mapper} is {@code null} */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -9141,7 +9427,8 @@ public final Observable flatMapSingle(@NonNull Function * *

@@ -9152,11 +9439,11 @@ public final Observable flatMapSingle(@NonNull Function * * @param onNext - * {@link Consumer} to execute for each item. + * the {@code Consumer} to execute for each item. * @return - * a Disposable that allows disposing of an asynchronous sequence + * a {@link Disposable} that allows disposing the sequence if the current {@code Observable} runs asynchronously * @throws NullPointerException - * if {@code onNext} is null + * if {@code onNext} is {@code null} * @see ReactiveX operators documentation: Subscribe */ @CheckReturnValue @@ -9167,25 +9454,25 @@ public final Disposable forEach(@NonNull Consumer onNext) { } /** - * Subscribes to the {@link ObservableSource} and receives notifications for each element until the - * onNext Predicate returns false. + * Subscribes to the {@link ObservableSource} and calls a {@link Predicate} for each item of the current {@code Observable}, + * on its emission thread, until the predicate returns {@code false}. *

* *

- * If the Observable emits an error, it is wrapped into an - * {@link io.reactivex.rxjava3.exceptions.OnErrorNotImplementedException OnErrorNotImplementedException} - * and routed to the RxJavaPlugins.onError handler. + * If the {@code Observable} emits an error, it is wrapped into an + * {@link OnErrorNotImplementedException} + * and routed to the {@link RxJavaPlugins#onError(Throwable)} handler. *

*
Scheduler:
*
{@code forEachWhile} does not operate by default on a particular {@link Scheduler}.
*
* * @param onNext - * {@link Predicate} to execute for each item. + * the {@code Predicate} to execute for each item. * @return - * a Disposable that allows disposing of an asynchronous sequence + * a {@link Disposable} that allows disposing the sequence if the current {@code Observable} runs asynchronously * @throws NullPointerException - * if {@code onNext} is null + * if {@code onNext} is {@code null} * @see ReactiveX operators documentation: Subscribe */ @CheckReturnValue @@ -9196,22 +9483,21 @@ public final Disposable forEachWhile(@NonNull Predicate onNext) { } /** - * Subscribes to the {@link ObservableSource} and receives notifications for each element and error events until the - * onNext Predicate returns false. + * Subscribes to the {@link ObservableSource} and calls a {@link Predicate} for each item or a {@link Consumer} with the error + * of the current {@code Observable}, on their original emission threads, until the predicate returns {@code false}. *
*
Scheduler:
*
{@code forEachWhile} does not operate by default on a particular {@link Scheduler}.
*
* * @param onNext - * {@link Predicate} to execute for each item. + * the {@code Predicate} to execute for each item. * @param onError - * {@link Consumer} to execute when an error is emitted. + * the {@code Consumer} to execute when an error is emitted. * @return - * a Disposable that allows disposing of an asynchronous sequence + * a {@link Disposable} that allows disposing the sequence if the current {@code Observable} runs asynchronously * @throws NullPointerException - * if {@code onNext} is null, or - * if {@code onError} is null + * if {@code onNext} or {@code onError} is {@code null} * @see ReactiveX operators documentation: Subscribe */ @CheckReturnValue @@ -9222,25 +9508,24 @@ public final Disposable forEachWhile(@NonNull Predicate onNext, @NonN } /** - * Subscribes to the {@link ObservableSource} and receives notifications for each element and the terminal events until the - * onNext Predicate returns false. + * Subscribes to the {@link ObservableSource} and calls a {@link Predicate} for each item, a {@link Consumer} with the error + * or an {@link Action} upon completion of the current {@code Observable}, on their original emission threads, + * until the predicate returns {@code false}. *
*
Scheduler:
*
{@code forEachWhile} does not operate by default on a particular {@link Scheduler}.
*
* * @param onNext - * {@link Predicate} to execute for each item. + * the {@code Predicate} to execute for each item. * @param onError - * {@link Consumer} to execute when an error is emitted. + * the {@code Consumer} to execute when an error is emitted. * @param onComplete - * {@link Action} to execute when completion is signalled. + * the {@code Action} to execute when completion is signaled. * @return - * a Disposable that allows disposing of an asynchronous sequence + * a {@link Disposable} that allows disposing the sequence if the current {@code Observable} runs asynchronously * @throws NullPointerException - * if {@code onNext} is null, or - * if {@code onError} is null, or - * if {@code onComplete} is null + * if {@code onNext} or {@code onError} or {@code onComplete} is {@code null} * @see ReactiveX operators documentation: Subscribe */ @CheckReturnValue @@ -9258,17 +9543,19 @@ public final Disposable forEachWhile(@NonNull Predicate onNext, @NonN } /** - * Groups the items emitted by an {@code ObservableSource} according to a specified criterion, and emits these - * grouped items as {@link GroupedObservable}s. The emitted {@code GroupedObservableSource} allows only a single - * {@link Observer} during its lifetime and if this {@code Observer} calls dispose() before the - * source terminates, the next emission by the source having the same key will trigger a new - * {@code GroupedObservableSource} emission. + * Groups the items emitted by the current {@code Observable} according to a specified criterion, and emits these + * grouped items as {@link GroupedObservable}s. *

* *

- * Note: A {@link GroupedObservable} will cache the items it is to emit until such time as it + * Each emitted {@code GroupedObservable} allows only a single {@link Observer} to subscribe to it during its + * lifetime and if this {@code Observer} calls {@code dispose()} before the + * source terminates, the next emission by the source having the same key will trigger a new + * {@code GroupedObservable} emission. + *

+ * Note: A {@code GroupedObservable} will cache the items it is to emit until such time as it * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those - * {@code GroupedObservableSource}s that do not concern you. Instead, you can signal to them that they may + * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may * discard their buffers by applying an operator like {@link #ignoreElements} to them. *

* Note also that ignoring groups or subscribing later (i.e., on another thread) will result in @@ -9285,9 +9572,10 @@ public final Disposable forEachWhile(@NonNull Predicate onNext, @NonN * a function that extracts the key for each item * @param * the key type - * @return an {@code ObservableSource} that emits {@link GroupedObservable}s, each of which corresponds to a - * unique key value and each of which emits those items from the source ObservableSource that share that + * @return an {@code Observable} that emits {@code GroupedObservable}s, each of which corresponds to a + * unique key value and each of which emits those items from the current {@code Observable} that share that * key value + * @throws NullPointerException if {@code keySelector} is {@code null} * @see ReactiveX operators documentation: GroupBy */ @SuppressWarnings({ "unchecked", "rawtypes" }) @@ -9299,17 +9587,19 @@ public final Observable> groupBy(@NonNull Function * *

- * Note: A {@link GroupedObservable} will cache the items it is to emit until such time as it + * Each emitted {@code GroupedObservable} allows only a single {@link Observer} to subscribe to it during its + * lifetime and if this {@code Observer} calls {@code dispose()} before the + * source terminates, the next emission by the source having the same key will trigger a new + * {@code GroupedObservable} emission. + *

+ * Note: A {@code GroupedObservable} will cache the items it is to emit until such time as it * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those - * {@code GroupedObservableSource}s that do not concern you. Instead, you can signal to them that they may + * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may * discard their buffers by applying an operator like {@link #ignoreElements} to them. *

* Note also that ignoring groups or subscribing later (i.e., on another thread) will result in @@ -9327,11 +9617,12 @@ public final Observable> groupBy(@NonNull Function * the key type * @param delayError - * if true, the exception from the current Observable is delayed in each group until that specific group emitted - * the normal values; if false, the exception bypasses values in the groups and is reported immediately. - * @return an {@code ObservableSource} that emits {@link GroupedObservable}s, each of which corresponds to a - * unique key value and each of which emits those items from the source ObservableSource that share that + * if {@code true}, the exception from the current {@code Observable} is delayed in each group until that specific group emitted + * the normal values; if {@code false}, the exception bypasses values in the groups and is reported immediately. + * @return an {@code Observable} that emits {@code GroupedObservable}s, each of which corresponds to a + * unique key value and each of which emits those items from the current {@code Observable} that share that * key value + * @throws NullPointerException if {@code keySelector} is {@code null} * @see ReactiveX operators documentation: GroupBy */ @SuppressWarnings({ "unchecked", "rawtypes" }) @@ -9343,17 +9634,19 @@ public final Observable> groupBy(@NonNull Function * *

- * Note: A {@link GroupedObservable} will cache the items it is to emit until such time as it + * Each emitted {@code GroupedObservable} allows only a single {@link Observer} to subscribe to it during its + * lifetime and if this {@code Observer} calls {@code dispose()} before the + * source terminates, the next emission by the source having the same key will trigger a new + * {@code GroupedObservable} emission. + *

+ * Note: A {@code GroupedObservable} will cache the items it is to emit until such time as it * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those - * {@code GroupedObservableSource}s that do not concern you. Instead, you can signal to them that they may + * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may * discard their buffers by applying an operator like {@link #ignoreElements} to them. *

* Note also that ignoring groups or subscribing later (i.e., on another thread) will result in @@ -9374,9 +9667,10 @@ public final Observable> groupBy(@NonNull Function * the element type - * @return an {@code ObservableSource} that emits {@link GroupedObservable}s, each of which corresponds to a - * unique key value and each of which emits those items from the source ObservableSource that share that + * @return an {@code Observable} that emits {@code GroupedObservable}s, each of which corresponds to a + * unique key value and each of which emits those items from the current {@code Observable} that share that * key value + * @throws NullPointerException if {@code keySelector} or {@code valueSelector} is {@code null} * @see ReactiveX operators documentation: GroupBy */ @CheckReturnValue @@ -9388,17 +9682,19 @@ public final Observable> groupBy(@NonNull Functio } /** - * Groups the items emitted by an {@code ObservableSource} according to a specified criterion, and emits these - * grouped items as {@link GroupedObservable}s. The emitted {@code GroupedObservableSource} allows only a single - * {@link Observer} during its lifetime and if this {@code Observer} calls dispose() before the - * source terminates, the next emission by the source having the same key will trigger a new - * {@code GroupedObservableSource} emission. + * Groups the items emitted by the current {@code Observable} according to a specified criterion, and emits these + * grouped items as {@link GroupedObservable}s. *

* *

- * Note: A {@link GroupedObservable} will cache the items it is to emit until such time as it + * Each emitted {@code GroupedObservable} allows only a single {@link Observer} to subscribe to it during its + * lifetime and if this {@code Observer} calls {@code dispose()} before the + * source terminates, the next emission by the source having the same key will trigger a new + * {@code GroupedObservable} emission. + *

+ * Note: A {@code GroupedObservable} will cache the items it is to emit until such time as it * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those - * {@code GroupedObservableSource}s that do not concern you. Instead, you can signal to them that they may + * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may * discard their buffers by applying an operator like {@link #ignoreElements} to them. *

* Note also that ignoring groups or subscribing later (i.e., on another thread) will result in @@ -9420,10 +9716,10 @@ public final Observable> groupBy(@NonNull Functio * @param * the element type * @param delayError - * if true, the exception from the current Observable is delayed in each group until that specific group emitted - * the normal values; if false, the exception bypasses values in the groups and is reported immediately. - * @return an {@code ObservableSource} that emits {@link GroupedObservable}s, each of which corresponds to a - * unique key value and each of which emits those items from the source ObservableSource that share that + * if {@code true}, the exception from the current {@code Observable} is delayed in each group until that specific group emitted + * the normal values; if {@code false}, the exception bypasses values in the groups and is reported immediately. + * @return an {@code Observable} that emits {@code GroupedObservable}s, each of which corresponds to a + * unique key value and each of which emits those items from the current {@code Observable} that share that * key value * @see ReactiveX operators documentation: GroupBy */ @@ -9436,17 +9732,19 @@ public final Observable> groupBy(@NonNull Functio } /** - * Groups the items emitted by an {@code ObservableSource} according to a specified criterion, and emits these - * grouped items as {@link GroupedObservable}s. The emitted {@code GroupedObservableSource} allows only a single - * {@link Observer} during its lifetime and if this {@code Observer} calls dispose() before the - * source terminates, the next emission by the source having the same key will trigger a new - * {@code GroupedObservableSource} emission. + * Groups the items emitted by the current {@code Observable} according to a specified criterion, and emits these + * grouped items as {@link GroupedObservable}s. *

* *

- * Note: A {@link GroupedObservable} will cache the items it is to emit until such time as it + * Each emitted {@code GroupedObservable} allows only a single {@link Observer} to subscribe to it during its + * lifetime and if this {@code Observer} calls {@code dispose()} before the + * source terminates, the next emission by the source having the same key will trigger a new + * {@code GroupedObservable} emission. + *

+ * Note: A {@code GroupedObservable} will cache the items it is to emit until such time as it * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those - * {@code GroupedObservableSource}s that do not concern you. Instead, you can signal to them that they may + * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may * discard their buffers by applying an operator like {@link #ignoreElements} to them. *

* Note also that ignoring groups or subscribing later (i.e., on another thread) will result in @@ -9464,17 +9762,19 @@ public final Observable> groupBy(@NonNull Functio * @param valueSelector * a function that extracts the return element for each item * @param delayError - * if true, the exception from the current Observable is delayed in each group until that specific group emitted - * the normal values; if false, the exception bypasses values in the groups and is reported immediately. + * if {@code true}, the exception from the current {@code Observable} is delayed in each group until that specific group emitted + * the normal values; if {@code false}, the exception bypasses values in the groups and is reported immediately. * @param bufferSize - * the hint for how many {@link GroupedObservable}s and element in each {@link GroupedObservable} should be buffered + * the hint for how many {@code GroupedObservable}s and element in each {@code GroupedObservable} should be buffered * @param * the key type * @param * the element type - * @return an {@code ObservableSource} that emits {@link GroupedObservable}s, each of which corresponds to a - * unique key value and each of which emits those items from the source ObservableSource that share that + * @return an {@code Observable} that emits {@code GroupedObservable}s, each of which corresponds to a + * unique key value and each of which emits those items from the current {@code Observable} that share that * key value + * @throws NullPointerException if {@code keySelector} or {@code valueSelector} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: GroupBy */ @CheckReturnValue @@ -9491,10 +9791,10 @@ public final Observable> groupBy(@NonNull Functio } /** - * Returns an Observable that correlates two ObservableSources when they overlap in time and groups the results. + * Returns an {@code Observable} that correlates two {@link ObservableSource}s when they overlap in time and groups the results. *

* There are no guarantees in what order the items get combined when multiple - * items from one or both source ObservableSources overlap. + * items from one or both source {@code ObservableSource}s overlap. *

* *

@@ -9502,23 +9802,24 @@ public final Observable> groupBy(@NonNull Functio *
{@code groupJoin} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the value type of the right ObservableSource source - * @param the element type of the left duration ObservableSources - * @param the element type of the right duration ObservableSources + * @param the value type of the right {@code ObservableSource} source + * @param the element type of the left duration {@code ObservableSource}s + * @param the element type of the right duration {@code ObservableSource}s * @param the result type * @param other - * the other ObservableSource to correlate items from the source ObservableSource with + * the other {@code ObservableSource} to correlate items from the current {@code Observable} with * @param leftEnd - * a function that returns an ObservableSource whose emissions indicate the duration of the values of - * the source ObservableSource + * a function that returns an {@code ObservableSource} whose emissions indicate the duration of the values of + * the current {@code Observable} * @param rightEnd - * a function that returns an ObservableSource whose emissions indicate the duration of the values of - * the {@code right} ObservableSource + * a function that returns an {@code ObservableSource} whose emissions indicate the duration of the values of + * the {@code right} {@code ObservableSource} * @param resultSelector - * a function that takes an item emitted by each ObservableSource and returns the value to be emitted - * by the resulting ObservableSource - * @return an Observable that emits items based on combining those items emitted by the source ObservableSources + * a function that takes an item emitted by each {@code ObservableSource} and returns the value to be emitted + * by the resulting {@code Observable} + * @return an {@code Observable} that emits items based on combining those items emitted by the current {@code Observable}s * whose durations overlap + * @throws NullPointerException if {@code other}, {@code leftEnd}, {@code rightEnd} or {@code resultSelector} is {@code null} * @see ReactiveX operators documentation: Join */ @CheckReturnValue @@ -9539,8 +9840,9 @@ public final Observable groupJoin( } /** - * Hides the identity of this Observable and its Disposable. - *

Allows hiding extra features such as {@link io.reactivex.rxjava3.subjects.Subject}'s + * Hides the identity of the current {@code Observable} and its {@link Disposable}. + *

+ * Allows hiding extra features such as {@link io.reactivex.rxjava3.subjects.Subject}'s * {@link Observer} methods or preventing certain identity-based * optimizations (fusion). *

@@ -9549,7 +9851,7 @@ public final Observable groupJoin( *

Scheduler:
*
{@code hide} does not operate by default on a particular {@link Scheduler}.
*
- * @return the new Observable instance + * @return the new {@code Observable} instance * * @since 2.0 */ @@ -9561,7 +9863,7 @@ public final Observable hide() { } /** - * Ignores all items emitted by the source ObservableSource and only calls {@code onComplete} or {@code onError}. + * Ignores all items emitted by the current {@code Observable} and only calls {@code onComplete} or {@code onError}. *

* *

@@ -9569,7 +9871,7 @@ public final Observable hide() { *
{@code ignoreElements} does not operate by default on a particular {@link Scheduler}.
*
* - * @return the new Completable instance + * @return the new {@link Completable} instance * @see ReactiveX operators documentation: IgnoreElements */ @CheckReturnValue @@ -9580,9 +9882,9 @@ public final Completable ignoreElements() { } /** - * Returns a Single that emits {@code true} if the source ObservableSource is empty, otherwise {@code false}. + * Returns a {@link Single} that emits {@code true} if the current {@code Observable} is empty, otherwise {@code false}. *

- * In Rx.Net this is negated as the {@code any} Observer but we renamed this in RxJava to better match Java + * In Rx.Net this is negated as the {@code any} {@link Observer} but we renamed this in RxJava to better match Java * naming idioms. *

* @@ -9591,7 +9893,7 @@ public final Completable ignoreElements() { *

{@code isEmpty} does not operate by default on a particular {@link Scheduler}.
*
* - * @return a Single that emits a Boolean + * @return a {@code Single} that emits a {@link Boolean} * @see ReactiveX operators documentation: Contains */ @CheckReturnValue @@ -9602,10 +9904,10 @@ public final Single isEmpty() { } /** - * Correlates the items emitted by two ObservableSources based on overlapping durations. + * Correlates the items emitted by two {@link ObservableSource}s based on overlapping durations. *

* There are no guarantees in what order the items get combined when multiple - * items from one or both source ObservableSources overlap. + * items from one or both source {@code ObservableSource}s overlap. *

* *

@@ -9613,23 +9915,24 @@ public final Single isEmpty() { *
{@code join} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the value type of the right ObservableSource source - * @param the element type of the left duration ObservableSources - * @param the element type of the right duration ObservableSources + * @param the value type of the right {@code ObservableSource} source + * @param the element type of the left duration {@code ObservableSource}s + * @param the element type of the right duration {@code ObservableSource}s * @param the result type * @param other - * the second ObservableSource to join items from + * the second {@code ObservableSource} to join items from * @param leftEnd - * a function to select a duration for each item emitted by the source ObservableSource, used to + * a function to select a duration for each item emitted by the current {@code Observable}, used to * determine overlap * @param rightEnd - * a function to select a duration for each item emitted by the {@code right} ObservableSource, used to + * a function to select a duration for each item emitted by the {@code right} {@code ObservableSource}, used to * determine overlap * @param resultSelector - * a function that computes an item to be emitted by the resulting ObservableSource for any two - * overlapping items emitted by the two ObservableSources - * @return an Observable that emits items correlating to items emitted by the source ObservableSources that have + * a function that computes an item to be emitted by the resulting {@code Observable} for any two + * overlapping items emitted by the two {@code ObservableSource}s + * @return an {@code Observable} that emits items correlating to items emitted by the current {@code Observable}s that have * overlapping durations + * @throws NullPointerException if {@code other}, {@code leftEnd}, {@code rightEnd} or {@code resultSelector} is {@code null} * @see ReactiveX operators documentation: Join */ @CheckReturnValue @@ -9650,8 +9953,8 @@ public final Observable join( } /** - * Returns a Maybe that emits the last item emitted by this Observable or - * completes if this Observable is empty. + * Returns a {@link Maybe} that emits the last item emitted by the current {@code Observable} or + * completes if the current {@code Observable} is empty. *

* *

@@ -9659,7 +9962,7 @@ public final Observable join( *
{@code lastElement} does not operate by default on a particular {@link Scheduler}.
*
* - * @return a Maybe that emits the last item from the source ObservableSource or notifies observers of an + * @return a {@code Maybe} that emits the last item from the current {@code Observable} or notifies observers of an * error * @see ReactiveX operators documentation: Last */ @@ -9671,8 +9974,8 @@ public final Maybe lastElement() { } /** - * Returns a Single that emits only the last item emitted by this Observable, or a default item - * if this Observable completes without emitting any items. + * Returns a {@link Single} that emits only the last item emitted by the current {@code Observable}, or a default item + * if the current {@code Observable} completes without emitting any items. *

* *

@@ -9681,9 +9984,10 @@ public final Maybe lastElement() { *
* * @param defaultItem - * the default item to emit if the source ObservableSource is empty - * @return a Single that emits only the last item emitted by the source ObservableSource, or a default item - * if the source ObservableSource is empty + * the default item to emit if the current {@code Observable} is empty + * @return a {@code Single} that emits only the last item emitted by the current {@code Observable}, or a default item + * if the current {@code Observable} is empty + * @throws NullPointerException if {@code defaultItem} is {@code null} * @see ReactiveX operators documentation: Last */ @CheckReturnValue @@ -9695,8 +9999,8 @@ public final Single last(@NonNull T defaultItem) { } /** - * Returns a Single that emits only the last item emitted by this Observable or - * signals a {@link NoSuchElementException} if this Observable is empty. + * Returns a {@link Single} that emits only the last item emitted by the current {@code Observable} or + * signals a {@link NoSuchElementException} if the current {@code Observable} is empty. *

* *

@@ -9704,8 +10008,8 @@ public final Single last(@NonNull T defaultItem) { *
{@code lastOrError} does not operate by default on a particular {@link Scheduler}.
*
* - * @return a Single that emits only the last item emitted by the source ObservableSource. - * If the source ObservableSource completes without emitting any items a {@link NoSuchElementException} will be thrown. + * @return a {@code Single} that emits only the last item emitted by the current {@code Observable}. + * If the current {@code Observable} completes without emitting any items a {@code NoSuchElementException} will be thrown. * @see ReactiveX operators documentation: Last */ @CheckReturnValue @@ -9720,7 +10024,7 @@ public final Single lastOrError() { * other standard composition methods first; * Returns an {@code Observable} which, when subscribed to, invokes the {@link ObservableOperator#apply(Observer) apply(Observer)} method * of the provided {@link ObservableOperator} for each individual downstream {@link Observer} and allows the - * insertion of a custom operator by accessing the downstream's {@link Observer} during this subscription phase + * insertion of a custom operator by accessing the downstream's {@code Observer} during this subscription phase * and providing a new {@code Observer}, containing the custom operator's intended business logic, that will be * used in the subscription process going further upstream. *

@@ -9837,23 +10141,24 @@ public final Single lastOrError() { * class and creating an {@link ObservableTransformer} with it is recommended. *

* Note also that it is not possible to stop the subscription phase in {@code lift()} as the {@code apply()} method - * requires a non-null {@code Observer} instance to be returned, which is then unconditionally subscribed to - * the upstream {@code Observable}. For example, if the operator decided there is no reason to subscribe to the + * requires a non-{@code null} {@code Observer} instance to be returned, which is then unconditionally subscribed to + * the current {@code Observable}. For example, if the operator decided there is no reason to subscribe to the * upstream source because of some optimization possibility or a failure to prepare the operator, it still has to - * return an {@code Observer} that should immediately dispose the upstream's {@code Disposable} in its + * return an {@code Observer} that should immediately dispose the upstream's {@link Disposable} in its * {@code onSubscribe} method. Again, using an {@code ObservableTransformer} and extending the {@code Observable} is * a better option as {@link #subscribeActual} can decide to not subscribe to its upstream after all. *

*
Scheduler:
*
{@code lift} does not operate by default on a particular {@link Scheduler}, however, the - * {@link ObservableOperator} may use a {@code Scheduler} to support its own asynchronous behavior.
+ * {@code ObservableOperator} may use a {@code Scheduler} to support its own asynchronous behavior. *
* * @param the output value type - * @param lifter the {@link ObservableOperator} that receives the downstream's {@code Observer} and should return + * @param lifter the {@code ObservableOperator} that receives the downstream's {@code Observer} and should return * an {@code Observer} with custom behavior to be used as the consumer for the current * {@code Observable}. - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code lifter} is {@code null} * @see RxJava wiki: Writing operators * @see #compose(ObservableTransformer) */ @@ -9866,7 +10171,7 @@ public final Observable lift(@NonNull ObservableOperator * @@ -9877,9 +10182,10 @@ public final Observable lift(@NonNull ObservableOperator the output type * @param mapper - * a function to apply to each item emitted by the ObservableSource - * @return an Observable that emits the items from the source ObservableSource, transformed by the specified + * a function to apply to each item emitted by the current {@code Observable} + * @return an {@code Observable} that emits the items from the current {@code Observable}, transformed by the specified * function + * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: Map */ @CheckReturnValue @@ -9891,8 +10197,8 @@ public final Observable map(@NonNull Function map } /** - * Returns an Observable that represents all of the emissions and notifications from the source - * ObservableSource into emissions marked with their original types within {@link Notification} objects. + * Returns an {@code Observable} that represents all of the emissions and notifications from the current + * {@code Observable} into emissions marked with their original types within {@link Notification} objects. *

* *

@@ -9900,8 +10206,8 @@ public final Observable map(@NonNull Function map *
{@code materialize} does not operate by default on a particular {@link Scheduler}.
*
* - * @return an Observable that emits items that are the result of materializing the items and notifications - * of the source ObservableSource + * @return an {@code Observable} that emits items that are the result of materializing the items and notifications + * of the current {@code Observable} * @see ReactiveX operators documentation: Materialize * @see #dematerialize(Function) */ @@ -9913,11 +10219,11 @@ public final Observable> materialize() { } /** - * Flattens this and another ObservableSource into a single ObservableSource, without any transformation. + * Flattens the current {@code Observable} and another {@link ObservableSource} into a single {@code Observable} sequence, without any transformation. *

* *

- * You can combine items emitted by multiple ObservableSources so that they appear as a single ObservableSource, by + * You can combine items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by * using the {@code mergeWith} method. *

*
Scheduler:
@@ -9925,8 +10231,9 @@ public final Observable> materialize() { *
* * @param other - * an ObservableSource to be merged - * @return an Observable that emits all of the items emitted by the source ObservableSources + * an {@code ObservableSource} to be merged + * @return an {@code Observable} that emits all of the items emitted by the current {@code Observable}s + * @throws NullPointerException if {@code other} is {@code null} * @see ReactiveX operators documentation: Merge */ @CheckReturnValue @@ -9938,11 +10245,11 @@ public final Observable mergeWith(@NonNull ObservableSource othe } /** - * Merges the sequence of items of this Observable with the success value of the other SingleSource. + * Merges the sequence of items of the current {@code Observable} with the success value of the other {@link SingleSource}. *

* *

- * The success value of the other {@code SingleSource} can get interleaved at any point of this + * The success value of the other {@code SingleSource} can get interleaved at any point of the current * {@code Observable} sequence. *

*
Scheduler:
@@ -9950,7 +10257,8 @@ public final Observable mergeWith(@NonNull ObservableSource othe *
*

History: 2.1.10 - experimental * @param other the {@code SingleSource} whose success value to merge with - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code other} is {@code null} * @since 2.2 */ @CheckReturnValue @@ -9962,12 +10270,12 @@ public final Observable mergeWith(@NonNull SingleSource other) { } /** - * Merges the sequence of items of this Observable with the success value of the other MaybeSource - * or waits both to complete normally if the MaybeSource is empty. + * Merges the sequence of items of the current {@code Observable} with the success value of the other {@link MaybeSource} + * or waits both to complete normally if the {@code MaybeSource} is empty. *

* *

- * The success value of the other {@code MaybeSource} can get interleaved at any point of this + * The success value of the other {@code MaybeSource} can get interleaved at any point of the current * {@code Observable} sequence. *

*
Scheduler:
@@ -9975,7 +10283,8 @@ public final Observable mergeWith(@NonNull SingleSource other) { *
*

History: 2.1.10 - experimental * @param other the {@code MaybeSource} which provides a success value to merge with or completes - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code other} is {@code null} * @since 2.2 */ @CheckReturnValue @@ -9987,7 +10296,7 @@ public final Observable mergeWith(@NonNull MaybeSource other) { } /** - * Relays the items of this Observable and completes only when the other CompletableSource completes + * Relays the items of the current {@code Observable} and completes only when the other {@link CompletableSource} completes * as well. *

* @@ -9997,7 +10306,8 @@ public final Observable mergeWith(@NonNull MaybeSource other) { *

*

History: 2.1.10 - experimental * @param other the {@code CompletableSource} to await for completion - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code other} is {@code null} * @since 2.2 */ @CheckReturnValue @@ -10009,29 +10319,30 @@ public final Observable mergeWith(@NonNull CompletableSource other) { } /** - * Modifies an ObservableSource to perform its emissions and notifications on a specified {@link Scheduler}, + * Returns an {@code Observable} to perform the current {@code Observable}'s emissions and notifications on a specified {@link Scheduler}, * asynchronously with an unbounded buffer with {@link Flowable#bufferSize()} "island size". * - *

Note that onError notifications will cut ahead of onNext notifications on the emission thread if Scheduler is truly + *

Note that {@code onError} notifications will cut ahead of {@code onNext} notifications on the emission thread if {@code Scheduler} is truly * asynchronous. If strict event ordering is required, consider using the {@link #observeOn(Scheduler, boolean)} overload. *

* *

- * This operator keeps emitting as many signals as it can on the given Scheduler's Worker thread, + * This operator keeps emitting as many signals as it can on the given {@code Scheduler}'s worker thread, * which may result in a longer than expected occupation of this thread. In other terms, * it does not allow per-signal fairness in case the worker runs on a shared underlying thread. * If such fairness and signal/work interleaving is preferred, use the delay operator with zero time instead. *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
*

"Island size" indicates how large chunks the unbounded buffer allocates to store the excess elements waiting to be consumed * on the other side of the asynchronous boundary. * * @param scheduler - * the {@link Scheduler} to notify {@link Observer}s on - * @return the source ObservableSource modified so that its {@link Observer}s are notified on the specified - * {@link Scheduler} + * the {@code Scheduler} to notify {@link Observer}s on + * @return the current {@code Observable} modified so that its {@code Observer}s are notified on the specified + * {@code Scheduler} + * @throws NullPointerException if {@code scheduler} is {@code null} * @see ReactiveX operators documentation: ObserveOn * @see RxJava Threading Examples * @see #subscribeOn @@ -10047,30 +10358,30 @@ public final Observable observeOn(@NonNull Scheduler scheduler) { } /** - * Modifies an ObservableSource to perform its emissions and notifications on a specified {@link Scheduler}, - * asynchronously with an unbounded buffer with {@link Flowable#bufferSize()} "island size" and optionally delays onError notifications. + * Returns an {@code Observable} to perform the current {@code Observable}'s emissions and notifications on a specified {@link Scheduler}, + * asynchronously with an unbounded buffer with {@link Flowable#bufferSize()} "island size" and optionally delays {@code onError} notifications. *

* *

- * This operator keeps emitting as many signals as it can on the given Scheduler's Worker thread, + * This operator keeps emitting as many signals as it can on the given {@code Scheduler}'s worker thread, * which may result in a longer than expected occupation of this thread. In other terms, * it does not allow per-signal fairness in case the worker runs on a shared underlying thread. * If such fairness and signal/work interleaving is preferred, use the delay operator with zero time instead. *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
*

"Island size" indicates how large chunks the unbounded buffer allocates to store the excess elements waiting to be consumed * on the other side of the asynchronous boundary. * * @param scheduler - * the {@link Scheduler} to notify {@link Observer}s on + * the {@code Scheduler} to notify {@link Observer}s on * @param delayError - * indicates if the onError notification may not cut ahead of onNext notification on the other side of the - * scheduling boundary. If true a sequence ending in onError will be replayed in the same order as was received - * from upstream - * @return the source ObservableSource modified so that its {@link Observer}s are notified on the specified - * {@link Scheduler} + * indicates if the {@code onError} notification may not cut ahead of {@code onNext} notification on the other side of the + * scheduling boundary. If {@code true}, a sequence ending in {@code onError} will be replayed in the same order as was received + * from the current {@code Observable} + * @return the current {@code Observable} modified so that its {@code Observer}s are notified on the specified + * {@code Scheduler} * @see ReactiveX operators documentation: ObserveOn * @see RxJava Threading Examples * @see #subscribeOn @@ -10086,31 +10397,33 @@ public final Observable observeOn(@NonNull Scheduler scheduler, boolean delay } /** - * Modifies an ObservableSource to perform its emissions and notifications on a specified {@link Scheduler}, - * asynchronously with an unbounded buffer of configurable "island size" and optionally delays onError notifications. + * Returns an {@code Observable} to perform the current {@code Observable}'s emissions and notifications on a specified {@link Scheduler}, + * asynchronously with an unbounded buffer of configurable "island size" and optionally delays {@code onError} notifications. *

* *

- * This operator keeps emitting as many signals as it can on the given Scheduler's Worker thread, + * This operator keeps emitting as many signals as it can on the given {@code Scheduler}'s worker thread, * which may result in a longer than expected occupation of this thread. In other terms, * it does not allow per-signal fairness in case the worker runs on a shared underlying thread. * If such fairness and signal/work interleaving is preferred, use the delay operator with zero time instead. *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
*

"Island size" indicates how large chunks the unbounded buffer allocates to store the excess elements waiting to be consumed * on the other side of the asynchronous boundary. Values below 16 are not recommended in performance sensitive scenarios. * * @param scheduler - * the {@link Scheduler} to notify {@link Observer}s on + * the {@code Scheduler} to notify {@link Observer}s on * @param delayError - * indicates if the onError notification may not cut ahead of onNext notification on the other side of the - * scheduling boundary. If true a sequence ending in onError will be replayed in the same order as was received + * indicates if the {@code onError} notification may not cut ahead of {@code onNext} notification on the other side of the + * scheduling boundary. If {@code true} a sequence ending in {@code onError} will be replayed in the same order as was received * from upstream * @param bufferSize the size of the buffer. - * @return the source ObservableSource modified so that its {@link Observer}s are notified on the specified - * {@link Scheduler} + * @return the current {@code Observable} modified so that its {@code Observer}s are notified on the specified + * {@code Scheduler} + * @throws NullPointerException if {@code scheduler} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: ObserveOn * @see RxJava Threading Examples * @see #subscribeOn @@ -10128,7 +10441,7 @@ public final Observable observeOn(@NonNull Scheduler scheduler, boolean delay } /** - * Filters the items emitted by an ObservableSource, only emitting those of the specified type. + * Filters the items emitted by the current {@code Observable}, only emitting those of the specified type. *

* *

@@ -10138,8 +10451,9 @@ public final Observable observeOn(@NonNull Scheduler scheduler, boolean delay * * @param the output type * @param clazz - * the class type to filter the items emitted by the source ObservableSource - * @return an Observable that emits items from the source ObservableSource of type {@code clazz} + * the class type to filter the items emitted by the current {@code Observable} + * @return an {@code Observable} that emits items from the current {@code Observable} of type {@code clazz} + * @throws NullPointerException if {@code clazz} is {@code null} * @see ReactiveX operators documentation: Filter */ @CheckReturnValue @@ -10151,19 +10465,19 @@ public final Observable ofType(@NonNull Class clazz) { } /** - * Instructs an ObservableSource to pass control to another ObservableSource rather than invoking + * Instructs the current {@code Observable} to pass control to another {@link ObservableSource} rather than invoking * {@link Observer#onError onError} if it encounters an error. *

* *

- * By default, when an ObservableSource encounters an error that prevents it from emitting the expected item to - * its {@link Observer}, the ObservableSource invokes its Observer's {@code onError} method, and then quits - * without invoking any more of its Observer's methods. The {@code onErrorResumeNext} method changes this - * behavior. If you pass a function that returns an ObservableSource ({@code resumeFunction}) to - * {@code onErrorResumeNext}, if the original ObservableSource encounters an error, instead of invoking its - * Observer's {@code onError} method, it will instead relinquish control to the ObservableSource returned from - * {@code resumeFunction}, which will invoke the Observer's {@link Observer#onNext onNext} method if it is - * able to do so. In such a case, because no ObservableSource necessarily invokes {@code onError}, the Observer + * By default, when an {@code ObservableSource} encounters an error that prevents it from emitting the expected item to + * its {@link Observer}, the {@code ObservableSource} invokes its {@code Observer}'s {@code onError} method, and then quits + * without invoking any more of its {@code Observer}'s methods. The {@code onErrorResumeNext} method changes this + * behavior. If you pass a function that returns an {@code ObservableSource} ({@code resumeFunction}) to + * {@code onErrorResumeNext}, if the original {@code ObservableSource} encounters an error, instead of invoking its + * {@code Observer}'s {@code onError} method, it will instead relinquish control to the {@code ObservableSource} returned from + * {@code resumeFunction}, which will invoke the {@code Observer}'s {@link Observer#onNext onNext} method if it is + * able to do so. In such a case, because no {@code ObservableSource} necessarily invokes {@code onError}, the {@code Observer} * may never know that an error happened. *

* You can use this to prevent errors from propagating or to supply fallback data should errors be @@ -10174,9 +10488,10 @@ public final Observable ofType(@NonNull Class clazz) { *

* * @param resumeFunction - * a function that returns an ObservableSource that will take over if the source ObservableSource encounters + * a function that returns an {@code ObservableSource} that will take over if the current {@code Observable} encounters * an error - * @return the original ObservableSource, with appropriately modified behavior + * @return the original {@code ObservableSource}, with appropriately modified behavior + * @throws NullPointerException if {@code resumeFunction} is {@code null} * @see ReactiveX operators documentation: Catch */ @CheckReturnValue @@ -10188,19 +10503,19 @@ public final Observable onErrorResumeNext(@NonNull Function * *

- * By default, when an ObservableSource encounters an error that prevents it from emitting the expected item to - * its {@link Observer}, the ObservableSource invokes its Observer's {@code onError} method, and then quits - * without invoking any more of its Observer's methods. The {@code onErrorResumeWith} method changes this - * behavior. If you pass another ObservableSource ({@code next}) to an ObservableSource's - * {@code onErrorResumeWith} method, if the original ObservableSource encounters an error, instead of invoking its - * Observer's {@code onError} method, it will instead relinquish control to {@code next} which - * will invoke the Observer's {@link Observer#onNext onNext} method if it is able to do so. In such a case, - * because no ObservableSource necessarily invokes {@code onError}, the Observer may never know that an error + * By default, when an {@code ObservableSource} encounters an error that prevents it from emitting the expected item to + * its {@link Observer}, the {@code ObservableSource} invokes its {@code Observer}'s {@code onError} method, and then quits + * without invoking any more of its {@code Observer}'s methods. The {@code onErrorResumeWith} method changes this + * behavior. If you pass another {@code ObservableSource} ({@code next}) to an {@code ObservableSource}'s + * {@code onErrorResumeWith} method, if the original {@code ObservableSource} encounters an error, instead of invoking its + * {@code Observer}'s {@code onError} method, it will instead relinquish control to {@code next} which + * will invoke the {@code Observer}'s {@link Observer#onNext onNext} method if it is able to do so. In such a case, + * because no {@code ObservableSource} necessarily invokes {@code onError}, the {@code Observer} may never know that an error * happened. *

* You can use this to prevent errors from propagating or to supply fallback data should errors be @@ -10211,9 +10526,10 @@ public final Observable onErrorResumeNext(@NonNull Function * * @param next - * the next ObservableSource source that will take over if the source ObservableSource encounters + * the next {@code ObservableSource} source that will take over if the current {@code Observable} encounters * an error - * @return the original ObservableSource, with appropriately modified behavior + * @return the original {@code ObservableSource}, with appropriately modified behavior + * @throws NullPointerException if {@code next} is {@code null} * @see ReactiveX operators documentation: Catch */ @CheckReturnValue @@ -10225,16 +10541,16 @@ public final Observable onErrorResumeWith(@NonNull ObservableSource * *

- * By default, when an ObservableSource encounters an error that prevents it from emitting the expected item to - * its {@link Observer}, the ObservableSource invokes its Observer's {@code onError} method, and then quits - * without invoking any more of its Observer's methods. The {@code onErrorReturn} method changes this - * behavior. If you pass a function ({@code resumeFunction}) to an ObservableSource's {@code onErrorReturn} - * method, if the original ObservableSource encounters an error, instead of invoking its Observer's + * By default, when an {@link ObservableSource} encounters an error that prevents it from emitting the expected item to + * its {@link Observer}, the {@code ObservableSource} invokes its {@code Observer}'s {@code onError} method, and then quits + * without invoking any more of its {@code Observer}'s methods. The {@code onErrorReturn} method changes this + * behavior. If you pass a function ({@code resumeFunction}) to an {@code ObservableSource}'s {@code onErrorReturn} + * method, if the original {@code ObservableSource} encounters an error, instead of invoking its {@code Observer}'s * {@code onError} method, it will instead emit the return value of {@code resumeFunction}. *

* You can use this to prevent errors from propagating or to supply fallback data should errors be @@ -10245,9 +10561,10 @@ public final Observable onErrorResumeWith(@NonNull ObservableSource * * @param valueSupplier - * a function that returns a single value that will be emitted along with a regular onComplete in case - * the current Observable signals an onError event - * @return the original ObservableSource with appropriately modified behavior + * a function that returns a single value that will be emitted along with a regular {@code onComplete} in case + * the current {@code Observable} signals an {@code onError} event + * @return the original {@code ObservableSource} with appropriately modified behavior + * @throws NullPointerException if {@code valueSupplier} is {@code null} * @see ReactiveX operators documentation: Catch */ @CheckReturnValue @@ -10259,16 +10576,16 @@ public final Observable onErrorReturn(@NonNull Function * *

- * By default, when an ObservableSource encounters an error that prevents it from emitting the expected item to - * its {@link Observer}, the ObservableSource invokes its Observer's {@code onError} method, and then quits - * without invoking any more of its Observer's methods. The {@code onErrorReturn} method changes this - * behavior. If you pass a function ({@code resumeFunction}) to an ObservableSource's {@code onErrorReturn} - * method, if the original ObservableSource encounters an error, instead of invoking its Observer's + * By default, when an {@link ObservableSource} encounters an error that prevents it from emitting the expected item to + * its {@link Observer}, the {@code ObservableSource} invokes its {@code Observer}'s {@code onError} method, and then quits + * without invoking any more of its {@code Observer}'s methods. The {@code onErrorReturn} method changes this + * behavior. If you pass a function ({@code resumeFunction}) to an {@code ObservableSource}'s {@code onErrorReturn} + * method, if the original {@code ObservableSource} encounters an error, instead of invoking its {@code Observer}'s * {@code onError} method, it will instead emit the return value of {@code resumeFunction}. *

* You can use this to prevent errors from propagating or to supply fallback data should errors be @@ -10279,9 +10596,10 @@ public final Observable onErrorReturn(@NonNull Function * * @param item - * the value that is emitted along with a regular onComplete in case the current - * Observable signals an exception - * @return the original ObservableSource with appropriately modified behavior + * the value that is emitted along with a regular {@code onComplete} in case the current + * {@code Observable} signals an exception + * @return the original {@code ObservableSource} with appropriately modified behavior + * @throws NullPointerException if {@code item} is {@code null} * @see ReactiveX operators documentation: Catch */ @CheckReturnValue @@ -10293,16 +10611,16 @@ public final Observable onErrorReturnItem(@NonNull T item) { } /** - * Nulls out references to the upstream producer and downstream Observer if - * the sequence is terminated or downstream calls dispose(). + * Nulls out references to the upstream producer and downstream {@link Observer} if + * the sequence is terminated or downstream calls {@code dispose()}. *

* *

*
Scheduler:
*
{@code onTerminateDetach} does not operate by default on a particular {@link Scheduler}.
*
- * @return an Observable which nulls out references to the upstream producer and downstream Observer if - * the sequence is terminated or downstream calls dispose() + * @return an {@code Observable} which {@code null}s out references to the upstream producer and downstream {@code Observer} if + * the sequence is terminated or downstream calls {@code dispose()} * @since 2.0 */ @CheckReturnValue @@ -10313,7 +10631,7 @@ public final Observable onTerminateDetach() { } /** - * Returns a {@link ConnectableObservable}, which is a variety of ObservableSource that waits until its + * Returns a {@link ConnectableObservable}, which is a variety of {@link ObservableSource} that waits until its * {@link ConnectableObservable#connect connect} method is called before it begins emitting items to those * {@link Observer}s that have subscribed to it. *

@@ -10323,8 +10641,8 @@ public final Observable onTerminateDetach() { *

{@code publish} does not operate by default on a particular {@link Scheduler}.
*
* - * @return a {@link ConnectableObservable} that upon connection causes the source ObservableSource to emit items - * to its {@link Observer}s + * @return a {@code ConnectableObservable} that upon connection causes the current {@code Observable} to emit items + * to its {@code Observer}s * @see ReactiveX operators documentation: Publish */ @CheckReturnValue @@ -10335,8 +10653,8 @@ public final ConnectableObservable publish() { } /** - * Returns an Observable that emits the results of invoking a specified selector on items emitted by a - * {@link ConnectableObservable} that shares a single subscription to the underlying sequence. + * Returns an {@code Observable} that emits the results of invoking a specified selector on items emitted by a + * {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} sequence. *

* *

@@ -10345,12 +10663,14 @@ public final ConnectableObservable publish() { *
* * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param selector * a function that can use the multicasted source sequence as many times as needed, without - * causing multiple subscriptions to the source sequence. Observers to the given source will + * causing multiple subscriptions to the source sequence. {@link Observer}s to the given source will * receive all notifications of the source from the time of the subscription forward. - * @return an Observable that emits the results of invoking the selector on the items emitted by a {@link ConnectableObservable} that shares a single subscription to the underlying sequence + * @return an {@code Observable} that emits the results of invoking the selector on the items + * emitted by a {@code ConnectableObservable} that shares a single subscription to the underlying sequence + * @throws NullPointerException if {@code selector} is {@code null} * @see ReactiveX operators documentation: Publish */ @CheckReturnValue @@ -10362,9 +10682,9 @@ public final Observable publish(@NonNull Function, } /** - * Returns a Maybe that applies a specified accumulator function to the first item emitted by a source - * ObservableSource, then feeds the result of that function along with the second item emitted by the source - * ObservableSource into the same function, and so on until all items have been emitted by the finite source ObservableSource, + * Returns a {@link Maybe} that applies a specified accumulator function to the first item emitted by the current + * {@code Observable}, then feeds the result of that function along with the second item emitted by the current + * {@code Observable} into the same function, and so on until all items have been emitted by the current and finite {@code Observable}, * and emits the final result from the final call to your function as its sole item. *

* @@ -10375,17 +10695,18 @@ public final Observable publish(@NonNull Function, *

* Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to * be emitted. Sources that are infinite and never complete will never emit anything through this - * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. + * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}. *

*
Scheduler:
*
{@code reduce} does not operate by default on a particular {@link Scheduler}.
*
* * @param reducer - * an accumulator function to be invoked on each item emitted by the source ObservableSource, whose + * an accumulator function to be invoked on each item emitted by the current {@code Observable}, whose * result will be used in the next accumulator call - * @return a Maybe that emits a single item that is the result of accumulating the items emitted by - * the source ObservableSource + * @return a {@code Maybe} that emits a single item that is the result of accumulating the items emitted by + * the current {@code Observable} + * @throws NullPointerException if {@code reducer} is {@code null} * @see ReactiveX operators documentation: Reduce * @see Wikipedia: Fold (higher-order function) */ @@ -10398,10 +10719,10 @@ public final Maybe reduce(@NonNull BiFunction reducer) { } /** - * Returns a Single that applies a specified accumulator function to the first item emitted by a source - * ObservableSource and a specified seed value, then feeds the result of that function along with the second item - * emitted by an ObservableSource into the same function, and so on until all items have been emitted by the - * finite source ObservableSource, emitting the final result from the final call to your function as its sole item. + * Returns a {@link Single} that applies a specified accumulator function to the first item emitted by the current + * {@code Observable} and a specified seed value, then feeds the result of that function along with the second item + * emitted by the current {@code Observable} into the same function, and so on until all items have been emitted by the + * current and finite {@code Observable}, emitting the final result from the final call to your function as its sole item. *

* *

@@ -10409,7 +10730,7 @@ public final Maybe reduce(@NonNull BiFunction reducer) { * "compress," or "inject" in other programming contexts. Groovy, for instance, has an {@code inject} method * that does a similar operation on lists. *

- * Note that the {@code seed} is shared among all subscribers to the resulting ObservableSource + * Note that the {@code seed} is shared among all subscribers to the resulting {@code Observable} * and may cause problems if it is mutable. To make sure each subscriber gets its own value, defer * the application of this operator via {@link #defer(Supplier)}: * 


@@ -10429,7 +10750,7 @@ public final Maybe reduce(@NonNull BiFunction reducer) {
      * 

      * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to
      * be emitted. Sources that are infinite and never complete will never emit anything through this
-     * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}.
+     * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
      * 

      *  
Scheduler:

      *  
{@code reduce} does not operate by default on a particular {@link Scheduler}.

@@ -10439,10 +10760,11 @@ public final Maybe reduce(@NonNull BiFunction reducer) {
      * @param seed
      *            the initial (seed) accumulator value
      * @param reducer
-     *            an accumulator function to be invoked on each item emitted by the source ObservableSource, the
+     *            an accumulator function to be invoked on each item emitted by the current {@code Observable}, the
      *            result of which will be used in the next accumulator call
-     * @return a Single that emits a single item that is the result of accumulating the output from the
-     *         items emitted by the source ObservableSource
+     * @return a {@code Single} that emits a single item that is the result of accumulating the output from the
+     *         items emitted by the current {@code Observable}
+     * @throws NullPointerException if {@code seed} or {@code reducer} is {@code null}
      * @see ReactiveX operators documentation: Reduce
      * @see Wikipedia: Fold (higher-order function)
      * @see #reduceWith(Supplier, BiFunction)
@@ -10457,10 +10779,10 @@ public final Maybe reduce(@NonNull BiFunction reducer) {
     }
 
     /**
-     * Returns a Single that applies a specified accumulator function to the first item emitted by a source
-     * ObservableSource and a seed value derived from calling a specified seedSupplier, then feeds the result
-     * of that function along with the second item emitted by an ObservableSource into the same function,
-     * and so on until all items have been emitted by the finite source ObservableSource, emitting the final result
+     * Returns a {@link Single} that applies a specified accumulator function to the first item emitted by the current
+     * {@code Observable} and a seed value derived from calling a specified {@code seedSupplier}, then feeds the result
+     * of that function along with the second item emitted by the current {@code Observable} into the same function,
+     * and so on until all items have been emitted by the current and finite {@code Observable}, emitting the final result
      * from the final call to your function as its sole item.
      * 

      * 
@@ -10471,7 +10793,7 @@ public final Maybe reduce(@NonNull BiFunction reducer) {
      * 

      * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to
      * be emitted. Sources that are infinite and never complete will never emit anything through this
-     * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}.
+     * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
      * 

      *  
Scheduler:

      *  
{@code reduceWith} does not operate by default on a particular {@link Scheduler}.

@@ -10479,12 +10801,13 @@ public final Maybe reduce(@NonNull BiFunction reducer) {
      *
      * @param  the accumulator and output value type
      * @param seedSupplier
-     *            the Supplier that provides the initial (seed) accumulator value for each individual Observer
+     *            the {@link Supplier} that provides the initial (seed) accumulator value for each individual {@link Observer}
      * @param reducer
-     *            an accumulator function to be invoked on each item emitted by the source ObservableSource, the
+     *            an accumulator function to be invoked on each item emitted by the current {@code Observable}, the
      *            result of which will be used in the next accumulator call
-     * @return a Single that emits a single item that is the result of accumulating the output from the
-     *         items emitted by the source ObservableSource
+     * @return a {@code Single} that emits a single item that is the result of accumulating the output from the
+     *         items emitted by the current {@code Observable}
+     * @throws NullPointerException if {@code seedSupplier} or {@code reducer} is {@code null}
      * @see ReactiveX operators documentation: Reduce
      * @see Wikipedia: Fold (higher-order function)
      */
@@ -10498,7 +10821,7 @@ public final Maybe reduce(@NonNull BiFunction reducer) {
     }
 
     /**
-     * Returns an Observable that repeats the sequence of items emitted by the source ObservableSource indefinitely.
+     * Returns an {@code Observable} that repeats the sequence of items emitted by the current {@code Observable} indefinitely.
      * 

      * 
      * 

@@ -10506,7 +10829,7 @@ public final Maybe reduce(@NonNull BiFunction reducer) {
      *  
{@code repeat} does not operate by default on a particular {@link Scheduler}.

      * 

      *
-     * @return an Observable that emits the items emitted by the source ObservableSource repeatedly and in sequence
+     * @return an {@code Observable} that emits the items emitted by the current {@code Observable} repeatedly and in sequence
      * @see ReactiveX operators documentation: Repeat
      */
     @CheckReturnValue
@@ -10517,7 +10840,7 @@ public final Observable repeat() {
     }
 
     /**
-     * Returns an Observable that repeats the sequence of items emitted by the source ObservableSource at most
+     * Returns an {@code Observable} that repeats the sequence of items emitted by the current {@code Observable} at most
      * {@code count} times.
      * 

      * 
@@ -10527,12 +10850,12 @@ public final Observable repeat() {
      * 

      *
      * @param times
-     *            the number of times the source ObservableSource items are repeated, a count of 0 will yield an empty
+     *            the number of times the current {@code Observable} items are repeated, a count of 0 will yield an empty
      *            sequence
-     * @return an Observable that repeats the sequence of items emitted by the source ObservableSource at most
+     * @return an {@code Observable} that repeats the sequence of items emitted by the current {@code Observable} at most
      *         {@code count} times
      * @throws IllegalArgumentException
-     *             if {@code count} is less than zero
+     *             if {@code count} is negative
      * @see ReactiveX operators documentation: Repeat
      */
     @CheckReturnValue
@@ -10549,8 +10872,8 @@ public final Observable repeat(long times) {
     }
 
     /**
-     * Returns an Observable that repeats the sequence of items emitted by the source ObservableSource until
-     * the provided stop function returns true.
+     * Returns an {@code Observable} that repeats the sequence of items emitted by the current {@code Observable} until
+     * the provided stop function returns {@code true}.
      * 

      * 
      * 

@@ -10559,12 +10882,12 @@ public final Observable repeat(long times) {
      * 

      *
      * @param stop
-     *                a boolean supplier that is called when the current Observable completes;
-     *                if it returns true, the returned Observable completes; if it returns false,
-     *                the upstream Observable is resubscribed.
-     * @return the new Observable instance
+     *                a boolean supplier that is called when the current {@code Observable} completes;
+     *                if it returns {@code true}, the returned {@code Observable} completes; if it returns {@code false},
+     *                the current {@code Observable} is resubscribed.
+     * @return the new {@code Observable} instance
      * @throws NullPointerException
-     *             if {@code stop} is null
+     *             if {@code stop} is {@code null}
      * @see ReactiveX operators documentation: Repeat
      */
     @CheckReturnValue
@@ -10576,12 +10899,12 @@ public final Observable repeatUntil(@NonNull BooleanSupplier stop) {
     }
 
     /**
-     * Returns an Observable that emits the same values as the source ObservableSource with the exception of an
+     * Returns an {@code Observable} that emits the same values as the current {@code Observable} with the exception of an
      * {@code onComplete}. An {@code onComplete} notification from the source will result in the emission of
-     * a {@code void} item to the ObservableSource provided as an argument to the {@code notificationHandler}
-     * function. If that ObservableSource calls {@code onComplete} or {@code onError} then {@code repeatWhen} will
-     * call {@code onComplete} or {@code onError} on the child subscription. Otherwise, this ObservableSource will
-     * resubscribe to the source ObservableSource.
+     * a {@code void} item to the {@link ObservableSource} provided as an argument to the {@code notificationHandler}
+     * function. If that {@code ObservableSource} calls {@code onComplete} or {@code onError} then {@code repeatWhen} will
+     * call {@code onComplete} or {@code onError} on the child subscription. Otherwise, the current {@code Observable}
+     * will be resubscribed.
      * 

      * 
      * 

@@ -10590,8 +10913,9 @@ public final Observable repeatUntil(@NonNull BooleanSupplier stop) {
      * 

      *
      * @param handler
-     *            receives an ObservableSource of notifications with which a user can complete or error, aborting the repeat.
-     * @return the source ObservableSource modified with repeat logic
+     *            receives an {@code ObservableSource} of notifications with which a user can complete or error, aborting the repeat.
+     * @return the new {@code Observable} instance
+     * @throws NullPointerException if {@code handler} is {@code null}
      * @see ReactiveX operators documentation: Repeat
      */
     @CheckReturnValue
@@ -10603,9 +10927,9 @@ public final Observable repeatWhen(@NonNull Function
      * 
@@ -10614,8 +10938,8 @@ public final Observable repeatWhen(@NonNull FunctionThis version of {@code replay} does not operate by default on a particular {@link Scheduler}.
      * 

      *
-     * @return a {@link ConnectableObservable} that upon connection causes the source ObservableSource to emit its
-     *         items to its {@link Observer}s
+     * @return a {@code ConnectableObservable} that upon connection causes the current {@code Observable} to emit its
+     *         items to its {@code Observer}s
      * @see ReactiveX operators documentation: Replay
      */
     @CheckReturnValue
@@ -10626,8 +10950,8 @@ public final ConnectableObservable replay() {
     }
 
     /**
-     * Returns an Observable that emits items that are the results of invoking a specified selector on the items
-     * emitted by a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource.
+     * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on the items
+     * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable}.
      * 

      * 
      * 

@@ -10636,12 +10960,13 @@ public final ConnectableObservable replay() {
      * 

      *
      * @param 
-     *            the type of items emitted by the resulting ObservableSource
+     *            the type of items emitted by the resulting {@code Observable}
      * @param selector
      *            the selector function, which can use the multicasted sequence as many times as needed, without
-     *            causing multiple subscriptions to the ObservableSource
-     * @return an Observable that emits items that are the results of invoking the selector on a
-     *         {@link ConnectableObservable} that shares a single subscription to the source ObservableSource
+     *            causing multiple subscriptions to the current {@code Observable}
+     * @return an {@code Observable} that emits items that are the results of invoking the selector on a
+     *         {@code ConnectableObservable} that shares a single subscription to the current {@code Observable}
+     * @throws NullPointerException if {@code selector} is {@code null}
      * @see ReactiveX operators documentation: Replay
      */
     @CheckReturnValue
@@ -10653,8 +10978,8 @@ public final  Observable replay(@NonNull Function, ?
     }
 
     /**
-     * Returns an Observable that emits items that are the results of invoking a specified selector on items
-     * emitted by a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource,
+     * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on items
+     * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable},
      * replaying {@code bufferSize} notifications.
      * 

      * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
@@ -10667,15 +10992,17 @@ public final  Observable replay(@NonNull Function, ?
      *
* * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param selector * the selector function, which can use the multicasted sequence as many times as needed, without - * causing multiple subscriptions to the ObservableSource + * causing multiple subscriptions to the current {@code Observable} * @param bufferSize - * the buffer size that limits the number of items the connectable ObservableSource can replay - * @return an Observable that emits items that are the results of invoking the selector on items emitted by - * a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource + * the buffer size that limits the number of items the connectable {@code Observable} can replay + * @return an {@code Observable} that emits items that are the results of invoking the selector on items emitted by + * a {@code ConnectableObservable} that shares a single subscription to the current {@code Observable} * replaying no more than {@code bufferSize} items + * @throws NullPointerException if {@code selector} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Replay * @see #replay(Function, int, boolean) */ @@ -10689,8 +11016,8 @@ public final Observable replay(@NonNull Function, ? } /** - * Returns an Observable that emits items that are the results of invoking a specified selector on items - * emitted by a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource, + * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on items + * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable}, * replaying {@code bufferSize} notifications. *

* Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than @@ -10703,18 +11030,20 @@ public final Observable replay(@NonNull Function, ? *

* * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param selector * the selector function, which can use the multicasted sequence as many times as needed, without - * causing multiple subscriptions to the ObservableSource + * causing multiple subscriptions to the current {@code Observable} * @param bufferSize - * the buffer size that limits the number of items the connectable ObservableSource can replay + * the buffer size that limits the number of items the connectable {@code Observable} can replay * @param eagerTruncate - * if true, whenever the internal buffer is truncated to the given bufferSize, the + * if {@code true}, whenever the internal buffer is truncated to the given bufferSize, the * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention - * @return an Observable that emits items that are the results of invoking the selector on items emitted by - * a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource + * @return an {@code Observable} that emits items that are the results of invoking the selector on items emitted by + * a {@code ConnectableObservable} that shares a single subscription to the current {@code Observable} * replaying no more than {@code bufferSize} items + * @throws NullPointerException if {@code selector} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Replay */ @CheckReturnValue @@ -10727,8 +11056,8 @@ public final Observable replay(@NonNull Function, ? } /** - * Returns an Observable that emits items that are the results of invoking a specified selector on items - * emitted by a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource, + * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on items + * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable}, * replaying no more than {@code bufferSize} items that were emitted within a specified time window. *

* Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than @@ -10741,20 +11070,22 @@ public final Observable replay(@NonNull Function, ? *

* * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param selector * a selector function, which can use the multicasted sequence as many times as needed, without - * causing multiple subscriptions to the ObservableSource + * causing multiple subscriptions to the current {@code Observable} * @param bufferSize - * the buffer size that limits the number of items the connectable ObservableSource can replay + * the buffer size that limits the number of items the connectable {@code Observable} can replay * @param time * the duration of the window in which the replayed items must have been emitted * @param unit * the time unit of {@code time} - * @return an Observable that emits items that are the results of invoking the selector on items emitted by - * a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource, and + * @return an {@code Observable} that emits items that are the results of invoking the selector on items emitted by + * a {@code ConnectableObservable} that shares a single subscription to the current {@code Observable}, and * replays no more than {@code bufferSize} items that were emitted within the window defined by * {@code time} + * @throws NullPointerException if {@code selector} or {@code unit} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Replay */ @CheckReturnValue @@ -10765,8 +11096,8 @@ public final Observable replay(@NonNull Function, ? } /** - * Returns an Observable that emits items that are the results of invoking a specified selector on items - * emitted by a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource, + * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on items + * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable}, * replaying no more than {@code bufferSize} items that were emitted within a specified time window. *

* Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than @@ -10779,24 +11110,26 @@ public final Observable replay(@NonNull Function, ? *

* * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param selector * a selector function, which can use the multicasted sequence as many times as needed, without - * causing multiple subscriptions to the ObservableSource + * causing multiple subscriptions to the current {@code Observable} * @param bufferSize - * the buffer size that limits the number of items the connectable ObservableSource can replay + * the buffer size that limits the number of items the connectable {@code Observable} can replay * @param time * the duration of the window in which the replayed items must have been emitted * @param unit * the time unit of {@code time} * @param scheduler - * the Scheduler that is the time source for the window - * @return an Observable that emits items that are the results of invoking the selector on items emitted by - * a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource, and + * the {@code Scheduler} that is the time source for the window + * @return an {@code Observable} that emits items that are the results of invoking the selector on items emitted by + * a {@code ConnectableObservable} that shares a single subscription to the current {@code Observable}, and * replays no more than {@code bufferSize} items that were emitted within the window defined by * {@code time} * @throws IllegalArgumentException - * if {@code bufferSize} is less than zero + * if {@code bufferSize} is non-positive + * @throws NullPointerException if {@code selector}, {@code unit} or {@code scheduler} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Replay * @see #replay(Function, int, long, TimeUnit, Scheduler, boolean) */ @@ -10811,9 +11144,10 @@ public final Observable replay(@NonNull Function, ? return ObservableReplay.multicastSelector( ObservableInternalHelper.replaySupplier(this, bufferSize, time, unit, scheduler, false), selector); } + /** - * Returns an Observable that emits items that are the results of invoking a specified selector on items - * emitted by a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource, + * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on items + * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable}, * replaying no more than {@code bufferSize} items that were emitted within a specified time window. *

* Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than @@ -10826,27 +11160,28 @@ public final Observable replay(@NonNull Function, ? *

* * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param selector * a selector function, which can use the multicasted sequence as many times as needed, without - * causing multiple subscriptions to the ObservableSource + * causing multiple subscriptions to the current {@code Observable} * @param bufferSize - * the buffer size that limits the number of items the connectable ObservableSource can replay + * the buffer size that limits the number of items the connectable {@code Observable} can replay * @param time * the duration of the window in which the replayed items must have been emitted * @param unit * the time unit of {@code time} * @param scheduler - * the Scheduler that is the time source for the window + * the {@code Scheduler} that is the time source for the window * @param eagerTruncate - * if true, whenever the internal buffer is truncated to the given bufferSize/age, the + * if {@code true}, whenever the internal buffer is truncated to the given bufferSize/age, the * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention - * @return an Observable that emits items that are the results of invoking the selector on items emitted by - * a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource, and + * @return an {@code Observable} that emits items that are the results of invoking the selector on items emitted by + * a {@code ConnectableObservable} that shares a single subscription to the current {@code Observable}, and * replays no more than {@code bufferSize} items that were emitted within the window defined by * {@code time} + * @throws NullPointerException if {@code selector}, {@code unit} or {@code scheduler} is {@code null} * @throws IllegalArgumentException - * if {@code bufferSize} is less than zero + * if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Replay */ @CheckReturnValue @@ -10862,8 +11197,8 @@ public final Observable replay(@NonNull Function, ? } /** - * Returns an Observable that emits items that are the results of invoking a specified selector on items - * emitted by a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource, + * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on items + * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable}, * replaying all items that were emitted within a specified time window. *

* @@ -10873,17 +11208,18 @@ public final Observable replay(@NonNull Function, ? *

* * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param selector * a selector function, which can use the multicasted sequence as many times as needed, without - * causing multiple subscriptions to the ObservableSource + * causing multiple subscriptions to the current {@code Observable} * @param time * the duration of the window in which the replayed items must have been emitted * @param unit * the time unit of {@code time} - * @return an Observable that emits items that are the results of invoking the selector on items emitted by - * a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource, + * @return an {@code Observable} that emits items that are the results of invoking the selector on items emitted by + * a {@code ConnectableObservable} that shares a single subscription to the current {@code Observable}, * replaying all items that were emitted within the window defined by {@code time} + * @throws NullPointerException if {@code selector} or {@code unit} is {@code null} * @see ReactiveX operators documentation: Replay */ @CheckReturnValue @@ -10894,8 +11230,8 @@ public final Observable replay(@NonNull Function, ? } /** - * Returns an Observable that emits items that are the results of invoking a specified selector on items - * emitted by a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource, + * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on items + * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable}, * replaying all items that were emitted within a specified time window. *

* @@ -10905,19 +11241,20 @@ public final Observable replay(@NonNull Function, ? *

* * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param selector * a selector function, which can use the multicasted sequence as many times as needed, without - * causing multiple subscriptions to the ObservableSource + * causing multiple subscriptions to the current {@code Observable} * @param time * the duration of the window in which the replayed items must have been emitted * @param unit * the time unit of {@code time} * @param scheduler * the scheduler that is the time source for the window - * @return an Observable that emits items that are the results of invoking the selector on items emitted by - * a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource, + * @return an {@code Observable} that emits items that are the results of invoking the selector on items emitted by + * a {@code ConnectableObservable} that shares a single subscription to the current {@code Observable}, * replaying all items that were emitted within the window defined by {@code time} + * @throws NullPointerException if {@code selector}, {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Replay * @see #replay(Function, long, TimeUnit, Scheduler, boolean) */ @@ -10932,8 +11269,8 @@ public final Observable replay(@NonNull Function, ? } /** - * Returns an Observable that emits items that are the results of invoking a specified selector on items - * emitted by a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource, + * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on items + * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable}, * replaying all items that were emitted within a specified time window. *

* @@ -10943,10 +11280,10 @@ public final Observable replay(@NonNull Function, ? *

* * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param selector * a selector function, which can use the multicasted sequence as many times as needed, without - * causing multiple subscriptions to the ObservableSource + * causing multiple subscriptions to the current {@code Observable} * @param time * the duration of the window in which the replayed items must have been emitted * @param unit @@ -10954,11 +11291,12 @@ public final Observable replay(@NonNull Function, ? * @param scheduler * the scheduler that is the time source for the window * @param eagerTruncate - * if true, whenever the internal buffer is truncated to the given age, the + * if {@code true}, whenever the internal buffer is truncated to the given age, the * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention - * @return an Observable that emits items that are the results of invoking the selector on items emitted by - * a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource, + * @return an {@code Observable} that emits items that are the results of invoking the selector on items emitted by + * a {@code ConnectableObservable} that shares a single subscription to the current {@code Observable}, * replaying all items that were emitted within the window defined by {@code time} + * @throws NullPointerException if {@code selector}, {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Replay */ @CheckReturnValue @@ -10972,9 +11310,9 @@ public final Observable replay(@NonNull Function, ? } /** - * Returns a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource that - * replays at most {@code bufferSize} items emitted by that ObservableSource. A Connectable ObservableSource resembles - * an ordinary ObservableSource, except that it does not begin emitting items when it is subscribed to, but only + * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} that + * replays at most {@code bufferSize} items emitted by the current {@code Observable}. A connectable {@code Observable} resembles + * an ordinary {@code Observable}, except that it does not begin emitting items when it is subscribed to, but only * when its {@code connect} method is called. *

* @@ -10990,8 +11328,9 @@ public final Observable replay(@NonNull Function, ? * * @param bufferSize * the buffer size that limits the number of items that can be replayed - * @return a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource and - * replays at most {@code bufferSize} items emitted by that ObservableSource + * @return a {@code ConnectableObservable} that shares a single subscription to the current {@code Observable} and + * replays at most {@code bufferSize} items emitted by the current {@code Observable} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Replay * @see #replay(int, boolean) */ @@ -11004,9 +11343,9 @@ public final ConnectableObservable replay(int bufferSize) { } /** - * Returns a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource that - * replays at most {@code bufferSize} items emitted by that ObservableSource. A Connectable ObservableSource resembles - * an ordinary ObservableSource, except that it does not begin emitting items when it is subscribed to, but only + * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} that + * replays at most {@code bufferSize} items emitted by the current {@code Observable}. A connectable {@code Observable} resembles + * an ordinary {@code Observable}, except that it does not begin emitting items when it is subscribed to, but only * when its {@code connect} method is called. *

* @@ -11022,10 +11361,11 @@ public final ConnectableObservable replay(int bufferSize) { * @param bufferSize * the buffer size that limits the number of items that can be replayed * @param eagerTruncate - * if true, whenever the internal buffer is truncated to the given bufferSize/age, the + * if {@code true}, whenever the internal buffer is truncated to the given bufferSize/age, the * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention - * @return a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource and - * replays at most {@code bufferSize} items emitted by that ObservableSource + * @return a {@code ConnectableObservable} that shares a single subscription to the current {@code Observable} and + * replays at most {@code bufferSize} items emitted by the current {@code Observable} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Replay */ @CheckReturnValue @@ -11037,9 +11377,9 @@ public final ConnectableObservable replay(int bufferSize, boolean eagerTrunca } /** - * Returns a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource and - * replays at most {@code bufferSize} items that were emitted during a specified time window. A Connectable - * ObservableSource resembles an ordinary ObservableSource, except that it does not begin emitting items when it is + * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} and + * replays at most {@code bufferSize} items that were emitted during a specified time window. A connectable + * {@code Observable} resembles an ordinary {@code Observable}, except that it does not begin emitting items when it is * subscribed to, but only when its {@code connect} method is called. *

* @@ -11059,9 +11399,11 @@ public final ConnectableObservable replay(int bufferSize, boolean eagerTrunca * the duration of the window in which the replayed items must have been emitted * @param unit * the time unit of {@code time} - * @return a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource and + * @return a {@code ConnectableObservable} that shares a single subscription to the current {@code Observable} and * replays at most {@code bufferSize} items that were emitted during the window defined by * {@code time} + * @throws NullPointerException if {@code unit} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Replay * @see #replay(int, long, TimeUnit, Scheduler, boolean) */ @@ -11073,9 +11415,9 @@ public final ConnectableObservable replay(int bufferSize, long time, @NonNull } /** - * Returns a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource and + * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} and * that replays a maximum of {@code bufferSize} items that are emitted within a specified time window. A - * Connectable ObservableSource resembles an ordinary ObservableSource, except that it does not begin emitting items + * connectable {@code Observable} resembles an ordinary {@code Observable}, except that it does not begin emitting items * when it is subscribed to, but only when its {@code connect} method is called. *

* Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than @@ -11097,11 +11439,12 @@ public final ConnectableObservable replay(int bufferSize, long time, @NonNull * the time unit of {@code time} * @param scheduler * the scheduler that is used as a time source for the window - * @return a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource and + * @return a {@code ConnectableObservable} that shares a single subscription to the current {@code Observable} and * replays at most {@code bufferSize} items that were emitted during the window defined by * {@code time} + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @throws IllegalArgumentException - * if {@code bufferSize} is less than zero + * if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Replay * @see #replay(int, long, TimeUnit, Scheduler, boolean) */ @@ -11116,9 +11459,9 @@ public final ConnectableObservable replay(int bufferSize, long time, @NonNull } /** - * Returns a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource and + * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} and * that replays a maximum of {@code bufferSize} items that are emitted within a specified time window. A - * Connectable ObservableSource resembles an ordinary ObservableSource, except that it does not begin emitting items + * connectable {@code Observable} resembles an ordinary {@code Observable}, except that it does not begin emitting items * when it is subscribed to, but only when its {@code connect} method is called. *

* @@ -11140,14 +11483,15 @@ public final ConnectableObservable replay(int bufferSize, long time, @NonNull * the time unit of {@code time} * @param scheduler * the scheduler that is used as a time source for the window - * @return a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource and + * @return a {@code ConnectableObservable} that shares a single subscription to the current {@code Observable} and * replays at most {@code bufferSize} items that were emitted during the window defined by * {@code time} * @param eagerTruncate - * if true, whenever the internal buffer is truncated to the given bufferSize/age, the + * if {@code true}, whenever the internal buffer is truncated to the given bufferSize/age, the * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @throws IllegalArgumentException - * if {@code bufferSize} is less than zero + * if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Replay */ @CheckReturnValue @@ -11161,9 +11505,9 @@ public final ConnectableObservable replay(int bufferSize, long time, @NonNull } /** - * Returns a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource and - * replays all items emitted by that ObservableSource within a specified time window. A Connectable ObservableSource - * resembles an ordinary ObservableSource, except that it does not begin emitting items when it is subscribed to, + * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} and + * replays all items emitted by the current {@code Observable} within a specified time window. A connectable {@code Observable} + * resembles an ordinary {@code Observable}, except that it does not begin emitting items when it is subscribed to, * but only when its {@code connect} method is called. *

* @@ -11176,8 +11520,9 @@ public final ConnectableObservable replay(int bufferSize, long time, @NonNull * the duration of the window in which the replayed items must have been emitted * @param unit * the time unit of {@code time} - * @return a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource and + * @return a {@code ConnectableObservable} that shares a single subscription to the current {@code Observable} and * replays the items that were emitted during the window defined by {@code time} + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: Replay */ @CheckReturnValue @@ -11188,9 +11533,9 @@ public final ConnectableObservable replay(long time, @NonNull TimeUnit unit) } /** - * Returns a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource and - * replays all items emitted by that ObservableSource within a specified time window. A Connectable ObservableSource - * resembles an ordinary ObservableSource, except that it does not begin emitting items when it is subscribed to, + * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} and + * replays all items emitted by the current {@code Observable} within a specified time window. A connectable {@code Observable} + * resembles an ordinary {@code Observable}, except that it does not begin emitting items when it is subscribed to, * but only when its {@code connect} method is called. *

* @@ -11207,9 +11552,10 @@ public final ConnectableObservable replay(long time, @NonNull TimeUnit unit) * @param unit * the time unit of {@code time} * @param scheduler - * the Scheduler that is the time source for the window - * @return a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource and + * the {@code Scheduler} that is the time source for the window + * @return a {@code ConnectableObservable} that shares a single subscription to the current {@code Observable} and * replays the items that were emitted during the window defined by {@code time} + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Replay * @see #replay(long, TimeUnit, Scheduler, boolean) */ @@ -11223,9 +11569,9 @@ public final ConnectableObservable replay(long time, @NonNull TimeUnit unit, } /** - * Returns a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource and - * replays all items emitted by that ObservableSource within a specified time window. A Connectable ObservableSource - * resembles an ordinary ObservableSource, except that it does not begin emitting items when it is subscribed to, + * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} and + * replays all items emitted by the current {@code Observable} within a specified time window. A connectable {@code Observable} + * resembles an ordinary {@code Observable}, except that it does not begin emitting items when it is subscribed to, * but only when its {@code connect} method is called. *

* @@ -11242,12 +11588,13 @@ public final ConnectableObservable replay(long time, @NonNull TimeUnit unit, * @param unit * the time unit of {@code time} * @param scheduler - * the Scheduler that is the time source for the window + * the {@code Scheduler} that is the time source for the window * @param eagerTruncate - * if true, whenever the internal buffer is truncated to the given bufferSize/age, the + * if {@code true}, whenever the internal buffer is truncated to the given bufferSize/age, the * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention - * @return a {@link ConnectableObservable} that shares a single subscription to the source ObservableSource and + * @return a {@code ConnectableObservable} that shares a single subscription to the current {@code Observable} and * replays the items that were emitted during the window defined by {@code time} + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Replay */ @CheckReturnValue @@ -11260,16 +11607,16 @@ public final ConnectableObservable replay(long time, @NonNull TimeUnit unit, } /** - * Returns an Observable that mirrors the source ObservableSource, resubscribing to it if it calls {@code onError} + * Returns an {@code Observable} that mirrors the current {@code Observable}, resubscribing to it if it calls {@code onError} * (infinite retry count). *

* *

- * If the source ObservableSource calls {@link Observer#onError}, this method will resubscribe to the source - * ObservableSource rather than propagating the {@code onError} call. + * If the current {@code Observable} calls {@link Observer#onError}, this method will resubscribe to the current + * {@code Observable} rather than propagating the {@code onError} call. *

- * Any and all items emitted by the source ObservableSource will be emitted by the resulting ObservableSource, even - * those emitted during failed subscriptions. For example, if an ObservableSource fails at first but emits + * Any and all items emitted by the current {@code Observable} will be emitted by the resulting {@code Observable}, even + * those emitted during failed subscriptions. For example, if the current {@code Observable} fails at first but emits * {@code [1, 2]} then succeeds the second time and emits {@code [1, 2, 3, 4, 5]} then the complete sequence * of emissions and notifications would be {@code [1, 2, 1, 2, 3, 4, 5, onComplete]}. *

@@ -11277,7 +11624,7 @@ public final ConnectableObservable replay(long time, @NonNull TimeUnit unit, *
{@code retry} does not operate by default on a particular {@link Scheduler}.
*
* - * @return the source ObservableSource modified with retry logic + * @return the current {@code Observable} modified with retry logic * @see ReactiveX operators documentation: Retry */ @CheckReturnValue @@ -11288,8 +11635,8 @@ public final Observable retry() { } /** - * Returns an Observable that mirrors the source ObservableSource, resubscribing to it if it calls {@code onError} - * and the predicate returns true for that specific exception and retry count. + * Returns an {@code Observable} that mirrors the current {@code Observable}, resubscribing to it if it calls {@code onError} + * and the predicate returns {@code true} for that specific exception and retry count. *

* *

@@ -11300,7 +11647,8 @@ public final Observable retry() { * @param predicate * the predicate that determines if a resubscription may happen in case of a specific exception * and retry count - * @return the source ObservableSource modified with retry logic + * @return the current {@code Observable} modified with retry logic + * @throws NullPointerException if {@code predicate} is {@code null} * @see #retry() * @see ReactiveX operators documentation: Retry */ @@ -11314,17 +11662,17 @@ public final Observable retry(@NonNull BiPredicate * *

- * If the source ObservableSource calls {@link Observer#onError}, this method will resubscribe to the source - * ObservableSource for a maximum of {@code count} resubscriptions rather than propagating the + * If the current {@code Observable} calls {@link Observer#onError}, this method will resubscribe to the current + * {@code Observable} for a maximum of {@code count} resubscriptions rather than propagating the * {@code onError} call. *

- * Any and all items emitted by the source ObservableSource will be emitted by the resulting ObservableSource, even - * those emitted during failed subscriptions. For example, if an ObservableSource fails at first but emits + * Any and all items emitted by the current {@code Observable} will be emitted by the resulting {@code Observable}, even + * those emitted during failed subscriptions. For example, if the current {@code Observable} fails at first but emits * {@code [1, 2]} then succeeds the second time and emits {@code [1, 2, 3, 4, 5]} then the complete sequence * of emissions and notifications would be {@code [1, 2, 1, 2, 3, 4, 5, onComplete]}. *

@@ -11333,8 +11681,9 @@ public final Observable retry(@NonNull BiPredicate * * @param times - * the number of times to resubscribe if the current Observable fails - * @return the source ObservableSource modified with retry logic + * the number of times to resubscribe if the current {@code Observable} fails + * @return the current {@code Observable} modified with retry logic + * @throws IllegalArgumentException if {@code times} is negative * @see ReactiveX operators documentation: Retry */ @CheckReturnValue @@ -11345,16 +11694,18 @@ public final Observable retry(long times) { } /** - * Retries at most times or until the predicate returns false, whichever happens first. + * Retries at most times or until the predicate returns {@code false}, whichever happens first. *

* *

*
Scheduler:
*
{@code retry} does not operate by default on a particular {@link Scheduler}.
*
- * @param times the number of times to resubscribe if the current Observable fails - * @param predicate the predicate called with the failure Throwable and should return true to trigger a retry. - * @return the new Observable instance + * @param times the number of times to resubscribe if the current {@code Observable} fails + * @param predicate the predicate called with the failure {@link Throwable} and should return {@code true} to trigger a retry. + * @throws NullPointerException if {@code predicate} is {@code null} + * @throws IllegalArgumentException if {@code times} is negative + * @return the new {@code Observable} instance */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -11369,7 +11720,7 @@ public final Observable retry(long times, @NonNull Predicate * *
@@ -11377,8 +11728,9 @@ public final Observable retry(long times, @NonNull Predicate{@code retry} does not operate by default on a particular {@link Scheduler}. *
* - * @param predicate the predicate that receives the failure Throwable and should return true to trigger a retry. - * @return the new Observable instance + * @param predicate the predicate that receives the failure {@link Throwable} and should return {@code true} to trigger a retry. + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code predicate} is {@code null} */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -11388,15 +11740,16 @@ public final Observable retry(@NonNull Predicate predicate } /** - * Retries until the given stop function returns true. + * Retries until the given stop function returns {@code true}. *

* *

*
Scheduler:
*
{@code retryUntil} does not operate by default on a particular {@link Scheduler}.
*
- * @param stop the function that should return true to stop retrying - * @return the new Observable instance + * @param stop the function that should return {@code true} to stop retrying + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code stop} is {@code null} */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -11407,12 +11760,12 @@ public final Observable retryUntil(@NonNull BooleanSupplier stop) { } /** - * Returns an Observable that emits the same values as the source ObservableSource with the exception of an + * Returns an {@code Observable} that emits the same values as the current {@code Observable} with the exception of an * {@code onError}. An {@code onError} notification from the source will result in the emission of a - * {@link Throwable} item to the ObservableSource provided as an argument to the {@code notificationHandler} - * function. If that ObservableSource calls {@code onComplete} or {@code onError} then {@code retry} will call - * {@code onComplete} or {@code onError} on the child subscription. Otherwise, this ObservableSource will - * resubscribe to the source ObservableSource. + * {@link Throwable} item to the {@code Observable} provided as an argument to the {@code notificationHandler} + * function. If that {@code Observable} calls {@code onComplete} or {@code onError} then {@code retry} will call + * {@code onComplete} or {@code onError} on the child subscription. Otherwise, the current {@code Observable} + * will be resubscribed. *

* *

@@ -11444,10 +11797,10 @@ public final Observable retryUntil(@NonNull BooleanSupplier stop) { * subscribing * } *

- * Note that the inner {@code ObservableSource} returned by the handler function should signal + * Note that the inner {@link ObservableSource} returned by the handler function should signal * either {@code onNext}, {@code onError} or {@code onComplete} in response to the received * {@code Throwable} to indicate the operator should retry or terminate. If the upstream to - * the operator is asynchronous, signalling onNext followed by onComplete immediately may + * the operator is asynchronous, signaling {@code onNext} followed by {@code onComplete} immediately may * result in the sequence to be completed immediately. Similarly, if this inner * {@code ObservableSource} signals {@code onError} or {@code onComplete} while the upstream is * active, the sequence is terminated with the same signal immediately. @@ -11474,9 +11827,10 @@ public final Observable retryUntil(@NonNull BooleanSupplier stop) { *

* * @param handler - * receives an ObservableSource of notifications with which a user can complete or error, aborting the + * receives an {@code Observable} of notifications with which a user can complete or error, aborting the * retry - * @return the source ObservableSource modified with retry logic + * @return the current {@code Observable} modified with retry logic + * @throws NullPointerException if {@code handler} is {@code null} * @see ReactiveX operators documentation: Retry */ @CheckReturnValue @@ -11489,16 +11843,16 @@ public final Observable retryWhen( } /** - * Subscribes to the current Observable and wraps the given Observer into a SafeObserver - * (if not already a SafeObserver) that - * deals with exceptions thrown by a misbehaving Observer (that doesn't follow the - * Reactive-Streams specification). + * Subscribes to the current {@code Observable} and wraps the given {@link Observer} into a {@link SafeObserver} + * (if not already a {@code SafeObserver}) that + * deals with exceptions thrown by a misbehaving {@code Observer} (that doesn't follow the + * Reactive Streams specification). *
*
Scheduler:
*
{@code safeSubscribe} does not operate by default on a particular {@link Scheduler}.
*
- * @param observer the incoming Observer instance - * @throws NullPointerException if s is null + * @param observer the incoming {@code Observer} instance + * @throws NullPointerException if {@code observer} is {@code null} */ @SchedulerSupport(SchedulerSupport.NONE) @NonNull @@ -11512,7 +11866,7 @@ public final void safeSubscribe(@NonNull Observer observer) { } /** - * Returns an Observable that emits the most recently emitted item (if any) emitted by the source ObservableSource + * Returns an {@code Observable} that emits the most recently emitted item (if any) emitted by the current {@code Observable} * within periodic time intervals. *

* @@ -11525,8 +11879,9 @@ public final void safeSubscribe(@NonNull Observer observer) { * the sampling rate * @param unit * the {@link TimeUnit} in which {@code period} is defined - * @return an Observable that emits the results of sampling the items emitted by the source ObservableSource at + * @return an {@code Observable} that emits the results of sampling the items emitted by the current {@code Observable} at * the specified time interval + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: Sample * @see #throttleLast(long, TimeUnit) */ @@ -11538,7 +11893,7 @@ public final Observable sample(long period, @NonNull TimeUnit unit) { } /** - * Returns an Observable that emits the most recently emitted item (if any) emitted by the source ObservableSource + * Returns an {@code Observable} that emits the most recently emitted item (if any) emitted by the current {@code Observable} * within periodic time intervals and optionally emit the very last upstream item when the upstream completes. *

* @@ -11552,12 +11907,12 @@ public final Observable sample(long period, @NonNull TimeUnit unit) { * the sampling rate * @param unit * the {@link TimeUnit} in which {@code period} is defined - * @return an Observable that emits the results of sampling the items emitted by the source ObservableSource at + * @return an {@code Observable} that emits the results of sampling the items emitted by the current {@code Observable} at * the specified time interval * @param emitLast - * if true and the upstream completes while there is still an unsampled item available, + * if {@code true} and the upstream completes while there is still an unsampled item available, * that item is emitted to downstream before completion - * if false, an unsampled last item is ignored. + * if {@code false}, an unsampled last item is ignored. * @see ReactiveX operators documentation: Sample * @see #throttleLast(long, TimeUnit) * @since 2.1 @@ -11570,13 +11925,13 @@ public final Observable sample(long period, @NonNull TimeUnit unit, boolean e } /** - * Returns an Observable that emits the most recently emitted item (if any) emitted by the source ObservableSource - * within periodic time intervals, where the intervals are defined on a particular Scheduler. + * Returns an {@code Observable} that emits the most recently emitted item (if any) emitted by the current {@code Observable} + * within periodic time intervals, where the intervals are defined on a particular {@link Scheduler}. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param period @@ -11584,9 +11939,10 @@ public final Observable sample(long period, @NonNull TimeUnit unit, boolean e * @param unit * the {@link TimeUnit} in which {@code period} is defined * @param scheduler - * the {@link Scheduler} to use when sampling - * @return an Observable that emits the results of sampling the items emitted by the source ObservableSource at + * the {@code Scheduler} to use when sampling + * @return an {@code Observable} that emits the results of sampling the items emitted by the current {@code Observable} at * the specified time interval + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Sample * @see #throttleLast(long, TimeUnit, Scheduler) */ @@ -11600,14 +11956,14 @@ public final Observable sample(long period, @NonNull TimeUnit unit, @NonNull } /** - * Returns an Observable that emits the most recently emitted item (if any) emitted by the source ObservableSource - * within periodic time intervals, where the intervals are defined on a particular Scheduler + * Returns an {@code Observable} that emits the most recently emitted item (if any) emitted by the current {@code Observable} + * within periodic time intervals, where the intervals are defined on a particular {@link Scheduler} * and optionally emit the very last upstream item when the upstream completes. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* *

History: 2.0.5 - experimental @@ -11616,13 +11972,14 @@ public final Observable sample(long period, @NonNull TimeUnit unit, @NonNull * @param unit * the {@link TimeUnit} in which {@code period} is defined * @param scheduler - * the {@link Scheduler} to use when sampling + * the {@code Scheduler} to use when sampling * @param emitLast - * if true and the upstream completes while there is still an unsampled item available, + * if {@code true} and the upstream completes while there is still an unsampled item available, * that item is emitted to downstream before completion - * if false, an unsampled last item is ignored. - * @return an Observable that emits the results of sampling the items emitted by the source ObservableSource at + * if {@code false}, an unsampled last item is ignored. + * @return an {@code Observable} that emits the results of sampling the items emitted by the current {@code Observable} at * the specified time interval + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Sample * @see #throttleLast(long, TimeUnit, Scheduler) * @since 2.1 @@ -11637,9 +11994,9 @@ public final Observable sample(long period, @NonNull TimeUnit unit, @NonNull } /** - * Returns an Observable that, when the specified {@code sampler} ObservableSource emits an item or completes, - * emits the most recently emitted item (if any) emitted by the source ObservableSource since the previous - * emission from the {@code sampler} ObservableSource. + * Returns an {@code Observable} that, when the specified {@code sampler} {@link ObservableSource} emits an item or completes, + * emits the most recently emitted item (if any) emitted by the current {@code Observable} since the previous + * emission from the {@code sampler} {@code ObservableSource}. *

* *

@@ -11647,11 +12004,12 @@ public final Observable sample(long period, @NonNull TimeUnit unit, @NonNull *
This version of {@code sample} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the element type of the sampler ObservableSource + * @param the element type of the sampler {@code ObservableSource} * @param sampler - * the ObservableSource to use for sampling the source ObservableSource - * @return an Observable that emits the results of sampling the items emitted by this ObservableSource whenever - * the {@code sampler} ObservableSource emits an item or completes + * the {@code ObservableSource} to use for sampling the current {@code Observable} + * @return an {@code Observable} that emits the results of sampling the items emitted by the current {@code Observable} whenever + * the {@code sampler} {@code ObservableSource} emits an item or completes + * @throws NullPointerException if {@code sampler} is {@code null} * @see ReactiveX operators documentation: Sample */ @CheckReturnValue @@ -11663,10 +12021,10 @@ public final Observable sample(@NonNull ObservableSource sampler) { } /** - * Returns an Observable that, when the specified {@code sampler} ObservableSource emits an item or completes, - * emits the most recently emitted item (if any) emitted by the source ObservableSource since the previous - * emission from the {@code sampler} ObservableSource - * and optionally emit the very last upstream item when the upstream or other ObservableSource complete. + * Returns an {@code Observable} that, when the specified {@code sampler} {@link ObservableSource} emits an item or completes, + * emits the most recently emitted item (if any) emitted by the current {@code Observable} since the previous + * emission from the {@code sampler} {@code ObservableSource} + * and optionally emit the very last upstream item when the upstream or other {@code ObservableSource} complete. *

* *

@@ -11675,15 +12033,16 @@ public final Observable sample(@NonNull ObservableSource sampler) { *
* *

History: 2.0.5 - experimental - * @param the element type of the sampler ObservableSource + * @param the element type of the sampler {@code ObservableSource} * @param sampler - * the ObservableSource to use for sampling the source ObservableSource + * the {@code ObservableSource} to use for sampling the current {@code Observable} * @param emitLast - * if true and the upstream completes while there is still an unsampled item available, + * if {@code true} and the upstream completes while there is still an unsampled item available, * that item is emitted to downstream before completion - * if false, an unsampled last item is ignored. - * @return an Observable that emits the results of sampling the items emitted by this ObservableSource whenever - * the {@code sampler} ObservableSource emits an item or completes + * if {@code false}, an unsampled last item is ignored. + * @return an {@code Observable} that emits the results of sampling the items emitted by the current {@code Observable} whenever + * the {@code sampler} {@code ObservableSource} emits an item or completes + * @throws NullPointerException if {@code sampler} is {@code null} * @see ReactiveX operators documentation: Sample * @since 2.1 */ @@ -11696,9 +12055,9 @@ public final Observable sample(@NonNull ObservableSource sampler, bool } /** - * Returns an Observable that applies a specified accumulator function to the first item emitted by a source - * ObservableSource, then feeds the result of that function along with the second item emitted by the source - * ObservableSource into the same function, and so on until all items have been emitted by the source ObservableSource, + * Returns an {@code Observable} that applies a specified accumulator function to the first item emitted by the current + * {@code Observable}, then feeds the result of that function along with the second item emitted by the current + * {@code Observable} into the same function, and so on until all items have been emitted by the current {@code Observable}, * emitting the result of each of these iterations. *

* @@ -11710,10 +12069,11 @@ public final Observable sample(@NonNull ObservableSource sampler, bool *

* * @param accumulator - * an accumulator function to be invoked on each item emitted by the source ObservableSource, whose + * an accumulator function to be invoked on each item emitted by the current {@code Observable}, whose * result will be emitted to {@link Observer}s via {@link Observer#onNext onNext} and used in the * next accumulator call - * @return an Observable that emits the results of each call to the accumulator function + * @return an {@code Observable} that emits the results of each call to the accumulator function + * @throws NullPointerException if {@code accumulator} is {@code null} * @see ReactiveX operators documentation: Scan */ @CheckReturnValue @@ -11725,19 +12085,19 @@ public final Observable scan(@NonNull BiFunction accumulator) { } /** - * Returns an Observable that applies a specified accumulator function to the first item emitted by a source - * ObservableSource and a seed value, then feeds the result of that function along with the second item emitted by - * the source ObservableSource into the same function, and so on until all items have been emitted by the source - * ObservableSource, emitting the result of each of these iterations. + * Returns an {@code Observable} that applies a specified accumulator function to the first item emitted by the current + * {@code Observable} and a seed value, then feeds the result of that function along with the second item emitted by + * the current {@code Observable} into the same function, and so on until all items have been emitted by the current + * {@code Observable}, emitting the result of each of these iterations. *

* *

* This sort of function is sometimes called an accumulator. *

- * Note that the ObservableSource that results from this method will emit {@code initialValue} as its first + * Note that the {@code Observable} that results from this method will emit {@code initialValue} as its first * emitted item. *

- * Note that the {@code initialValue} is shared among all subscribers to the resulting ObservableSource + * Note that the {@code initialValue} is shared among all subscribers to the resulting {@code Observable} * and may cause problems if it is mutable. To make sure each subscriber gets its own value, defer * the application of this operator via {@link #defer(Supplier)}: * 


@@ -11759,11 +12119,12 @@ public final Observable scan(@NonNull BiFunction accumulator) {
      * @param initialValue
      *            the initial (seed) accumulator item
      * @param accumulator
-     *            an accumulator function to be invoked on each item emitted by the source ObservableSource, whose
+     *            an accumulator function to be invoked on each item emitted by the current {@code Observable}, whose
      *            result will be emitted to {@link Observer}s via {@link Observer#onNext onNext} and used in the
      *            next accumulator call
-     * @return an Observable that emits {@code initialValue} followed by the results of each call to the
+     * @return an {@code Observable} that emits {@code initialValue} followed by the results of each call to the
      *         accumulator function
+     * @throws NullPointerException if {@code initialValue} or {@code accumulator} is {@code null}
      * @see ReactiveX operators documentation: Scan
      */
     @CheckReturnValue
@@ -11775,16 +12136,16 @@ public final  Observable scan(@NonNull R initialValue, @NonNull BiFunction
     }
 
     /**
-     * Returns an Observable that applies a specified accumulator function to the first item emitted by a source
-     * ObservableSource and a seed value, then feeds the result of that function along with the second item emitted by
-     * the source ObservableSource into the same function, and so on until all items have been emitted by the source
-     * ObservableSource, emitting the result of each of these iterations.
+     * Returns an {@code Observable} that applies a specified accumulator function to the first item emitted by the current
+     * {@code Observable} and a seed value, then feeds the result of that function along with the second item emitted by
+     * the current {@code Observable} into the same function, and so on until all items have been emitted by the current
+     * {@code Observable}, emitting the result of each of these iterations.
      * 

      * 
      * 

      * This sort of function is sometimes called an accumulator.
      * 

-     * Note that the ObservableSource that results from this method will emit the value returned
+     * Note that the {@code Observable} that results from this method will emit the value returned
      * by the {@code seedSupplier} as its first item.
      * 

      *  
Scheduler:

@@ -11793,13 +12154,14 @@ public final  Observable scan(@NonNull R initialValue, @NonNull BiFunction
      *
      * @param  the initial, accumulator and result type
      * @param seedSupplier
-     *            a Supplier that returns the initial (seed) accumulator item for each individual Observer
+     *            a {@link Supplier} that returns the initial (seed) accumulator item for each individual {@link Observer}
      * @param accumulator
-     *            an accumulator function to be invoked on each item emitted by the source ObservableSource, whose
-     *            result will be emitted to {@link Observer}s via {@link Observer#onNext onNext} and used in the
+     *            an accumulator function to be invoked on each item emitted by the current {@code Observable}, whose
+     *            result will be emitted to {@code Observer}s via {@link Observer#onNext onNext} and used in the
      *            next accumulator call
-     * @return an Observable that emits {@code initialValue} followed by the results of each call to the
+     * @return an {@code Observable} that emits {@code initialValue} followed by the results of each call to the
      *         accumulator function
+     * @throws NullPointerException if {@code seedSupplier} or {@code accumulator} is {@code null}
      * @see ReactiveX operators documentation: Scan
      */
     @CheckReturnValue
@@ -11812,13 +12174,13 @@ public final  Observable scanWith(@NonNull Supplier seedSupplier, @NonN
     }
 
     /**
-     * Forces an ObservableSource's emissions and notifications to be serialized and for it to obey
-     * the ObservableSource contract in other ways.
+     * Forces the current {@code Observable}'s emissions and notifications to be serialized and for it to obey
+     * the {@code ObservableSource} contract in other ways.
      * 

-     * It is possible for an ObservableSource to invoke its Observers' methods asynchronously, perhaps from
-     * different threads. This could make such an ObservableSource poorly-behaved, in that it might try to invoke
+     * It is possible for an {@code Observable} to invoke its {@link Observer}s' methods asynchronously, perhaps from
+     * different threads. This could make such an {@code Observable} poorly-behaved, in that it might try to invoke
      * {@code onComplete} or {@code onError} before one of its {@code onNext} invocations, or it might call
-     * {@code onNext} from two different threads concurrently. You can force such an ObservableSource to be
+     * {@code onNext} from two different threads concurrently. You can force such an {@code Observable} to be
      * well-behaved and sequential by applying the {@code serialize} method to it.
      * 

      * 
@@ -11827,7 +12189,7 @@ public final  Observable scanWith(@NonNull Supplier seedSupplier, @NonN
      *  
{@code serialize} does not operate by default on a particular {@link Scheduler}.

      * 

      *
-     * @return an {@link ObservableSource} that is guaranteed to be well-behaved and to make only serialized calls to
+     * @return an {@code Observable} that is guaranteed to be well-behaved and to make only serialized calls to
      *         its observers
      * @see ReactiveX operators documentation: Serialize
      */
@@ -11839,9 +12201,9 @@ public final Observable serialize() {
     }
 
     /**
-     * Returns a new {@link ObservableSource} that multicasts (and shares a single subscription to) the original {@link ObservableSource}. As long as
-     * there is at least one {@link Observer} this {@link ObservableSource} will be subscribed and emitting data.
-     * When all subscribers have disposed it will dispose the source {@link ObservableSource}.
+     * Returns a new {@code Observable} that multicasts (and shares a single subscription to) the current {@code Observable}. As long as
+     * there is at least one {@link Observer}, the current {@code Observable} will stay subscribed and keep emitting signals.
+     * When all observers have disposed, the operator will dispose the subscription to the current {@code Observable}.
      * 

      * This is an alias for {@link #publish()}.{@link ConnectableObservable#refCount() refCount()}.
      * 

@@ -11851,8 +12213,8 @@ public final Observable serialize() {
      *  
{@code share} does not operate by default on a particular {@link Scheduler}.

      *
* - * @return an {@code ObservableSource} that upon connection causes the source {@code ObservableSource} to emit items - * to its {@link Observer}s + * @return an {@code Observable} that upon connection causes the current {@code Observable} to emit items + * to its {@code Observer}s * @see ReactiveX operators documentation: RefCount */ @CheckReturnValue @@ -11863,8 +12225,9 @@ public final Observable share() { } /** - * Returns a Maybe that completes if this Observable is empty or emits the single item emitted by this Observable, - * or signals an {@code IllegalArgumentException} if this Observable emits more than one item. + * Returns a {@link Maybe} that completes if the current {@code Observable} is empty or emits the single item + * emitted by the current {@code Observable}, or signals an {@link IllegalArgumentException} if the current + * {@code Observable} emits more than one item. *

* *

@@ -11872,7 +12235,7 @@ public final Observable share() { *
{@code singleElement} does not operate by default on a particular {@link Scheduler}.
*
* - * @return a {@link Maybe} that emits the single item emitted by the source ObservableSource + * @return a {@code Maybe} that emits the single item emitted by the current {@code Observable} * @see ReactiveX operators documentation: First */ @CheckReturnValue @@ -11883,9 +12246,9 @@ public final Maybe singleElement() { } /** - * Returns a Single that emits the single item emitted by this Observable, if this Observable - * emits only a single item, or a default item if the source ObservableSource emits no items. If the source - * ObservableSource emits more than one item, an {@code IllegalArgumentException} is signalled instead. + * Returns a {@link Single} that emits the single item emitted by the current {@code Observable}, if the current {@code Observable} + * emits only a single item, or a default item if the current {@code Observable} emits no items. If the current + * {@code Observable} emits more than one item, an {@link IllegalArgumentException} is signaled instead. *

* *

@@ -11894,8 +12257,9 @@ public final Maybe singleElement() { *
* * @param defaultItem - * a default value to emit if the source ObservableSource emits no item - * @return the new Single instance + * a default value to emit if the current {@code Observable} emits no item + * @return the new {@code Single} instance + * @throws NullPointerException if {@code defaultItem} is {@code null} * @see ReactiveX operators documentation: First */ @CheckReturnValue @@ -11907,10 +12271,10 @@ public final Single single(@NonNull T defaultItem) { } /** - * Returns a Single that emits the single item emitted by this Observable if this Observable + * Returns a {@link Single} that emits the single item emitted by the current {@code Observable} if it * emits only a single item, otherwise - * if this Observable completes without emitting any items or emits more than one item a - * {@link NoSuchElementException} or {@code IllegalArgumentException} will be signalled respectively. + * if the current {@code Observable} completes without emitting any items or emits more than one item a + * {@link NoSuchElementException} or {@link IllegalArgumentException} will be signaled respectively. *

* *

@@ -11918,7 +12282,7 @@ public final Single single(@NonNull T defaultItem) { *
{@code singleOrError} does not operate by default on a particular {@link Scheduler}.
*
* - * @return the new Single instance + * @return the new {@code Single} instance * @see ReactiveX operators documentation: First */ @CheckReturnValue @@ -11929,7 +12293,7 @@ public final Single singleOrError() { } /** - * Returns an Observable that skips the first {@code count} items emitted by the source ObservableSource and emits + * Returns an {@code Observable} that skips the first {@code count} items emitted by the current {@code Observable} and emits * the remainder. *

* @@ -11940,8 +12304,8 @@ public final Single singleOrError() { * * @param count * the number of items to skip - * @return an Observable that is identical to the source ObservableSource except that it does not emit the first - * {@code count} items that the source ObservableSource emits + * @return an {@code Observable} that is identical to the current {@code Observable} except that it does not emit the first + * {@code count} items that the current {@code Observable} emits * @see ReactiveX operators documentation: Skip */ @CheckReturnValue @@ -11955,7 +12319,7 @@ public final Observable skip(long count) { } /** - * Returns an Observable that skips values emitted by the source ObservableSource before a specified time window + * Returns an {@code Observable} that skips values emitted by the current {@code Observable} before a specified time window * elapses. *

* @@ -11969,8 +12333,9 @@ public final Observable skip(long count) { * the length of the time window to skip * @param unit * the time unit of {@code time} - * @return an Observable that skips values emitted by the source ObservableSource before the time window defined + * @return an {@code Observable} that skips values emitted by the current {@code Observable} before the time window defined * by {@code time} elapses and the emits the remainder + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: Skip */ @CheckReturnValue @@ -11981,13 +12346,13 @@ public final Observable skip(long time, @NonNull TimeUnit unit) { } /** - * Returns an Observable that skips values emitted by the source ObservableSource before a specified time window + * Returns an {@code Observable} that skips values emitted by the current {@code Observable} before a specified time window * on a specified {@link Scheduler} elapses. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use for the timed skipping
+ *
You specify which {@code Scheduler} this operator will use for the timed skipping
*
* * @param time @@ -11995,9 +12360,10 @@ public final Observable skip(long time, @NonNull TimeUnit unit) { * @param unit * the time unit of {@code time} * @param scheduler - * the {@link Scheduler} on which the timed wait happens - * @return an Observable that skips values emitted by the source ObservableSource before the time window defined + * the {@code Scheduler} on which the timed wait happens + * @return an {@code Observable} that skips values emitted by the current {@code Observable} before the time window defined * by {@code time} and {@code scheduler} elapses, and then emits the remainder + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Skip */ @CheckReturnValue @@ -12008,13 +12374,13 @@ public final Observable skip(long time, @NonNull TimeUnit unit, @NonNull Sche } /** - * Returns an Observable that drops a specified number of items from the end of the sequence emitted by the - * source ObservableSource. + * Returns an {@code Observable} that drops a specified number of items from the end of the sequence emitted by the + * current {@code Observable}. *

* *

- * This Observer accumulates a queue long enough to store the first {@code count} items. As more items are - * received, items are taken from the front of the queue and emitted by the returned ObservableSource. This causes + * This {@link Observer} accumulates a queue long enough to store the first {@code count} items. As more items are + * received, items are taken from the front of the queue and emitted by the returned {@code Observable}. This causes * such items to be delayed. *

*
Scheduler:
@@ -12023,10 +12389,10 @@ public final Observable skip(long time, @NonNull TimeUnit unit, @NonNull Sche * * @param count * number of items to drop from the end of the source sequence - * @return an Observable that emits the items emitted by the source ObservableSource except for the dropped ones + * @return an {@code Observable} that emits the items emitted by the current {@code Observable} except for the dropped ones * at the end - * @throws IndexOutOfBoundsException - * if {@code count} is less than zero + * @throws IllegalArgumentException + * if {@code count} is negative * @see ReactiveX operators documentation: SkipLast */ @CheckReturnValue @@ -12034,7 +12400,7 @@ public final Observable skip(long time, @NonNull TimeUnit unit, @NonNull Sche @NonNull public final Observable skipLast(int count) { if (count < 0) { - throw new IndexOutOfBoundsException("count >= 0 required but it was " + count); + throw new IllegalArgumentException("count >= 0 required but it was " + count); } if (count == 0) { return RxJavaPlugins.onAssembly(this); @@ -12043,7 +12409,7 @@ public final Observable skipLast(int count) { } /** - * Returns an Observable that drops items emitted by the source ObservableSource during a specified time window + * Returns an {@code Observable} that drops items emitted by the current {@code Observable} during a specified time window * before the source completes. *

* @@ -12052,15 +12418,16 @@ public final Observable skipLast(int count) { *

*
Scheduler:
*
{@code skipLast} does not operate on any particular scheduler but uses the current time - * from the {@code computation} {@link Scheduler}.
+ * from the {@code trampoline} {@link Scheduler}. *
* * @param time * the length of the time window * @param unit * the time unit of {@code time} - * @return an Observable that drops those items emitted by the source ObservableSource in a time window before the + * @return an {@code Observable} that drops those items emitted by the current {@code Observable} in a time window before the * source completes defined by {@code time} + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: SkipLast */ @CheckReturnValue @@ -12071,7 +12438,7 @@ public final Observable skipLast(long time, @NonNull TimeUnit unit) { } /** - * Returns an Observable that drops items emitted by the source ObservableSource during a specified time window + * Returns an {@code Observable} that drops items emitted by the current {@code Observable} during a specified time window * before the source completes. *

* @@ -12088,10 +12455,11 @@ public final Observable skipLast(long time, @NonNull TimeUnit unit) { * @param unit * the time unit of {@code time} * @param delayError - * if true, an exception signalled by the current Observable is delayed until the regular elements are consumed - * by the downstream; if false, an exception is immediately signalled and all regular elements dropped - * @return an Observable that drops those items emitted by the source ObservableSource in a time window before the + * if {@code true}, an exception signaled by the current {@code Observable} is delayed until the regular elements are consumed + * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped + * @return an {@code Observable} that drops those items emitted by the current {@code Observable} in a time window before the * source completes defined by {@code time} + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: SkipLast */ @CheckReturnValue @@ -12102,7 +12470,7 @@ public final Observable skipLast(long time, @NonNull TimeUnit unit, boolean d } /** - * Returns an Observable that drops items emitted by the source ObservableSource during a specified time window + * Returns an {@code Observable} that drops items emitted by the current {@code Observable} during a specified time window * (defined on a specified scheduler) before the source completes. *

* @@ -12119,8 +12487,9 @@ public final Observable skipLast(long time, @NonNull TimeUnit unit, boolean d * the time unit of {@code time} * @param scheduler * the scheduler used as the time source - * @return an Observable that drops those items emitted by the source ObservableSource in a time window before the + * @return an {@code Observable} that drops those items emitted by the current {@code Observable} in a time window before the * source completes defined by {@code time} and {@code scheduler} + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: SkipLast */ @CheckReturnValue @@ -12131,7 +12500,7 @@ public final Observable skipLast(long time, @NonNull TimeUnit unit, @NonNull } /** - * Returns an Observable that drops items emitted by the source ObservableSource during a specified time window + * Returns an {@code Observable} that drops items emitted by the current {@code Observable} during a specified time window * (defined on a specified scheduler) before the source completes. *

* @@ -12149,10 +12518,11 @@ public final Observable skipLast(long time, @NonNull TimeUnit unit, @NonNull * @param scheduler * the scheduler used as the time source * @param delayError - * if true, an exception signalled by the current Observable is delayed until the regular elements are consumed - * by the downstream; if false, an exception is immediately signalled and all regular elements dropped - * @return an Observable that drops those items emitted by the source ObservableSource in a time window before the + * if {@code true}, an exception signaled by the current {@code Observable} is delayed until the regular elements are consumed + * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped + * @return an {@code Observable} that drops those items emitted by the current {@code Observable} in a time window before the * source completes defined by {@code time} and {@code scheduler} + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: SkipLast */ @CheckReturnValue @@ -12163,7 +12533,7 @@ public final Observable skipLast(long time, @NonNull TimeUnit unit, @NonNull } /** - * Returns an Observable that drops items emitted by the source ObservableSource during a specified time window + * Returns an {@code Observable} that drops items emitted by the current {@code Observable} during a specified time window * (defined on a specified scheduler) before the source completes. *

* @@ -12181,12 +12551,14 @@ public final Observable skipLast(long time, @NonNull TimeUnit unit, @NonNull * @param scheduler * the scheduler used as the time source * @param delayError - * if true, an exception signalled by the current Observable is delayed until the regular elements are consumed - * by the downstream; if false, an exception is immediately signalled and all regular elements dropped + * if {@code true}, an exception signaled by the current {@code Observable} is delayed until the regular elements are consumed + * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped * @param bufferSize * the hint about how many elements to expect to be skipped - * @return an Observable that drops those items emitted by the source ObservableSource in a time window before the + * @return an {@code Observable} that drops those items emitted by the current {@code Observable} in a time window before the * source completes defined by {@code time} and {@code scheduler} + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: SkipLast */ @CheckReturnValue @@ -12202,7 +12574,7 @@ public final Observable skipLast(long time, @NonNull TimeUnit unit, @NonNull } /** - * Returns an Observable that skips items emitted by the source ObservableSource until a second ObservableSource emits + * Returns an {@code Observable} that skips items emitted by the current {@code Observable} until a second {@link ObservableSource} emits * an item. *

* @@ -12211,12 +12583,13 @@ public final Observable skipLast(long time, @NonNull TimeUnit unit, @NonNull *

{@code skipUntil} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the element type of the other ObservableSource + * @param the element type of the other {@code ObservableSource} * @param other - * the second ObservableSource that has to emit an item before the source ObservableSource's elements begin - * to be mirrored by the resulting ObservableSource - * @return an Observable that skips items from the source ObservableSource until the second ObservableSource emits an + * the second {@code ObservableSource} that has to emit an item before the current {@code Observable}'s elements begin + * to be mirrored by the resulting {@code Observable} + * @return an {@code Observable} that skips items from the current {@code Observable} until the second {@code ObservableSource} emits an * item, then emits the remaining items + * @throws NullPointerException if {@code other} is {@code null} * @see ReactiveX operators documentation: SkipUntil */ @CheckReturnValue @@ -12228,8 +12601,8 @@ public final Observable skipUntil(@NonNull ObservableSource other) { } /** - * Returns an Observable that skips all items emitted by the source ObservableSource as long as a specified - * condition holds true, but emits all further source items as soon as the condition becomes false. + * Returns an {@code Observable} that skips all items emitted by the current {@code Observable} as long as a specified + * condition holds {@code true}, but emits all further source items as soon as the condition becomes {@code false}. *

* *

@@ -12238,9 +12611,10 @@ public final Observable skipUntil(@NonNull ObservableSource other) { *
* * @param predicate - * a function to test each item emitted from the source ObservableSource - * @return an Observable that begins emitting items emitted by the source ObservableSource when the specified - * predicate becomes false + * a function to test each item emitted from the current {@code Observable} + * @return an {@code Observable} that begins emitting items emitted by the current {@code Observable} when the specified + * predicate becomes {@code false} + * @throws NullPointerException if {@code predicate} is {@code null} * @see ReactiveX operators documentation: SkipWhile */ @CheckReturnValue @@ -12252,14 +12626,14 @@ public final Observable skipWhile(@NonNull Predicate predicate) { } /** - * Returns an Observable that emits the events emitted by source ObservableSource, in a - * sorted order. Each item emitted by the ObservableSource must implement {@link Comparable} with respect to all + * Returns an {@code Observable} that emits the events emitted by the current {@code Observable}, in a + * sorted order. Each item emitted by the current {@code Observable} must implement {@link Comparable} with respect to all * other items in the sequence. *

* *

- * If any item emitted by this Observable does not implement {@link Comparable} with respect to - * all other items emitted by this Observable, no items will be emitted and the + * If any item emitted by the current {@code Observable} does not implement {@code Comparable} with respect to + * all other items emitted by the current {@code Observable}, no items will be emitted and the * sequence is terminated with a {@link ClassCastException}. * *

Note that calling {@code sorted} with long, non-terminating or infinite sources @@ -12269,7 +12643,7 @@ public final Observable skipWhile(@NonNull Predicate predicate) { *

Scheduler:
*
{@code sorted} does not operate by default on a particular {@link Scheduler}.
*
- * @return an Observable that emits the items emitted by the source ObservableSource in sorted order + * @return an {@code Observable} that emits the items emitted by the current {@code Observable} in sorted order */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -12279,7 +12653,7 @@ public final Observable sorted() { } /** - * Returns an Observable that emits the events emitted by source ObservableSource, in a + * Returns an {@code Observable} that emits the events emitted by the current {@code Observable}, in a * sorted order based on a specified comparison function. * *

Note that calling {@code sorted} with long, non-terminating or infinite sources @@ -12291,9 +12665,10 @@ public final Observable sorted() { *

* * @param sortFunction - * a function that compares two items emitted by the source ObservableSource and returns an Integer + * a function that compares two items emitted by the current {@code Observable} and returns an {@code int} * that indicates their sort order - * @return an Observable that emits the items emitted by the source ObservableSource in sorted order + * @throws NullPointerException if {@code sortFunction} is {@code null} + * @return an {@code Observable} that emits the items emitted by the current {@code Observable} in sorted order */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -12304,8 +12679,8 @@ public final Observable sorted(@NonNull Comparator sortFunction) { } /** - * Returns an Observable that emits the items in a specified {@link Iterable} before it begins to emit items - * emitted by the source ObservableSource. + * Returns an {@code Observable} that emits the items in a specified {@link Iterable} before it begins to emit items + * emitted by the current {@code Observable}. *

* *

@@ -12314,9 +12689,10 @@ public final Observable sorted(@NonNull Comparator sortFunction) { *
* * @param items - * an Iterable that contains the items you want the modified ObservableSource to emit first - * @return an Observable that emits the items in the specified {@link Iterable} and then emits the items - * emitted by the source ObservableSource + * an {@code Iterable} that contains the items you want the resulting {@code Observable} to emit first + * @return an {@code Observable} that emits the items in the specified {@code Iterable} and then emits the items + * emitted by the current {@code Observable} + * @throws NullPointerException if {@code items} is {@code null} * @see ReactiveX operators documentation: StartWith * @since 3.0.0 * @see #startWithItem(Object) @@ -12330,8 +12706,8 @@ public final Observable startWithIterable(@NonNull Iterable item } /** - * Returns an Observable that emits the items in a specified {@link ObservableSource} before it begins to emit - * items emitted by the source ObservableSource. + * Returns an {@code Observable} that emits the items in a specified {@link ObservableSource} before it begins to emit + * items emitted by the current {@code Observable}. *

* *

@@ -12340,9 +12716,10 @@ public final Observable startWithIterable(@NonNull Iterable item *
* * @param other - * an ObservableSource that contains the items you want the modified ObservableSource to emit first - * @return an Observable that emits the items in the specified {@link ObservableSource} and then emits the items - * emitted by the source ObservableSource + * an {@code ObservableSource} that contains the items you want the modified {@code ObservableSource} to emit first + * @return an {@code Observable} that emits the items in the specified {@code ObservableSource} and then emits the items + * emitted by the current {@code Observable} + * @throws NullPointerException if {@code other} is {@code null} * @see ReactiveX operators documentation: StartWith */ @CheckReturnValue @@ -12354,8 +12731,8 @@ public final Observable startWith(@NonNull ObservableSource othe } /** - * Returns an Observable that emits a specified item before it begins to emit items emitted by the source - * ObservableSource. + * Returns an {@code Observable} that emits a specified item before it begins to emit items emitted by the current + * {@code Observable}. *

* *

@@ -12365,8 +12742,9 @@ public final Observable startWith(@NonNull ObservableSource othe * * @param item * the item to emit first - * @return an Observable that emits the specified item before it begins to emit items emitted by the source - * ObservableSource + * @return an {@code Observable} that emits the specified item before it begins to emit items emitted by the current + * {@code Observable} + * @throws NullPointerException if {@code item} is {@code null} * @see ReactiveX operators documentation: StartWith * @see #startWithArray(Object...) * @see #startWithIterable(Iterable) @@ -12376,13 +12754,12 @@ public final Observable startWith(@NonNull ObservableSource othe @SchedulerSupport(SchedulerSupport.NONE) @NonNull public final Observable startWithItem(@NonNull T item) { - Objects.requireNonNull(item, "item is null"); return concatArray(just(item), this); } /** - * Returns an Observable that emits the specified items before it begins to emit items emitted by the source - * ObservableSource. + * Returns an {@code Observable} that emits the specified items before it begins to emit items emitted by the current + * {@code Observable}. *

* *

@@ -12392,8 +12769,9 @@ public final Observable startWithItem(@NonNull T item) { * * @param items * the array of values to emit first - * @return an Observable that emits the specified items before it begins to emit items emitted by the source - * ObservableSource + * @return an {@code Observable} that emits the specified items before it begins to emit items emitted by the current + * {@code Observable} + * @throws NullPointerException if {@code items} is {@code null} * @see ReactiveX operators documentation: StartWith * @see #startWithItem(Object) * @see #startWithIterable(Iterable) @@ -12411,18 +12789,18 @@ public final Observable startWithArray(@NonNull T... items) { } /** - * Subscribes to an ObservableSource and ignores {@code onNext} and {@code onComplete} emissions. + * Subscribes to the current {@code Observable} and ignores {@code onNext} and {@code onComplete} emissions. *

- * If the Observable emits an error, it is wrapped into an - * {@link io.reactivex.rxjava3.exceptions.OnErrorNotImplementedException OnErrorNotImplementedException} - * and routed to the RxJavaPlugins.onError handler. + * If the {@code Observable} emits an error, it is wrapped into an + * {@link OnErrorNotImplementedException} + * and routed to the {@link RxJavaPlugins#onError(Throwable)} handler. *

*
Scheduler:
*
{@code subscribe} does not operate by default on a particular {@link Scheduler}.
*
* * @return a {@link Disposable} reference with which the caller can stop receiving items before - * the ObservableSource has finished sending them + * the current {@code Observable} has finished sending them * @see ReactiveX operators documentation: Subscribe */ @SchedulerSupport(SchedulerSupport.NONE) @@ -12432,22 +12810,22 @@ public final Disposable subscribe() { } /** - * Subscribes to an ObservableSource and provides a callback to handle the items it emits. + * Subscribes to the current {@code Observable} and provides a callback to handle the items it emits. *

- * If the Observable emits an error, it is wrapped into an - * {@link io.reactivex.rxjava3.exceptions.OnErrorNotImplementedException OnErrorNotImplementedException} - * and routed to the RxJavaPlugins.onError handler. + * If the {@code Observable} emits an error, it is wrapped into an + * {@link OnErrorNotImplementedException} + * and routed to the {@link RxJavaPlugins#onError(Throwable)} handler. *

*
Scheduler:
*
{@code subscribe} does not operate by default on a particular {@link Scheduler}.
*
* * @param onNext - * the {@code Consumer} you have designed to accept emissions from the ObservableSource + * the {@code Consumer} you have designed to accept emissions from the current {@code Observable} * @return a {@link Disposable} reference with which the caller can stop receiving items before - * the ObservableSource has finished sending them + * the current {@code Observable} has finished sending them * @throws NullPointerException - * if {@code onNext} is null + * if {@code onNext} is {@code null} * @see ReactiveX operators documentation: Subscribe */ @CheckReturnValue @@ -12458,24 +12836,23 @@ public final Disposable subscribe(@NonNull Consumer onNext) { } /** - * Subscribes to an ObservableSource and provides callbacks to handle the items it emits and any error - * notification it issues. + * Subscribes to the current {@code Observable} and provides callbacks to handle the items it emits and any error + * notification it signals. *
*
Scheduler:
*
{@code subscribe} does not operate by default on a particular {@link Scheduler}.
*
* * @param onNext - * the {@code Consumer} you have designed to accept emissions from the ObservableSource + * the {@code Consumer} you have designed to accept emissions from the current {@code Observable} * @param onError - * the {@code Consumer} you have designed to accept any error notification from the - * ObservableSource + * the {@code Consumer} you have designed to accept any error notification from the current + * {@code Observable} * @return a {@link Disposable} reference with which the caller can stop receiving items before - * the ObservableSource has finished sending them + * the current {@code Observable} has finished sending them * @see ReactiveX operators documentation: Subscribe * @throws NullPointerException - * if {@code onNext} is null, or - * if {@code onError} is null + * if {@code onNext} or {@code onError} is {@code null} */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -12485,27 +12862,25 @@ public final Disposable subscribe(@NonNull Consumer onNext, @NonNull } /** - * Subscribes to an ObservableSource and provides callbacks to handle the items it emits and any error or - * completion notification it issues. + * Subscribes to the current {@code Observable} and provides callbacks to handle the items it emits and any error or + * completion notification it signals. *
*
Scheduler:
*
{@code subscribe} does not operate by default on a particular {@link Scheduler}.
*
* * @param onNext - * the {@code Consumer} you have designed to accept emissions from the ObservableSource + * the {@code Consumer} you have designed to accept emissions from the current {@code Observable} * @param onError - * the {@code Consumer} you have designed to accept any error notification from the - * ObservableSource + * the {@code Consumer} you have designed to accept any error notification from the current + * {@code Observable} * @param onComplete - * the {@code Action} you have designed to accept a completion notification from the - * ObservableSource + * the {@link Action} you have designed to accept a completion notification from the current + * {@code Observable} * @return a {@link Disposable} reference with which the caller can stop receiving items before - * the ObservableSource has finished sending them + * the current {@code Observable} has finished sending them * @throws NullPointerException - * if {@code onNext} is null, or - * if {@code onError} is null, or - * if {@code onComplete} is null + * if {@code onNext}, {@code onError} or {@code onComplete} is {@code null} * @see ReactiveX operators documentation: Subscribe */ @CheckReturnValue @@ -12554,13 +12929,13 @@ public final void subscribe(@NonNull Observer observer) { *

There is no need to call any of the plugin hooks on the current {@code Observable} instance or * the {@code Observer}; all hooks and basic safeguards have been * applied by {@link #subscribe(Observer)} before this method gets called. - * @param observer the incoming Observer, never null + * @param observer the incoming {@code Observer}, never {@code null} */ protected abstract void subscribeActual(@NonNull Observer observer); /** - * Subscribes a given Observer (subclass) to this Observable and returns the given - * Observer as is. + * Subscribes a given {@link Observer} (subclass) to the current {@code Observable} and returns the given + * {@code Observer} instance as is. *

Usage example: * 


      * Observable<Integer> source = Observable.range(1, 10);
@@ -12576,10 +12951,10 @@ public final void subscribe(@NonNull Observer observer) {
      *  
Scheduler:

      *  
{@code subscribeWith} does not operate by default on a particular {@link Scheduler}.

      *
- * @param the type of the Observer to use and return - * @param observer the Observer (subclass) to use and return, not null + * @param the type of the {@code Observer} to use and return + * @param observer the {@code Observer} (subclass) to use and return, not {@code null} * @return the input {@code observer} - * @throws NullPointerException if {@code observer} is null + * @throws NullPointerException if {@code observer} is {@code null} * @since 2.0 */ @CheckReturnValue @@ -12591,18 +12966,19 @@ public final void subscribe(@NonNull Observer observer) { } /** - * Asynchronously subscribes Observers to this ObservableSource on the specified {@link Scheduler}. + * Asynchronously subscribes {@link Observer}s to the current {@code Observable} on the specified {@link Scheduler}. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param scheduler - * the {@link Scheduler} to perform subscription actions on - * @return the source ObservableSource modified so that its subscriptions happen on the - * specified {@link Scheduler} + * the {@code Scheduler} to perform subscription actions on + * @return the current {@code Observable} modified so that its subscriptions happen on the + * specified {@code Scheduler} + * @throws NullPointerException if {@code scheduler} is {@code null} * @see ReactiveX operators documentation: SubscribeOn * @see RxJava Threading Examples * @see #observeOn @@ -12616,8 +12992,8 @@ public final Observable subscribeOn(@NonNull Scheduler scheduler) { } /** - * Returns an Observable that emits the items emitted by the source ObservableSource or the items of an alternate - * ObservableSource if the source ObservableSource is empty. + * Returns an {@code Observable} that emits the items emitted by the current {@code Observable} or the items of an alternate + * {@link ObservableSource} if the current {@code Observable} is empty. *

* *

@@ -12626,9 +13002,10 @@ public final Observable subscribeOn(@NonNull Scheduler scheduler) { *
* * @param other - * the alternate ObservableSource to subscribe to if the source does not emit any items - * @return an ObservableSource that emits the items emitted by the source ObservableSource or the items of an - * alternate ObservableSource if the source ObservableSource is empty. + * the alternate {@code ObservableSource} to subscribe to if the source does not emit any items + * @return an {@code Observable} that emits the items emitted by the current {@code Observable} or the items of an + * alternate {@code ObservableSource} if the current {@code Observable} is empty. + * @throws NullPointerException if {@code other} is {@code null} * @since 1.1.0 */ @CheckReturnValue @@ -12640,12 +13017,12 @@ public final Observable switchIfEmpty(@NonNull ObservableSource } /** - * Returns a new ObservableSource by applying a function that you supply to each item emitted by the source - * ObservableSource that returns an ObservableSource, and then emitting the items emitted by the most recently emitted - * of these ObservableSources. + * Returns a new {@code Observable} by applying a function that you supply to each item emitted by the current + * {@code Observable} that returns an {@link ObservableSource}, and then emitting the items emitted by the most recently emitted + * of these {@code ObservableSource}s. *

- * The resulting ObservableSource completes if both the upstream ObservableSource and the last inner ObservableSource, if any, complete. - * If the upstream ObservableSource signals an onError, the inner ObservableSource is disposed and the error delivered in-sequence. + * The resulting {@code Observable} completes if both the current {@code Observable} and the last inner {@code ObservableSource}, if any, complete. + * If the current {@code Observable} signals an {@code onError}, the inner {@code ObservableSource} is disposed and the error delivered in-sequence. *

* *

@@ -12653,11 +13030,12 @@ public final Observable switchIfEmpty(@NonNull ObservableSource *
{@code switchMap} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the element type of the inner ObservableSources and the output + * @param the element type of the inner {@code ObservableSource}s and the output * @param mapper - * a function that, when applied to an item emitted by the source ObservableSource, returns an - * ObservableSource - * @return an Observable that emits the items emitted by the ObservableSource returned from applying {@code func} to the most recently emitted item emitted by the source ObservableSource + * a function that, when applied to an item emitted by the current {@code Observable}, returns an + * {@code ObservableSource} + * @return an {@code Observable} that emits the items emitted by the {@code ObservableSource} returned from applying {@code mapper} to the most recently emitted item emitted by the current {@code Observable} + * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: FlatMap * @see #switchMapDelayError(Function) */ @@ -12669,12 +13047,12 @@ public final Observable switchMap(@NonNull Function - * The resulting ObservableSource completes if both the upstream ObservableSource and the last inner ObservableSource, if any, complete. - * If the upstream ObservableSource signals an onError, the inner ObservableSource is disposed and the error delivered in-sequence. + * The resulting {@code Observable} completes if both the current {@code Observable} and the last inner {@code ObservableSource}, if any, complete. + * If the current {@code Observable} signals an {@code onError}, the inner {@code ObservableSource} is disposed and the error delivered in-sequence. *

* *

@@ -12682,13 +13060,15 @@ public final Observable switchMap(@NonNull Function{@code switchMap} does not operate by default on a particular {@link Scheduler}. *
* - * @param the element type of the inner ObservableSources and the output + * @param the element type of the inner {@code ObservableSource}s and the output * @param mapper - * a function that, when applied to an item emitted by the source ObservableSource, returns an - * ObservableSource + * a function that, when applied to an item emitted by the current {@code Observable}, returns an + * {@code ObservableSource} * @param bufferSize - * the number of elements to prefetch from the current active inner ObservableSource - * @return an Observable that emits the items emitted by the ObservableSource returned from applying {@code func} to the most recently emitted item emitted by the source ObservableSource + * the number of elements expected from the current active inner {@code ObservableSource} to be buffered + * @return an {@code Observable} that emits the items emitted by the {@code ObservableSource} returned from applying {@code mapper} to the most recently emitted item emitted by the current {@code Observable} + * @throws NullPointerException if {@code mapper} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: FlatMap * @see #switchMapDelayError(Function, int) */ @@ -12710,7 +13090,7 @@ public final Observable switchMap(@NonNull Function @@ -12719,27 +13099,28 @@ public final Observable switchMap(@NonNull Function *
Scheduler:
*
{@code switchMapCompletable} does not operate by default on a particular {@link Scheduler}.
*
Error handling:
- *
If either this {@code Observable} or the active {@code CompletableSource} signals an {@code onError}, - * the resulting {@code Completable} is terminated immediately with that {@code Throwable}. + *
If either the current {@code Observable} or the active {@code CompletableSource} signals an {@code onError}, + * the resulting {@code Completable} is terminated immediately with that {@link Throwable}. * Use the {@link #switchMapCompletableDelayError(Function)} to delay such inner failures until * every inner {@code CompletableSource}s and the main {@code Observable} terminates in some fashion. * If they fail concurrently, the operator may combine the {@code Throwable}s into a - * {@link io.reactivex.rxjava3.exceptions.CompositeException CompositeException} + * {@link CompositeException} * and signal it to the downstream instead. If any inactivated (switched out) {@code CompletableSource} - * signals an {@code onError} late, the {@code Throwable}s will be signalled to the global error handler via - * {@link RxJavaPlugins#onError(Throwable)} method as {@code UndeliverableException} errors. + * signals an {@code onError} late, the {@code Throwable}s will be signaled to the global error handler via + * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. *
*
*

History: 2.1.11 - experimental * @param mapper the function called with each upstream item and should return a - * {@link CompletableSource} to be subscribed to and awaited for + * {@code CompletableSource} to be subscribed to and awaited for * (non blockingly) for its terminal event - * @return the new Completable instance + * @return the new {@code Completable} instance + * @throws NullPointerException if {@code mapper} is {@code null} * @see #switchMapCompletableDelayError(Function) * @since 2.2 */ @@ -12762,27 +13143,28 @@ public final Completable switchMapCompletable(@NonNull Function *

Scheduler:
*
{@code switchMapCompletableDelayError} does not operate by default on a particular {@link Scheduler}.
*
Error handling:
- *
Errors of this {@code Observable} and all the {@code CompletableSource}s, who had the chance + *
The errors of the current {@code Observable} and all the {@code CompletableSource}s, who had the chance * to run to their completion, are delayed until * all of them terminate in some fashion. At this point, if there was only one failure, the respective - * {@code Throwable} is emitted to the downstream. It there were more than one failures, the - * operator combines all {@code Throwable}s into a {@link io.reactivex.rxjava3.exceptions.CompositeException CompositeException} + * {@link Throwable} is emitted to the downstream. It there were more than one failures, the + * operator combines all {@code Throwable}s into a {@link CompositeException} * and signals that to the downstream. * If any inactivated (switched out) {@code CompletableSource} - * signals an {@code onError} late, the {@code Throwable}s will be signalled to the global error handler via - * {@link RxJavaPlugins#onError(Throwable)} method as {@code UndeliverableException} errors. + * signals an {@code onError} late, the {@code Throwable}s will be signaled to the global error handler via + * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. *
*
*

History: 2.1.11 - experimental * @param mapper the function called with each upstream item and should return a - * {@link CompletableSource} to be subscribed to and awaited for + * {@code CompletableSource} to be subscribed to and awaited for * (non blockingly) for its terminal event - * @return the new Completable instance + * @return the new {@code Completable} instance + * @throws NullPointerException if {@code mapper} is {@code null} * @see #switchMapCompletable(Function) * @since 2.2 */ @@ -12795,9 +13177,9 @@ public final Completable switchMapCompletableDelayError(@NonNull Function * @@ -12805,21 +13187,22 @@ public final Completable switchMapCompletableDelayError(@NonNull FunctionScheduler: *

{@code switchMapMaybe} does not operate by default on a particular {@link Scheduler}.
*
Error handling:
- *
This operator terminates with an {@code onError} if this {@code Observable} or any of + *
This operator terminates with an {@code onError} if the current {@code Observable} or any of * the inner {@code MaybeSource}s fail while they are active. When this happens concurrently, their - * individual {@code Throwable} errors may get combined and emitted as a single - * {@link io.reactivex.rxjava3.exceptions.CompositeException CompositeException}. Otherwise, a late - * (i.e., inactive or switched out) {@code onError} from this {@code Observable} or from any of + * individual {@link Throwable} errors may get combined and emitted as a single + * {@link CompositeException}. Otherwise, a late + * (i.e., inactive or switched out) {@code onError} from the current {@code Observable} or from any of * the inner {@code MaybeSource}s will be forwarded to the global error handler via - * {@link io.reactivex.rxjava3.plugins.RxJavaPlugins#onError(Throwable)} as - * {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}
+ * {@link RxJavaPlugins#onError(Throwable)} as + * {@link UndeliverableException} *
*

History: 2.1.11 - experimental * @param the output value type * @param mapper the function called with the current upstream event and should * return a {@code MaybeSource} to replace the current active inner source * and get subscribed to. - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code mapper} is {@code null} * @see #switchMapMaybeDelayError(Function) * @since 2.2 */ @@ -12834,7 +13217,7 @@ public final Observable switchMapMaybe(@NonNull Function * *

@@ -12846,7 +13229,8 @@ public final Observable switchMapMaybe(@NonNull Function Observable switchMapMaybeDelayError(@NonNull Function - * The resulting ObservableSource completes if both the upstream ObservableSource and the last inner SingleSource, if any, complete. - * If the upstream ObservableSource signals an onError, the inner SingleSource is disposed and the error delivered in-sequence. + * The resulting {@code Observable} completes if both the current {@code Observable} and the last inner {@code SingleSource}, if any, complete. + * If the current {@code Observable} signals an {@code onError}, the inner {@code SingleSource} is disposed and the error delivered in-sequence. *

* *

@@ -12872,11 +13256,12 @@ public final Observable switchMapMaybeDelayError(@NonNull Function{@code switchMapSingle} does not operate by default on a particular {@link Scheduler}. *
*

History: 2.0.8 - experimental - * @param the element type of the inner SingleSources and the output + * @param the element type of the inner {@code SingleSource}s and the output * @param mapper - * a function that, when applied to an item emitted by the source ObservableSource, returns a - * SingleSource - * @return an Observable that emits the item emitted by the SingleSource returned from applying {@code func} to the most recently emitted item emitted by the source ObservableSource + * a function that, when applied to an item emitted by the current {@code Observable}, returns a + * {@code SingleSource} + * @return an {@code Observable} that emits the item emitted by the {@code SingleSource} returned from applying {@code mapper} to the most recently emitted item emitted by the current {@code Observable} + * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: FlatMap * @see #switchMapSingleDelayError(Function) * @since 2.2 @@ -12890,13 +13275,13 @@ public final Observable switchMapSingle(@NonNull Function - * The resulting ObservableSource completes if both the upstream ObservableSource and the last inner SingleSource, if any, complete. - * If the upstream ObservableSource signals an onError, the termination of the last inner SingleSource will emit that error as is - * or wrapped into a CompositeException along with the other possible errors the former inner SingleSources signalled. + * The resulting {@code Observable} completes if both the current {@code Observable} and the last inner {@code SingleSource}, if any, complete. + * If the current {@code Observable} signals an {@code onError}, the termination of the last inner {@code SingleSource} will emit that error as is + * or wrapped into a {@link CompositeException} along with the other possible errors the former inner {@code SingleSource}s signaled. *

* *

@@ -12904,11 +13289,13 @@ public final Observable switchMapSingle(@NonNull Function{@code switchMapSingleDelayError} does not operate by default on a particular {@link Scheduler}. *
*

History: 2.0.8 - experimental - * @param the element type of the inner SingleSources and the output + * @param the element type of the inner {@code SingleSource}s and the output * @param mapper - * a function that, when applied to an item emitted by the source ObservableSource, returns a - * SingleSource - * @return an Observable that emits the item emitted by the SingleSource returned from applying {@code func} to the most recently emitted item emitted by the source ObservableSource + * a function that, when applied to an item emitted by the current {@code Observable}, returns a + * {@code SingleSource} + * @return an {@code Observable} that emits the item emitted by the {@code SingleSource} returned from applying {@code mapper} + * to the most recently emitted item emitted by the current {@code Observable} + * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: FlatMap * @see #switchMapSingle(Function) * @since 2.2 @@ -12922,13 +13309,13 @@ public final Observable switchMapSingleDelayError(@NonNull Function - * The resulting ObservableSource completes if both the upstream ObservableSource and the last inner ObservableSource, if any, complete. - * If the upstream ObservableSource signals an onError, the termination of the last inner ObservableSource will emit that error as is - * or wrapped into a CompositeException along with the other possible errors the former inner ObservableSources signalled. + * The resulting {@code Observable} completes if both the current {@code Observable} and the last inner {@code ObservableSource}, if any, complete. + * If the current {@code Observable} signals an {@code onError}, the termination of the last inner {@code ObservableSource} will emit that error as is + * or wrapped into a {@link CompositeException} along with the other possible errors the former inner {@code ObservableSource}s signaled. *

* *

@@ -12936,11 +13323,13 @@ public final Observable switchMapSingleDelayError(@NonNull Function{@code switchMapDelayError} does not operate by default on a particular {@link Scheduler}. *
* - * @param the element type of the inner ObservableSources and the output + * @param the element type of the inner {@code ObservableSource}s and the output * @param mapper - * a function that, when applied to an item emitted by the source ObservableSource, returns an - * ObservableSource - * @return an Observable that emits the items emitted by the ObservableSource returned from applying {@code func} to the most recently emitted item emitted by the source ObservableSource + * a function that, when applied to an item emitted by the current {@code Observable}, returns an + * {@code ObservableSource} + * @return an {@code Observable} that emits the items emitted by the {@code ObservableSource} returned from applying {@code mapper} + * to the most recently emitted item emitted by the current {@code Observable} + * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: FlatMap * @see #switchMap(Function) * @since 2.0 @@ -12953,13 +13342,13 @@ public final Observable switchMapDelayError(@NonNull Function - * The resulting ObservableSource completes if both the upstream ObservableSource and the last inner ObservableSource, if any, complete. - * If the upstream ObservableSource signals an onError, the termination of the last inner ObservableSource will emit that error as is - * or wrapped into a CompositeException along with the other possible errors the former inner ObservableSources signalled. + * The resulting {@code Observable} completes if both the current {@code Observable} and the last inner {@code ObservableSource}, if any, complete. + * If the current {@code Observable} signals an {@code onError}, the termination of the last inner {@code ObservableSource} will emit that error as is + * or wrapped into a {@link CompositeException} along with the other possible errors the former inner {@code ObservableSource}s signaled. *

* *

@@ -12967,13 +13356,15 @@ public final Observable switchMapDelayError(@NonNull Function{@code switchMapDelayError} does not operate by default on a particular {@link Scheduler}. *
* - * @param the element type of the inner ObservableSources and the output + * @param the element type of the inner {@code ObservableSource}s and the output * @param mapper - * a function that, when applied to an item emitted by the source ObservableSource, returns an - * ObservableSource + * a function that, when applied to an item emitted by the current {@code Observable}, returns an + * {@code ObservableSource} * @param bufferSize - * the number of elements to prefetch from the current active inner ObservableSource - * @return an Observable that emits the items emitted by the ObservableSource returned from applying {@code func} to the most recently emitted item emitted by the source ObservableSource + * the number of elements expected from the current active inner {@code ObservableSource} to be buffered + * @return an {@code Observable} that emits the items emitted by the {@code ObservableSource} returned from applying {@code mapper} to the most recently emitted item emitted by the current {@code Observable} + * @throws NullPointerException if {@code mapper} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: FlatMap * @see #switchMap(Function, int) * @since 2.0 @@ -12996,14 +13387,18 @@ public final Observable switchMapDelayError(@NonNull Function * *

- * This method returns an ObservableSource that will invoke a subscribing {@link Observer}'s + * This method returns an {@code Observable} that will invoke a subscribing {@link Observer}'s * {@link Observer#onNext onNext} function a maximum of {@code count} times before invoking * {@link Observer#onComplete onComplete}. + *

+ * Taking {@code 0} items from the current {@code Observable} will still subscribe to it, allowing the + * subscription-time side-effects to happen there, but will be immediately disposed and the downstream completed + * without any item emission. *

*
Scheduler:
*
This version of {@code take} does not operate by default on a particular {@link Scheduler}.
@@ -13011,8 +13406,9 @@ public final Observable switchMapDelayError(@NonNull FunctionReactiveX operators documentation: Take */ @CheckReturnValue @@ -13026,7 +13422,7 @@ public final Observable take(long count) { } /** - * Returns an Observable that emits those items emitted by source ObservableSource before a specified time runs + * Returns an {@code Observable} that emits those items emitted by the current {@code Observable} before a specified time runs * out. *

* If time runs out before the {@code Observable} completes normally, the {@code onComplete} event will be @@ -13035,14 +13431,15 @@ public final Observable take(long count) { * *

*
Scheduler:
- *
This version of {@code take} operates by default on the {@code computation} {@link Scheduler}.
+ *
This version of {@code take} operates by default on the {@code computation} {@code Scheduler}.
*
* * @param time * the length of the time window * @param unit * the time unit of {@code time} - * @return an Observable that emits those items emitted by the source ObservableSource before the time runs out + * @return an {@code Observable} that emits those items emitted by the current {@code Observable} before the time runs out + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: Take */ @CheckReturnValue @@ -13053,16 +13450,16 @@ public final Observable take(long time, @NonNull TimeUnit unit) { } /** - * Returns an Observable that emits those items emitted by source ObservableSource before a specified time (on a - * specified Scheduler) runs out. + * Returns an {@code Observable} that emits those items emitted by the current {@code Observable} before a specified time (on a + * specified {@link Scheduler}) runs out. *

* If time runs out before the {@code Observable} completes normally, the {@code onComplete} event will be - * signaled on the provided {@link Scheduler}. + * signaled on the provided {@code Scheduler}. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param time @@ -13070,9 +13467,10 @@ public final Observable take(long time, @NonNull TimeUnit unit) { * @param unit * the time unit of {@code time} * @param scheduler - * the Scheduler used for time source - * @return an Observable that emits those items emitted by the source ObservableSource before the time runs out, - * according to the specified Scheduler + * the {@code Scheduler} used for time source + * @return an {@code Observable} that emits those items emitted by the current {@code Observable} before the time runs out, + * according to the specified {@code Scheduler} + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Take */ @CheckReturnValue @@ -13083,8 +13481,8 @@ public final Observable take(long time, @NonNull TimeUnit unit, @NonNull Sche } /** - * Returns an Observable that emits at most the last {@code count} items emitted by the source ObservableSource. If the source emits fewer than - * {@code count} items then all of its items are emitted. + * Returns an {@code Observable} that emits at most the last {@code count} items emitted by the current {@code Observable}. + * If the source emits fewer than {@code count} items then all of its items are emitted. *

* *

@@ -13093,11 +13491,11 @@ public final Observable take(long time, @NonNull TimeUnit unit, @NonNull Sche *
* * @param count - * the maximum number of items to emit from the end of the sequence of items emitted by the source - * ObservableSource - * @return an Observable that emits at most the last {@code count} items emitted by the source ObservableSource - * @throws IndexOutOfBoundsException - * if {@code count} is less than zero + * the maximum number of items to emit from the end of the sequence of items emitted by the current + * {@code Observable} + * @return an {@code Observable} that emits at most the last {@code count} items emitted by the current {@code Observable} + * @throws IllegalArgumentException + * if {@code count} is negative * @see ReactiveX operators documentation: TakeLast */ @CheckReturnValue @@ -13105,7 +13503,7 @@ public final Observable take(long time, @NonNull TimeUnit unit, @NonNull Sche @NonNull public final Observable takeLast(int count) { if (count < 0) { - throw new IndexOutOfBoundsException("count >= 0 required but it was " + count); + throw new IllegalArgumentException("count >= 0 required but it was " + count); } if (count == 0) { return RxJavaPlugins.onAssembly(new ObservableIgnoreElements<>(this)); @@ -13117,14 +13515,14 @@ public final Observable takeLast(int count) { } /** - * Returns an Observable that emits at most a specified number of items from the source ObservableSource that were - * emitted in a specified window of time before the ObservableSource completed. + * Returns an {@code Observable} that emits at most a specified number of items from the current {@code Observable} that were + * emitted in a specified window of time before the current {@code Observable} completed. *

* *

*
Scheduler:
*
{@code takeLast} does not operate on any particular scheduler but uses the current time - * from the {@code computation} {@link Scheduler}.
+ * from the {@code trampoline} {@link Scheduler}. *
* * @param count @@ -13133,8 +13531,9 @@ public final Observable takeLast(int count) { * the length of the time window * @param unit * the time unit of {@code time} - * @return an Observable that emits at most {@code count} items from the source ObservableSource that were emitted - * in a specified window of time before the ObservableSource completed + * @return an {@code Observable} that emits at most {@code count} items from the current {@code Observable} that were emitted + * in a specified window of time before the current {@code Observable} completed + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: TakeLast */ @CheckReturnValue @@ -13145,14 +13544,14 @@ public final Observable takeLast(long count, long time, @NonNull TimeUnit uni } /** - * Returns an Observable that emits at most a specified number of items from the source ObservableSource that were - * emitted in a specified window of time before the ObservableSource completed, where the timing information is - * provided by a given Scheduler. + * Returns an {@code Observable} that emits at most a specified number of items from the current {@code Observable} that were + * emitted in a specified window of time before the current {@code Observable} completed, where the timing information is + * provided by a given {@link Scheduler}. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use for tracking the current time
+ *
You specify which {@code Scheduler} this operator will use for tracking the current time
*
* * @param count @@ -13162,12 +13561,13 @@ public final Observable takeLast(long count, long time, @NonNull TimeUnit uni * @param unit * the time unit of {@code time} * @param scheduler - * the {@link Scheduler} that provides the timestamps for the observed items - * @return an Observable that emits at most {@code count} items from the source ObservableSource that were emitted - * in a specified window of time before the ObservableSource completed, where the timing information is - * provided by the given {@code scheduler} - * @throws IndexOutOfBoundsException - * if {@code count} is less than zero + * the {@code Scheduler} that provides the timestamps for the observed items + * @return an {@code Observable} that emits at most {@code count} items from the current {@code Observable} that were emitted + * in a specified window of time before the current {@code Observable} completed, where the timing information is + * provided by the given {@code Scheduler} + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} + * @throws IllegalArgumentException + * if {@code count} is negative * @see ReactiveX operators documentation: TakeLast */ @CheckReturnValue @@ -13178,14 +13578,14 @@ public final Observable takeLast(long count, long time, @NonNull TimeUnit uni } /** - * Returns an Observable that emits at most a specified number of items from the source ObservableSource that were - * emitted in a specified window of time before the ObservableSource completed, where the timing information is - * provided by a given Scheduler. + * Returns an {@code Observable} that emits at most a specified number of items from the current {@code Observable} that were + * emitted in a specified window of time before the current {@code Observable} completed, where the timing information is + * provided by a given {@link Scheduler}. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use for tracking the current time
+ *
You specify which {@code Scheduler} this operator will use for tracking the current time
*
* * @param count @@ -13195,17 +13595,18 @@ public final Observable takeLast(long count, long time, @NonNull TimeUnit uni * @param unit * the time unit of {@code time} * @param scheduler - * the {@link Scheduler} that provides the timestamps for the observed items + * the {@code Scheduler} that provides the timestamps for the observed items * @param delayError - * if true, an exception signalled by the current Observable is delayed until the regular elements are consumed - * by the downstream; if false, an exception is immediately signalled and all regular elements dropped + * if {@code true}, an exception signaled by the current {@code Observable} is delayed until the regular elements are consumed + * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped * @param bufferSize * the hint about how many elements to expect to be last - * @return an Observable that emits at most {@code count} items from the source ObservableSource that were emitted - * in a specified window of time before the ObservableSource completed, where the timing information is + * @return an {@code Observable} that emits at most {@code count} items from the current {@code Observable} that were emitted + * in a specified window of time before the current {@code Observable} completed, where the timing information is * provided by the given {@code scheduler} - * @throws IndexOutOfBoundsException - * if {@code count} is less than zero + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} + * @throws IllegalArgumentException + * if {@code count} is negative or {@code bufferSize} is non-positive * @see ReactiveX operators documentation: TakeLast */ @CheckReturnValue @@ -13216,27 +13617,28 @@ public final Observable takeLast(long count, long time, @NonNull TimeUnit uni Objects.requireNonNull(scheduler, "scheduler is null"); ObjectHelper.verifyPositive(bufferSize, "bufferSize"); if (count < 0) { - throw new IndexOutOfBoundsException("count >= 0 required but it was " + count); + throw new IllegalArgumentException("count >= 0 required but it was " + count); } return RxJavaPlugins.onAssembly(new ObservableTakeLastTimed<>(this, count, time, unit, scheduler, bufferSize, delayError)); } /** - * Returns an Observable that emits the items from the source ObservableSource that were emitted in a specified - * window of time before the ObservableSource completed. + * Returns an {@code Observable} that emits the items from the current {@code Observable} that were emitted in a specified + * window of time before the current {@code Observable} completed. *

* *

*
Scheduler:
- *
This version of {@code takeLast} operates by default on the {@code computation} {@link Scheduler}.
+ *
{@code takeLast} does not operate on any particular scheduler but uses the current time + * from the {@code trampoline} {@link Scheduler}.
*
* * @param time * the length of the time window * @param unit * the time unit of {@code time} - * @return an Observable that emits the items from the source ObservableSource that were emitted in the window of - * time before the ObservableSource completed specified by {@code time} + * @return an {@code Observable} that emits the items from the current {@code Observable} that were emitted in the window of + * time before the current {@code Observable} completed specified by {@code time} * @see ReactiveX operators documentation: TakeLast */ @CheckReturnValue @@ -13247,13 +13649,14 @@ public final Observable takeLast(long time, @NonNull TimeUnit unit) { } /** - * Returns an Observable that emits the items from the source ObservableSource that were emitted in a specified - * window of time before the ObservableSource completed. + * Returns an {@code Observable} that emits the items from the current {@code Observable} that were emitted in a specified + * window of time before the current {@code Observable} completed. *

* *

*
Scheduler:
- *
This version of {@code takeLast} operates by default on the {@code computation} {@link Scheduler}.
+ *
{@code takeLast} does not operate on any particular scheduler but uses the current time + * from the {@code trampoline} {@link Scheduler}.
*
* * @param time @@ -13261,10 +13664,10 @@ public final Observable takeLast(long time, @NonNull TimeUnit unit) { * @param unit * the time unit of {@code time} * @param delayError - * if true, an exception signalled by the current Observable is delayed until the regular elements are consumed - * by the downstream; if false, an exception is immediately signalled and all regular elements dropped - * @return an Observable that emits the items from the source ObservableSource that were emitted in the window of - * time before the ObservableSource completed specified by {@code time} + * if {@code true}, an exception signaled by the current {@code Observable} is delayed until the regular elements are consumed + * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped + * @return an {@code Observable} that emits the items from the current {@code Observable} that were emitted in the window of + * time before the current {@code Observable} completed specified by {@code time} * @see ReactiveX operators documentation: TakeLast */ @CheckReturnValue @@ -13275,14 +13678,14 @@ public final Observable takeLast(long time, @NonNull TimeUnit unit, boolean d } /** - * Returns an Observable that emits the items from the source ObservableSource that were emitted in a specified - * window of time before the ObservableSource completed, where the timing information is provided by a specified - * Scheduler. + * Returns an {@code Observable} that emits the items from the current {@code Observable} that were emitted in a specified + * window of time before the current {@code Observable} completed, where the timing information is provided by a specified + * {@link Scheduler}. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param time @@ -13290,9 +13693,9 @@ public final Observable takeLast(long time, @NonNull TimeUnit unit, boolean d * @param unit * the time unit of {@code time} * @param scheduler - * the Scheduler that provides the timestamps for the Observed items - * @return an Observable that emits the items from the source ObservableSource that were emitted in the window of - * time before the ObservableSource completed specified by {@code time}, where the timing information is + * the {@code Scheduler} that provides the timestamps for the observed items + * @return an {@code Observable} that emits the items from the current {@code Observable} that were emitted in the window of + * time before the current {@code Observable} completed specified by {@code time}, where the timing information is * provided by {@code scheduler} * @see ReactiveX operators documentation: TakeLast */ @@ -13304,14 +13707,14 @@ public final Observable takeLast(long time, @NonNull TimeUnit unit, @NonNull } /** - * Returns an Observable that emits the items from the source ObservableSource that were emitted in a specified - * window of time before the ObservableSource completed, where the timing information is provided by a specified - * Scheduler. + * Returns an {@code Observable} that emits the items from the current {@code Observable} that were emitted in a specified + * window of time before the current {@code Observable} completed, where the timing information is provided by a specified + * {@link Scheduler}. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param time @@ -13319,12 +13722,12 @@ public final Observable takeLast(long time, @NonNull TimeUnit unit, @NonNull * @param unit * the time unit of {@code time} * @param scheduler - * the Scheduler that provides the timestamps for the Observed items + * the {@code Scheduler} that provides the timestamps for the observed items * @param delayError - * if true, an exception signalled by the current Observable is delayed until the regular elements are consumed - * by the downstream; if false, an exception is immediately signalled and all regular elements dropped - * @return an Observable that emits the items from the source ObservableSource that were emitted in the window of - * time before the ObservableSource completed specified by {@code time}, where the timing information is + * if {@code true}, an exception signaled by the current {@code Observable} is delayed until the regular elements are consumed + * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped + * @return an {@code Observable} that emits the items from the current {@code Observable} that were emitted in the window of + * time before the current {@code Observable} completed specified by {@code time}, where the timing information is * provided by {@code scheduler} * @see ReactiveX operators documentation: TakeLast */ @@ -13336,14 +13739,14 @@ public final Observable takeLast(long time, @NonNull TimeUnit unit, @NonNull } /** - * Returns an Observable that emits the items from the source ObservableSource that were emitted in a specified - * window of time before the ObservableSource completed, where the timing information is provided by a specified - * Scheduler. + * Returns an {@code Observable} that emits the items from the current {@code Observable} that were emitted in a specified + * window of time before the current {@code Observable} completed, where the timing information is provided by a specified + * {@link Scheduler}. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param time @@ -13351,14 +13754,14 @@ public final Observable takeLast(long time, @NonNull TimeUnit unit, @NonNull * @param unit * the time unit of {@code time} * @param scheduler - * the Scheduler that provides the timestamps for the Observed items + * the {@code Scheduler} that provides the timestamps for the observed items * @param delayError - * if true, an exception signalled by the current Observable is delayed until the regular elements are consumed - * by the downstream; if false, an exception is immediately signalled and all regular elements dropped + * if {@code true}, an exception signaled by the current {@code Observable} is delayed until the regular elements are consumed + * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped * @param bufferSize * the hint about how many elements to expect to be last - * @return an Observable that emits the items from the source ObservableSource that were emitted in the window of - * time before the ObservableSource completed specified by {@code time}, where the timing information is + * @return an {@code Observable} that emits the items from the current {@code Observable} that were emitted in the window of + * time before the current {@code Observable} completed specified by {@code time}, where the timing information is * provided by {@code scheduler} * @see ReactiveX operators documentation: TakeLast */ @@ -13370,7 +13773,7 @@ public final Observable takeLast(long time, @NonNull TimeUnit unit, @NonNull } /** - * Returns an Observable that emits the items emitted by the source Observable until a second ObservableSource + * Returns an {@code Observable} that emits the items emitted by the current {@code Observable} until a second {@link ObservableSource} * emits an item. *

* @@ -13380,11 +13783,12 @@ public final Observable takeLast(long time, @NonNull TimeUnit unit, @NonNull *

* * @param other - * the ObservableSource whose first emitted item will cause {@code takeUntil} to stop emitting items - * from the source Observable + * the {@code ObservableSource} whose first emitted item will cause {@code takeUntil} to stop emitting items + * from the current {@code Observable} * @param * the type of items emitted by {@code other} - * @return an Observable that emits the items emitted by the source Observable until such time as {@code other} emits its first item + * @return an {@code Observable} that emits the items emitted by the current {@code Observable} until such time as {@code other} emits its first item + * @throws NullPointerException if {@code other} is {@code null} * @see ReactiveX operators documentation: TakeUntil */ @CheckReturnValue @@ -13396,7 +13800,7 @@ public final Observable takeUntil(@NonNull ObservableSource other) { } /** - * Returns an Observable that emits items emitted by the source Observable, checks the specified predicate + * Returns an {@code Observable} that emits items emitted by the current {@code Observable}, checks the specified predicate * for each item, and then completes when the condition is satisfied. *

* @@ -13410,9 +13814,10 @@ public final Observable takeUntil(@NonNull ObservableSource other) { *

* * @param stopPredicate - * a function that evaluates an item emitted by the source Observable and returns a Boolean - * @return an Observable that first emits items emitted by the source Observable, checks the specified + * a function that evaluates an item emitted by the current {@code Observable} and returns a {@link Boolean} + * @return an {@code Observable} that first emits items emitted by the current {@code Observable}, checks the specified * condition after each item, and then completes when the condition is satisfied. + * @throws NullPointerException if {@code stopPredicate} is {@code null} * @see ReactiveX operators documentation: TakeUntil * @see Observable#takeWhile(Predicate) * @since 1.1.0 @@ -13426,7 +13831,7 @@ public final Observable takeUntil(@NonNull Predicate stopPredicate } /** - * Returns an Observable that emits items emitted by the source ObservableSource so long as each item satisfied a + * Returns an {@code Observable} that emits items emitted by the current {@code Observable} so long as each item satisfied a * specified condition, and then completes as soon as this condition is not satisfied. *

* @@ -13436,9 +13841,10 @@ public final Observable takeUntil(@NonNull Predicate stopPredicate *

* * @param predicate - * a function that evaluates an item emitted by the source ObservableSource and returns a Boolean - * @return an Observable that emits the items from the source ObservableSource so long as each item satisfies the + * a function that evaluates an item emitted by the current {@code Observable} and returns a {@link Boolean} + * @return an {@code Observable} that emits the items from the current {@code Observable} so long as each item satisfies the * condition defined by {@code predicate}, then completes + * @throws NullPointerException if {@code predicate} is {@code null} * @see ReactiveX operators documentation: TakeWhile * @see Observable#takeUntil(Predicate) */ @@ -13451,11 +13857,11 @@ public final Observable takeWhile(@NonNull Predicate predicate) { } /** - * Returns an Observable that emits only the first item emitted by the source ObservableSource during sequential + * Returns an {@code Observable} that emits only the first item emitted by the current {@code Observable} during sequential * time windows of a specified duration. *

* This differs from {@link #throttleLast} in that this only tracks passage of time whereas - * {@link #throttleLast} ticks at scheduled intervals. + * {@code throttleLast} ticks at scheduled intervals. *

* *

@@ -13467,7 +13873,8 @@ public final Observable takeWhile(@NonNull Predicate predicate) { * time to wait before emitting another item after emitting the last item * @param unit * the unit of time of {@code windowDuration} - * @return an Observable that performs the throttle operation + * @return an {@code Observable} that performs the throttle operation + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: Sample */ @CheckReturnValue @@ -13478,16 +13885,16 @@ public final Observable throttleFirst(long windowDuration, @NonNull TimeUnit } /** - * Returns an Observable that emits only the first item emitted by the source ObservableSource during sequential - * time windows of a specified duration, where the windows are managed by a specified Scheduler. + * Returns an {@code Observable} that emits only the first item emitted by the current {@code Observable} during sequential + * time windows of a specified duration, where the windows are managed by a specified {@link Scheduler}. *

* This differs from {@link #throttleLast} in that this only tracks passage of time whereas - * {@link #throttleLast} ticks at scheduled intervals. + * {@code throttleLast} ticks at scheduled intervals. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param skipDuration @@ -13495,9 +13902,10 @@ public final Observable throttleFirst(long windowDuration, @NonNull TimeUnit * @param unit * the unit of time of {@code skipDuration} * @param scheduler - * the {@link Scheduler} to use internally to manage the timers that handle timeout for each + * the {@code Scheduler} to use internally to manage the timers that handle timeout for each * event - * @return an Observable that performs the throttle operation + * @return an {@code Observable} that performs the throttle operation + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Sample */ @CheckReturnValue @@ -13510,11 +13918,11 @@ public final Observable throttleFirst(long skipDuration, @NonNull TimeUnit un } /** - * Returns an Observable that emits only the last item emitted by the source ObservableSource during sequential + * Returns an {@code Observable} that emits only the last item emitted by the current {@code Observable} during sequential * time windows of a specified duration. *

* This differs from {@link #throttleFirst} in that this ticks along at a scheduled interval whereas - * {@link #throttleFirst} does not tick, it just tracks passage of time. + * {@code throttleFirst} does not tick, it just tracks passage of time. *

* *

@@ -13523,11 +13931,12 @@ public final Observable throttleFirst(long skipDuration, @NonNull TimeUnit un *
* * @param intervalDuration - * duration of windows within which the last item emitted by the source ObservableSource will be + * duration of windows within which the last item emitted by the current {@code Observable} will be * emitted * @param unit * the unit of time of {@code intervalDuration} - * @return an Observable that performs the throttle operation + * @return an {@code Observable} that performs the throttle operation + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: Sample * @see #sample(long, TimeUnit) */ @@ -13539,27 +13948,28 @@ public final Observable throttleLast(long intervalDuration, @NonNull TimeUnit } /** - * Returns an Observable that emits only the last item emitted by the source ObservableSource during sequential - * time windows of a specified duration, where the duration is governed by a specified Scheduler. + * Returns an {@code Observable} that emits only the last item emitted by the current {@code Observable} during sequential + * time windows of a specified duration, where the duration is governed by a specified {@link Scheduler}. *

* This differs from {@link #throttleFirst} in that this ticks along at a scheduled interval whereas - * {@link #throttleFirst} does not tick, it just tracks passage of time. + * {@code throttleFirst} does not tick, it just tracks passage of time. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param intervalDuration - * duration of windows within which the last item emitted by the source ObservableSource will be + * duration of windows within which the last item emitted by the current {@code Observable} will be * emitted * @param unit * the unit of time of {@code intervalDuration} * @param scheduler - * the {@link Scheduler} to use internally to manage the timers that handle timeout for each + * the {@code Scheduler} to use internally to manage the timers that handle timeout for each * event - * @return an Observable that performs the throttle operation + * @return an {@code Observable} that performs the throttle operation + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Sample * @see #sample(long, TimeUnit, Scheduler) */ @@ -13571,7 +13981,7 @@ public final Observable throttleLast(long intervalDuration, @NonNull TimeUnit } /** - * Throttles items from the upstream {@code Observable} by first emitting the next + * Throttles items from the current {@code Observable} by first emitting the next * item from upstream, then periodically emitting the latest item (if any) when * the specified timeout elapses between them. *

@@ -13590,7 +14000,8 @@ public final Observable throttleLast(long intervalDuration, @NonNull TimeUnit * @param timeout the time to wait after an item emission towards the downstream * before trying to emit the latest item from upstream again * @param unit the time unit - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code unit} is {@code null} * @see #throttleLatest(long, TimeUnit, boolean) * @see #throttleLatest(long, TimeUnit, Scheduler) * @since 2.2 @@ -13603,7 +14014,7 @@ public final Observable throttleLatest(long timeout, @NonNull TimeUnit unit) } /** - * Throttles items from the upstream {@code Observable} by first emitting the next + * Throttles items from the current {@code Observable} by first emitting the next * item from upstream, then periodically emitting the latest item (if any) when * the specified timeout elapses between them. *

@@ -13623,7 +14034,8 @@ public final Observable throttleLatest(long timeout, @NonNull TimeUnit unit) * immediately when the upstream completes, regardless if there is * a timeout window active or not. If {@code false}, the very last * upstream item is ignored and the flow terminates. - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code unit} is {@code null} * @see #throttleLatest(long, TimeUnit, Scheduler, boolean) * @since 2.2 */ @@ -13635,7 +14047,7 @@ public final Observable throttleLatest(long timeout, @NonNull TimeUnit unit, } /** - * Throttles items from the upstream {@code Observable} by first emitting the next + * Throttles items from the current {@code Observable} by first emitting the next * item from upstream, then periodically emitting the latest item (if any) when * the specified timeout elapses between them. *

@@ -13654,9 +14066,10 @@ public final Observable throttleLatest(long timeout, @NonNull TimeUnit unit, * @param timeout the time to wait after an item emission towards the downstream * before trying to emit the latest item from upstream again * @param unit the time unit - * @param scheduler the {@link Scheduler} where the timed wait and latest item + * @param scheduler the {@code Scheduler} where the timed wait and latest item * emission will be performed - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see #throttleLatest(long, TimeUnit, Scheduler, boolean) * @since 2.2 */ @@ -13668,7 +14081,7 @@ public final Observable throttleLatest(long timeout, @NonNull TimeUnit unit, } /** - * Throttles items from the upstream {@code Observable} by first emitting the next + * Throttles items from the current {@code Observable} by first emitting the next * item from upstream, then periodically emitting the latest item (if any) when * the specified timeout elapses between them. *

@@ -13684,13 +14097,14 @@ public final Observable throttleLatest(long timeout, @NonNull TimeUnit unit, * @param timeout the time to wait after an item emission towards the downstream * before trying to emit the latest item from upstream again * @param unit the time unit - * @param scheduler the {@link Scheduler} where the timed wait and latest item + * @param scheduler the {@code Scheduler} where the timed wait and latest item * emission will be performed * @param emitLast If {@code true}, the very last item from the upstream will be emitted * immediately when the upstream completes, regardless if there is * a timeout window active or not. If {@code false}, the very last * upstream item is ignored and the flow terminates. - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @since 2.2 */ @CheckReturnValue @@ -13703,12 +14117,12 @@ public final Observable throttleLatest(long timeout, @NonNull TimeUnit unit, } /** - * Returns an Observable that mirrors the source ObservableSource, except that it drops items emitted by the - * source ObservableSource that are followed by newer items before a timeout value expires. The timer resets on + * Returns an {@code Observable} that mirrors the current {@code Observable}, except that it drops items emitted by the + * current {@code Observable} that are followed by newer items before a timeout value expires. The timer resets on * each emission (alias to {@link #debounce(long, TimeUnit, Scheduler)}). *

- * Note: If items keep being emitted by the source ObservableSource faster than the timeout then no items - * will be emitted by the resulting ObservableSource. + * Note: If items keep being emitted by the current {@code Observable} faster than the timeout then no items + * will be emitted by the resulting {@code Observable}. *

* *

@@ -13717,13 +14131,14 @@ public final Observable throttleLatest(long timeout, @NonNull TimeUnit unit, *
* * @param timeout - * the length of the window of time that must pass after the emission of an item from the source - * ObservableSource in which that ObservableSource emits no items in order for the item to be emitted by the - * resulting ObservableSource + * the length of the window of time that must pass after the emission of an item from the current + * {@code Observable}, in which the current {@code Observable} emits no items, in order for the item to be emitted by the + * resulting {@code Observable} * @param unit * the unit of time for the specified {@code timeout} - * @return an Observable that filters out items from the source ObservableSource that are too quickly followed by + * @return an {@code Observable} that filters out items from the current {@code Observable} that are too quickly followed by * newer items + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: Debounce * @see #debounce(long, TimeUnit) */ @@ -13735,30 +14150,31 @@ public final Observable throttleWithTimeout(long timeout, @NonNull TimeUnit u } /** - * Returns an Observable that mirrors the source ObservableSource, except that it drops items emitted by the - * source ObservableSource that are followed by newer items before a timeout value expires on a specified - * Scheduler. The timer resets on each emission (Alias to {@link #debounce(long, TimeUnit, Scheduler)}). + * Returns an {@code Observable} that mirrors the current {@code Observable}, except that it drops items emitted by the + * current {@code Observable} that are followed by newer items before a timeout value expires on a specified + * {@link Scheduler}. The timer resets on each emission (Alias to {@link #debounce(long, TimeUnit, Scheduler)}). *

- * Note: If items keep being emitted by the source ObservableSource faster than the timeout then no items - * will be emitted by the resulting ObservableSource. + * Note: If items keep being emitted by the current {@code Observable} faster than the timeout then no items + * will be emitted by the resulting {@code Observable}. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param timeout - * the length of the window of time that must pass after the emission of an item from the source - * ObservableSource in which that ObservableSource emits no items in order for the item to be emitted by the - * resulting ObservableSource + * the length of the window of time that must pass after the emission of an item from the current + * {@code Observable}, in which the current {@code Observable} emits no items, in order for the item to be emitted by the + * resulting {@code Observable} * @param unit * the unit of time for the specified {@code timeout} * @param scheduler - * the {@link Scheduler} to use internally to manage the timers that handle the timeout for each + * the {@code Scheduler} to use internally to manage the timers that handle the timeout for each * item - * @return an Observable that filters out items from the source ObservableSource that are too quickly followed by + * @return an {@code Observable} that filters out items from the current {@code Observable} that are too quickly followed by * newer items + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Debounce * @see #debounce(long, TimeUnit, Scheduler) */ @@ -13770,8 +14186,8 @@ public final Observable throttleWithTimeout(long timeout, @NonNull TimeUnit u } /** - * Returns an Observable that emits records of the time interval between consecutive items emitted by the - * source ObservableSource. + * Returns an {@code Observable} that emits records of the time interval between consecutive items emitted by the + * current {@code Observable}. *

* *

@@ -13780,7 +14196,7 @@ public final Observable throttleWithTimeout(long timeout, @NonNull TimeUnit u * from the {@code computation} {@link Scheduler}. *
* - * @return an Observable that emits time interval information items + * @return an {@code Observable} that emits time interval information items * @see ReactiveX operators documentation: TimeInterval */ @CheckReturnValue @@ -13791,19 +14207,20 @@ public final Observable> timeInterval() { } /** - * Returns an Observable that emits records of the time interval between consecutive items emitted by the - * source ObservableSource, where this interval is computed on a specified Scheduler. + * Returns an {@code Observable} that emits records of the time interval between consecutive items emitted by the + * current {@code Observable}, where this interval is computed on a specified {@link Scheduler}. *

* *

*
Scheduler:
*
The operator does not operate on any particular scheduler but uses the current time - * from the specified {@link Scheduler}.
+ * from the specified {@code Scheduler}. *
* * @param scheduler - * the {@link Scheduler} used to compute time intervals - * @return an Observable that emits time interval information items + * the {@code Scheduler} used to compute time intervals + * @return an {@code Observable} that emits time interval information items + * @throws NullPointerException if {@code scheduler} is {@code null} * @see ReactiveX operators documentation: TimeInterval */ @CheckReturnValue @@ -13814,8 +14231,8 @@ public final Observable> timeInterval(@NonNull Scheduler scheduler) { } /** - * Returns an Observable that emits records of the time interval between consecutive items emitted by the - * source ObservableSource. + * Returns an {@code Observable} that emits records of the time interval between consecutive items emitted by the + * current {@code Observable}. *

* *

@@ -13825,7 +14242,8 @@ public final Observable> timeInterval(@NonNull Scheduler scheduler) { *
* * @param unit the time unit for the current time - * @return an Observable that emits time interval information items + * @return an {@code Observable} that emits time interval information items + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: TimeInterval */ @CheckReturnValue @@ -13836,20 +14254,21 @@ public final Observable> timeInterval(@NonNull TimeUnit unit) { } /** - * Returns an Observable that emits records of the time interval between consecutive items emitted by the - * source ObservableSource, where this interval is computed on a specified Scheduler. + * Returns an {@code Observable} that emits records of the time interval between consecutive items emitted by the + * current {@code Observable}, where this interval is computed on a specified {@link Scheduler}. *

* *

*
Scheduler:
*
The operator does not operate on any particular scheduler but uses the current time - * from the specified {@link Scheduler}.
+ * from the specified {@code Scheduler}. *
* * @param unit the time unit for the current time * @param scheduler - * the {@link Scheduler} used to compute time intervals - * @return an Observable that emits time interval information items + * the {@code Scheduler} used to compute time intervals + * @return an {@code Observable} that emits time interval information items + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: TimeInterval */ @CheckReturnValue @@ -13862,9 +14281,9 @@ public final Observable> timeInterval(@NonNull TimeUnit unit, @NonNull } /** - * Returns an Observable that mirrors the source ObservableSource, but notifies observers of a - * {@code TimeoutException} if an item emitted by the source ObservableSource doesn't arrive within a window of - * time after the emission of the previous item, where that period of time is measured by an ObservableSource that + * Returns an {@code Observable} that mirrors the current {@code Observable}, but notifies observers of a + * {@link TimeoutException} if an item emitted by the current {@code Observable} doesn't arrive within a window of + * time after the emission of the previous item, where that period of time is measured by an {@link ObservableSource} that * is a function of the previous item. *

* @@ -13878,11 +14297,12 @@ public final Observable> timeInterval(@NonNull TimeUnit unit, @NonNull * @param * the timeout value type (ignored) * @param itemTimeoutIndicator - * a function that returns an ObservableSource for each item emitted by the source - * ObservableSource and that determines the timeout window for the subsequent item - * @return an Observable that mirrors the source ObservableSource, but notifies observers of a - * {@code TimeoutException} if an item emitted by the source ObservableSource takes longer to arrive than + * a function that returns an {@code ObservableSource} for each item emitted by the current + * {@code Observable} and that determines the timeout window for the subsequent item + * @return an {@code Observable} that mirrors the current {@code Observable}, but notifies observers of a + * {@code TimeoutException} if an item emitted by the current {@code Observable} takes longer to arrive than * the time window defined by the selector for the previously emitted item + * @throws NullPointerException if {@code itemTimeoutIndicator} is {@code null} * @see ReactiveX operators documentation: Timeout */ @CheckReturnValue @@ -13893,9 +14313,9 @@ public final Observable timeout(@NonNull Function * @@ -13909,13 +14329,14 @@ public final Observable timeout(@NonNull Function * the timeout value type (ignored) * @param itemTimeoutIndicator - * a function that returns an ObservableSource, for each item emitted by the source ObservableSource, that + * a function that returns an {@code ObservableSource}, for each item emitted by the current {@code Observable}, that * determines the timeout window for the subsequent item * @param other - * the fallback ObservableSource to switch to if the source ObservableSource times out - * @return an Observable that mirrors the source ObservableSource, but switches to mirroring a fallback ObservableSource - * if an item emitted by the source ObservableSource takes longer to arrive than the time window defined + * the fallback {@code ObservableSource} to switch to if the current {@code Observable} times out + * @return an {@code Observable} that mirrors the current {@code Observable}, but switches to mirroring a fallback {@code ObservableSource} + * if an item emitted by the current {@code Observable} takes longer to arrive than the time window defined * by the selector for the previously emitted item + * @throws NullPointerException if {@code itemTimeoutIndicator} or {@code other} is {@code null} * @see ReactiveX operators documentation: Timeout */ @CheckReturnValue @@ -13928,9 +14349,9 @@ public final Observable timeout(@NonNull Function * *

@@ -13940,24 +14361,25 @@ public final Observable timeout(@NonNull FunctionReactiveX operators documentation: Timeout */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.COMPUTATION) @NonNull - public final Observable timeout(long timeout, @NonNull TimeUnit timeUnit) { - return timeout0(timeout, timeUnit, null, Schedulers.computation()); + public final Observable timeout(long timeout, @NonNull TimeUnit unit) { + return timeout0(timeout, unit, null, Schedulers.computation()); } /** - * Returns an Observable that mirrors the source ObservableSource but applies a timeout policy for each emitted + * Returns an {@code Observable} that mirrors the current {@code Observable} but applies a timeout policy for each emitted * item. If the next item isn't emitted within the specified timeout duration starting from its predecessor, - * the source ObservableSource is disposed and resulting ObservableSource begins instead - * to mirror a fallback ObservableSource. + * the current {@code Observable} is disposed and the resulting {@code Observable} begins instead + * to mirror a fallback {@link ObservableSource}. *

* *

@@ -13967,86 +14389,88 @@ public final Observable timeout(long timeout, @NonNull TimeUnit timeUnit) { * * @param timeout * maximum duration between items before a timeout occurs - * @param timeUnit + * @param unit * the unit of time that applies to the {@code timeout} argument * @param other - * the fallback ObservableSource to use in case of a timeout - * @return the source ObservableSource modified to switch to the fallback ObservableSource in case of a timeout + * the fallback {@code ObservableSource} to use in case of a timeout + * @return the current {@code Observable} modified to switch to the fallback {@code ObservableSource} in case of a timeout + * @throws NullPointerException if {@code unit} or {@code other} is {@code null} * @see ReactiveX operators documentation: Timeout */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.COMPUTATION) @NonNull - public final Observable timeout(long timeout, @NonNull TimeUnit timeUnit, @NonNull ObservableSource other) { + public final Observable timeout(long timeout, @NonNull TimeUnit unit, @NonNull ObservableSource other) { Objects.requireNonNull(other, "other is null"); - return timeout0(timeout, timeUnit, other, Schedulers.computation()); + return timeout0(timeout, unit, other, Schedulers.computation()); } /** - * Returns an Observable that mirrors the source ObservableSource but applies a timeout policy for each emitted - * item using a specified Scheduler. If the next item isn't emitted within the specified timeout duration - * starting from its predecessor, the source ObservableSource is disposed and resulting ObservableSource - * begins instead to mirror a fallback ObservableSource. + * Returns an {@code Observable} that mirrors the current {@code Observable} but applies a timeout policy for each emitted + * item using a specified {@link Scheduler}. If the next item isn't emitted within the specified timeout duration + * starting from its predecessor, the current {@code Observable} is disposed and returned {@code Observable} + * begins instead to mirror a fallback {@link ObservableSource}. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param timeout * maximum duration between items before a timeout occurs - * @param timeUnit + * @param unit * the unit of time that applies to the {@code timeout} argument * @param scheduler - * the {@link Scheduler} to run the timeout timers on + * the {@code Scheduler} to run the timeout timers on * @param other - * the ObservableSource to use as the fallback in case of a timeout - * @return the source ObservableSource modified so that it will switch to the fallback ObservableSource in case of a + * the {@code ObservableSource} to use as the fallback in case of a timeout + * @return the current {@code Observable} modified so that it will switch to the fallback {@code ObservableSource} in case of a * timeout + * @throws NullPointerException if {@code unit}, {@code scheduler} or {@code other} is {@code null} * @see ReactiveX operators documentation: Timeout */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.CUSTOM) @NonNull - public final Observable timeout(long timeout, @NonNull TimeUnit timeUnit, @NonNull Scheduler scheduler, @NonNull ObservableSource other) { + public final Observable timeout(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, @NonNull ObservableSource other) { Objects.requireNonNull(other, "other is null"); - return timeout0(timeout, timeUnit, other, scheduler); + return timeout0(timeout, unit, other, scheduler); } /** - * Returns an Observable that mirrors the source ObservableSource but applies a timeout policy for each emitted - * item, where this policy is governed on a specified Scheduler. If the next item isn't emitted within the - * specified timeout duration starting from its predecessor, the resulting ObservableSource terminates and - * notifies observers of a {@code TimeoutException}. + * Returns an {@code Observable} that mirrors the current {@code Observable} but applies a timeout policy for each emitted + * item, where this policy is governed on a specified {@link Scheduler}. If the next item isn't emitted within the + * specified timeout duration starting from its predecessor, the resulting {@code Observable} terminates and + * notifies observers of a {@link TimeoutException}. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param timeout * maximum duration between items before a timeout occurs - * @param timeUnit + * @param unit * the unit of time that applies to the {@code timeout} argument * @param scheduler - * the Scheduler to run the timeout timers on - * @return the source ObservableSource modified to notify observers of a {@code TimeoutException} in case of a + * the {@code Scheduler} to run the timeout timers on + * @return the current {@code Observable} modified to notify observers of a {@code TimeoutException} in case of a * timeout * @see ReactiveX operators documentation: Timeout */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.CUSTOM) @NonNull - public final Observable timeout(long timeout, @NonNull TimeUnit timeUnit, @NonNull Scheduler scheduler) { - return timeout0(timeout, timeUnit, null, scheduler); + public final Observable timeout(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) { + return timeout0(timeout, unit, null, scheduler); } /** - * Returns an Observable that mirrors the source ObservableSource, but notifies observers of a - * {@code TimeoutException} if either the first item emitted by the source ObservableSource or any subsequent item - * doesn't arrive within time windows defined by other ObservableSources. + * Returns an {@code Observable} that mirrors the current {@code Observable}, but notifies observers of a + * {@link TimeoutException} if either the first item emitted by the current {@code Observable} or any subsequent item + * doesn't arrive within time windows defined by indicator {@link ObservableSource}s. *

* *

@@ -14059,15 +14483,16 @@ public final Observable timeout(long timeout, @NonNull TimeUnit timeUnit, @No * @param * the subsequent timeout value type (ignored) * @param firstTimeoutIndicator - * a function that returns an ObservableSource that determines the timeout window for the first source + * a function that returns an {@code ObservableSource} that determines the timeout window for the first source * item * @param itemTimeoutIndicator - * a function that returns an ObservableSource for each item emitted by the source ObservableSource and that + * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable} and that * determines the timeout window in which the subsequent source item must arrive in order to * continue the sequence - * @return an Observable that mirrors the source ObservableSource, but notifies observers of a + * @return an {@code Observable} that mirrors the current {@code Observable}, but notifies observers of a * {@code TimeoutException} if either the first item or any subsequent item doesn't arrive within * the time windows specified by the timeout selectors + * @throws NullPointerException if {@code firstTimeoutIndicator} or {@code itemTimeoutIndicator} is {@code null} * @see ReactiveX operators documentation: Timeout */ @CheckReturnValue @@ -14080,9 +14505,9 @@ public final Observable timeout(@NonNull ObservableSource firstTime } /** - * Returns an Observable that mirrors the source ObservableSource, but switches to a fallback ObservableSource if either - * the first item emitted by the source ObservableSource or any subsequent item doesn't arrive within time windows - * defined by other ObservableSources. + * Returns an {@code Observable} that mirrors the current {@code Observable}, but switches to a fallback {@link ObservableSource} if either + * the first item emitted by the current {@code Observable} or any subsequent item doesn't arrive within time windows + * defined by indicator {@code ObservableSource}s. *

* *

@@ -14095,20 +14520,19 @@ public final Observable timeout(@NonNull ObservableSource firstTime * @param * the subsequent timeout value type (ignored) * @param firstTimeoutIndicator - * a function that returns an ObservableSource which determines the timeout window for the first source + * a function that returns an {@code ObservableSource} which determines the timeout window for the first source * item * @param itemTimeoutIndicator - * a function that returns an ObservableSource for each item emitted by the source ObservableSource and that + * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable} and that * determines the timeout window in which the subsequent source item must arrive in order to * continue the sequence * @param other - * the fallback ObservableSource to switch to if the source ObservableSource times out - * @return an Observable that mirrors the source ObservableSource, but switches to the {@code other} ObservableSource if - * either the first item emitted by the source ObservableSource or any subsequent item doesn't arrive + * the fallback {@code ObservableSource} to switch to if the current {@code Observable} times out + * @return an {@code Observable} that mirrors the current {@code Observable}, but switches to the {@code other} {@code ObservableSource} if + * either the first item emitted by the current {@code Observable} or any subsequent item doesn't arrive * within time windows defined by the timeout selectors * @throws NullPointerException - * if {@code itemTimeoutIndicator} is null, or - * if {@code other} is null + * if {@code firstTimeoutIndicator}, {@code itemTimeoutIndicator} or {@code other} is {@code null} * @see ReactiveX operators documentation: Timeout */ @CheckReturnValue @@ -14124,12 +14548,12 @@ public final Observable timeout( } @NonNull - private Observable timeout0(long timeout, @NonNull TimeUnit timeUnit, + private Observable timeout0(long timeout, @NonNull TimeUnit unit, @Nullable ObservableSource other, @NonNull Scheduler scheduler) { - Objects.requireNonNull(timeUnit, "timeUnit is null"); + Objects.requireNonNull(unit, "unit is null"); Objects.requireNonNull(scheduler, "scheduler is null"); - return RxJavaPlugins.onAssembly(new ObservableTimeoutTimed<>(this, timeout, timeUnit, scheduler, other)); + return RxJavaPlugins.onAssembly(new ObservableTimeoutTimed<>(this, timeout, unit, scheduler, other)); } @NonNull @@ -14142,7 +14566,7 @@ private Observable timeout0( } /** - * Returns an Observable that emits each item emitted by the source ObservableSource, wrapped in a + * Returns an {@code Observable} that emits each item emitted by the current {@code Observable}, wrapped in a * {@link Timed} object. *

* @@ -14152,7 +14576,7 @@ private Observable timeout0( * from the {@code computation} {@link Scheduler}. *

* - * @return an Observable that emits timestamped items from the source ObservableSource + * @return an {@code Observable} that emits timestamped items from the current {@code Observable} * @see ReactiveX operators documentation: Timestamp */ @CheckReturnValue @@ -14163,20 +14587,21 @@ public final Observable> timestamp() { } /** - * Returns an Observable that emits each item emitted by the source ObservableSource, wrapped in a - * {@link Timed} object whose timestamps are provided by a specified Scheduler. + * Returns an {@code Observable} that emits each item emitted by the current {@code Observable}, wrapped in a + * {@link Timed} object whose timestamps are provided by a specified {@link Scheduler}. *

* *

*
Scheduler:
*
This operator does not operate on any particular scheduler but uses the current time - * from the specified {@link Scheduler}.
+ * from the specified {@code Scheduler}. *
* * @param scheduler - * the {@link Scheduler} to use as a time source - * @return an Observable that emits timestamped items from the source ObservableSource with timestamps provided by + * the {@code Scheduler} to use as a time source + * @return an {@code Observable} that emits timestamped items from the current {@code Observable} with timestamps provided by * the {@code scheduler} + * @throws NullPointerException if {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Timestamp */ @CheckReturnValue @@ -14187,7 +14612,7 @@ public final Observable> timestamp(@NonNull Scheduler scheduler) { } /** - * Returns an Observable that emits each item emitted by the source ObservableSource, wrapped in a + * Returns an {@code Observable} that emits each item emitted by the current {@code Observable}, wrapped in a * {@link Timed} object. *

* @@ -14198,7 +14623,8 @@ public final Observable> timestamp(@NonNull Scheduler scheduler) { *

* * @param unit the time unit for the current time - * @return an Observable that emits timestamped items from the source ObservableSource + * @return an {@code Observable} that emits timestamped items from the current {@code Observable} + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: Timestamp */ @CheckReturnValue @@ -14209,21 +14635,22 @@ public final Observable> timestamp(@NonNull TimeUnit unit) { } /** - * Returns an Observable that emits each item emitted by the source ObservableSource, wrapped in a - * {@link Timed} object whose timestamps are provided by a specified Scheduler. + * Returns an {@code Observable} that emits each item emitted by the current {@code Observable}, wrapped in a + * {@link Timed} object whose timestamps are provided by a specified {@link Scheduler}. *

* *

*
Scheduler:
*
This operator does not operate on any particular scheduler but uses the current time - * from the specified {@link Scheduler}.
+ * from the specified {@code Scheduler}. *
* * @param unit the time unit for the current time * @param scheduler - * the {@link Scheduler} to use as a time source - * @return an Observable that emits timestamped items from the source ObservableSource with timestamps provided by + * the {@code Scheduler} to use as a time source + * @return an {@code Observable} that emits timestamped items from the current {@code Observable} with timestamps provided by * the {@code scheduler} + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Timestamp */ @CheckReturnValue @@ -14245,9 +14672,9 @@ public final Observable> timestamp(@NonNull TimeUnit unit, @NonNull Sch *
*

History: 2.1.7 - experimental * @param the resulting object type - * @param converter the function that receives the current Observable instance and returns a value + * @param converter the function that receives the current {@code Observable} instance and returns a value * @return the converted value - * @throws NullPointerException if converter is null + * @throws NullPointerException if {@code converter} is {@code null} * @since 2.2 */ @CheckReturnValue @@ -14258,27 +14685,27 @@ public final R to(@NonNull ObservableConverter converter) { } /** - * Returns a Single that emits a single item, a list composed of all the items emitted by the - * finite source ObservableSource. + * Returns a {@link Single} that emits a single item, a {@link List} composed of all the items emitted by the + * current and finite {@code Observable}. *

* *

- * Normally, an ObservableSource that returns multiple items will do so by invoking its {@link Observer}'s + * Normally, an {@link ObservableSource} that returns multiple items will do so by invoking its {@link Observer}'s * {@link Observer#onNext onNext} method for each such item. You can change this behavior, instructing the - * ObservableSource to compose a list of all of these items and then to invoke the Observer's {@code onNext} - * function once, passing it the entire list, by calling the ObservableSource's {@code toList} method prior to + * {@code ObservableSource} to compose a list of all of these items and then to invoke the {@code Observer}'s {@code onNext} + * function once, passing it the entire list, by calling the {@code ObservableSource}'s {@code toList} method prior to * calling its {@link #subscribe} method. *

* Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to * be emitted. Sources that are infinite and never complete will never emit anything through this - * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. + * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}. *

*
Scheduler:
*
{@code toList} does not operate by default on a particular {@link Scheduler}.
*
* - * @return a Single that emits a single item: a List containing all of the items emitted by the source - * ObservableSource + * @return a {@code Single} that emits a single item: a {@code List} containing all of the items emitted by the current + * {@code Observable} * @see ReactiveX operators documentation: To */ @CheckReturnValue @@ -14289,29 +14716,30 @@ public final R to(@NonNull ObservableConverter converter) { } /** - * Returns a Single that emits a single item, a list composed of all the items emitted by the - * finite source ObservableSource. + * Returns a {@link Single} that emits a single item, a {@link List} composed of all the items emitted by the + * current and finite {@code Observable}. *

* *

- * Normally, an ObservableSource that returns multiple items will do so by invoking its {@link Observer}'s + * Normally, an {@link ObservableSource} that returns multiple items will do so by invoking its {@link Observer}'s * {@link Observer#onNext onNext} method for each such item. You can change this behavior, instructing the - * ObservableSource to compose a list of all of these items and then to invoke the Observer's {@code onNext} - * function once, passing it the entire list, by calling the ObservableSource's {@code toList} method prior to + * {@code ObservableSource} to compose a list of all of these items and then to invoke the {@code Observer}'s {@code onNext} + * function once, passing it the entire list, by calling the {@code ObservableSource}'s {@code toList} method prior to * calling its {@link #subscribe} method. *

* Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to * be emitted. Sources that are infinite and never complete will never emit anything through this - * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. + * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}. *

*
Scheduler:
*
{@code toList} does not operate by default on a particular {@link Scheduler}.
*
* * @param capacityHint - * the number of elements expected from the current Observable - * @return a Single that emits a single item: a List containing all of the items emitted by the source - * ObservableSource + * the number of elements expected from the current {@code Observable} + * @return a {@code Single} that emits a single item: a {@code List} containing all of the items emitted by the current + * {@code Observable} + * @throws IllegalArgumentException if {@code capacityHint} is non-positive * @see ReactiveX operators documentation: To */ @CheckReturnValue @@ -14323,20 +14751,20 @@ public final R to(@NonNull ObservableConverter converter) { } /** - * Returns a Single that emits a single item, a list composed of all the items emitted by the - * finite source ObservableSource. + * Returns a {@link Single} that emits a single item, a {@link Collection} (subclass) composed of all the items emitted by the + * finite upstream {@code Observable}. *

* *

- * Normally, an ObservableSource that returns multiple items will do so by invoking its {@link Observer}'s + * Normally, an {@link ObservableSource} that returns multiple items will do so by invoking its {@link Observer}'s * {@link Observer#onNext onNext} method for each such item. You can change this behavior, instructing the - * ObservableSource to compose a list of all of these items and then to invoke the Observer's {@code onNext} - * function once, passing it the entire list, by calling the ObservableSource's {@code toList} method prior to + * {@code ObservableSource} to compose a list of all of these items and then to invoke the {@code Observer}'s {@code onNext} + * function once, passing it the entire list, by calling the {@code ObservableSource}'s {@code toList} method prior to * calling its {@link #subscribe} method. *

* Note that this operator requires the upstream to signal {@code onComplete} for the accumulated collection to * be emitted. Sources that are infinite and never complete will never emit anything through this - * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. + * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}. *

*
Scheduler:
*
{@code toList} does not operate by default on a particular {@link Scheduler}.
@@ -14344,9 +14772,10 @@ public final R to(@NonNull ObservableConverter converter) { * * @param the subclass of a collection of Ts * @param collectionSupplier - * the Supplier returning the collection (for each individual Observer) to be filled in - * @return a Single that emits a single item: a List containing all of the items emitted by the source - * ObservableSource + * the {@link Supplier} returning the collection (for each individual {@code Observer}) to be filled in + * @return a {@code Single} that emits a single item: a {@code Collection} (subclass) containing all of the items emitted by the current + * {@code Observable} + * @throws NullPointerException if {@code collectionSupplier} is {@code null} * @see ReactiveX operators documentation: To */ @CheckReturnValue @@ -14358,17 +14787,17 @@ public final R to(@NonNull ObservableConverter converter) { } /** - * Returns a Single that emits a single HashMap containing all items emitted by the - * finite source ObservableSource, mapped by the keys returned by a specified + * Returns a {@link Single} that emits a single {@link HashMap} containing all items emitted by the + * current and finite {@code Observable}, mapped by the keys returned by a specified * {@code keySelector} function. *

* *

- * If more than one source item maps to the same key, the HashMap will contain the latest of those items. + * If more than one source item maps to the same key, the {@code HashMap} will contain the latest of those items. *

- * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code HashMap} to * be emitted. Sources that are infinite and never complete will never emit anything through this - * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. + * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}. *

*
Scheduler:
*
{@code toMap} does not operate by default on a particular {@link Scheduler}.
@@ -14376,9 +14805,10 @@ public final R to(@NonNull ObservableConverter converter) { * * @param the key type of the Map * @param keySelector - * the function that extracts the key from a source item to be used in the HashMap - * @return a Single that emits a single item: a HashMap containing the mapped items from the source - * ObservableSource + * the function that extracts the key from a source item to be used in the {@code HashMap} + * @return a {@code Single} that emits a single item: a {@code HashMap} containing the mapped items from the current + * {@code Observable} + * @throws NullPointerException if {@code keySelector} is {@code null} * @see ReactiveX operators documentation: To */ @CheckReturnValue @@ -14390,30 +14820,31 @@ public final R to(@NonNull ObservableConverter converter) { } /** - * Returns a Single that emits a single HashMap containing values corresponding to items emitted by the - * finite source ObservableSource, mapped by the keys returned by a specified {@code keySelector} function. + * Returns a {@link Single} that emits a single {@link HashMap} containing values corresponding to items emitted by the + * current and finite {@code Observable}, mapped by the keys and values returned by the given selector functions. *

* *

- * If more than one source item maps to the same key, the HashMap will contain a single entry that + * If more than one source item maps to the same key, the {@code HashMap} will contain a single entry that * corresponds to the latest of those items. *

- * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code HashMap} to * be emitted. Sources that are infinite and never complete will never emit anything through this - * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. + * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}. *

*
Scheduler:
*
{@code toMap} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the key type of the Map - * @param the value type of the Map + * @param the key type of the {@code HashMap} + * @param the value type of the {@code HashMap} * @param keySelector - * the function that extracts the key from a source item to be used in the HashMap + * the function that extracts the key from a source item to be used in the {@code HashMap} * @param valueSelector - * the function that extracts the value from a source item to be used in the HashMap - * @return a Single that emits a single item: a HashMap containing the mapped items from the source - * ObservableSource + * the function that extracts the value from a source item to be used in the {@code HashMap} + * @return a {@code Single} that emits a single item: a {@code HashMap} containing the mapped items from the current + * {@code Observable} + * @throws NullPointerException if {@code keySelector} or {@code valueSelector} is {@code null} * @see ReactiveX operators documentation: To */ @CheckReturnValue @@ -14428,29 +14859,30 @@ public final Single> toMap( } /** - * Returns a Single that emits a single Map, returned by a specified {@code mapFactory} function, that - * contains keys and values extracted from the items emitted by the finite source ObservableSource. + * Returns a {@link Single} that emits a single {@link Map} (subclass), returned by a specified {@code mapFactory} function, that + * contains keys and values extracted from the items, via selector functions, emitted by the current and finite {@code Observable}. *

* *

- * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code Map} to * be emitted. Sources that are infinite and never complete will never emit anything through this - * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. + * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}. *

*
Scheduler:
*
{@code toMap} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the key type of the Map - * @param the value type of the Map + * @param the key type of the {@code Map} + * @param the value type of the {@code Map} * @param keySelector - * the function that extracts the key from a source item to be used in the Map + * the function that extracts the key from a source item to be used in the {@code Map} * @param valueSelector - * the function that extracts the value from the source items to be used as value in the Map + * the function that extracts the value from the source items to be used as value in the {@code Map} * @param mapSupplier - * the function that returns a Map instance to be used - * @return a Single that emits a single item: a Map that contains the mapped items emitted by the - * source ObservableSource + * the function that returns a {@code Map} instance to be used + * @return a {@code Single} that emits a single item: a {@code Map} (subclass) that contains the mapped items emitted by the + * current {@code Observable} + * @throws NullPointerException if {@code keySelector}, {@code valueSelector} or {@code mapSupplier} is {@code null} * @see ReactiveX operators documentation: To */ @CheckReturnValue @@ -14467,24 +14899,25 @@ public final Single> toMap( } /** - * Returns a Single that emits a single HashMap that contains an ArrayList of items emitted by the - * finite source ObservableSource keyed by a specified {@code keySelector} function. + * Returns a {@link Single} that emits a single {@link HashMap} that contains an {@link ArrayList} of items emitted by the + * current and finite {@code Observable} keyed by a specified {@code keySelector} function. *

* *

- * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code HashMap} to * be emitted. Sources that are infinite and never complete will never emit anything through this - * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. + * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}. *

*
Scheduler:
*
{@code toMultimap} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the key type of the Map + * @param the key type of the {@code HashMap} * @param keySelector - * the function that extracts the key from the source items to be used as key in the HashMap - * @return a Single that emits a single item: a HashMap that contains an ArrayList of items mapped from - * the source ObservableSource + * the function that extracts the key from the source items to be used as key in the {@code HashMap} + * @return a {@code Single} that emits a single item: a {@code HashMap} that contains an {@code ArrayList} of items mapped from + * the current {@code Observable} + * @throws NullPointerException if {@code keySelector} is {@code null} * @see ReactiveX operators documentation: To */ @CheckReturnValue @@ -14498,28 +14931,29 @@ public final Single> toMap( } /** - * Returns a Single that emits a single HashMap that contains an ArrayList of values extracted by a - * specified {@code valueSelector} function from items emitted by the finite source ObservableSource, + * Returns a {@link Single} that emits a single {@link HashMap} that contains an {@link ArrayList} of values extracted by a + * specified {@code valueSelector} function from items emitted by the current and finite {@code Observable}, * keyed by a specified {@code keySelector} function. *

* *

- * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code HashMap} to * be emitted. Sources that are infinite and never complete will never emit anything through this - * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. + * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}. *

*
Scheduler:
*
{@code toMultimap} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the key type of the Map - * @param the value type of the Map + * @param the key type of the {@code HashMap} + * @param the value type of the {@code HashMap} * @param keySelector - * the function that extracts a key from the source items to be used as key in the HashMap + * the function that extracts a key from the source items to be used as key in the {@code HashMap} * @param valueSelector - * the function that extracts a value from the source items to be used as value in the HashMap - * @return a Single that emits a single item: a HashMap that contains an ArrayList of items mapped from - * the source ObservableSource + * the function that extracts a value from the source items to be used as value in the {@code HashMap} + * @return a {@code Single} that emits a single item: a {@code HashMap} that contains an {@code ArrayList} of items mapped from + * the current {@code Observable} + * @throws NullPointerException if {@code keySelector} or {@code valueSelector} is {@code null} * @see ReactiveX operators documentation: To */ @CheckReturnValue @@ -14532,28 +14966,33 @@ public final Single> toMap( } /** - * Returns a Single that emits a single Map, returned by a specified {@code mapFactory} function, that - * contains a custom collection of values, extracted by a specified {@code valueSelector} function from - * items emitted by the source ObservableSource, and keyed by the {@code keySelector} function. + * Returns a {@link Single} that emits a single {@code Map} (subclass), returned by a specified {@code mapFactory} function, that + * contains a custom {@link Collection} of values, extracted by a specified {@code valueSelector} function from + * items emitted by the current and finite {@code Observable}, and keyed by the {@code keySelector} function. *

* + *

+ * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code Map} to + * be emitted. Sources that are infinite and never complete will never emit anything through this + * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}. *

*
Scheduler:
*
{@code toMultimap} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the key type of the Map - * @param the value type of the Map + * @param the key type of the {@code Map} + * @param the value type of the {@code Map} * @param keySelector - * the function that extracts a key from the source items to be used as the key in the Map + * the function that extracts a key from the source items to be used as the key in the {@code Map} * @param valueSelector - * the function that extracts a value from the source items to be used as the value in the Map + * the function that extracts a value from the source items to be used as the value in the {@code Map} * @param mapSupplier - * the function that returns a Map instance to be used + * the function that returns a {@code Map} instance to be used * @param collectionFactory - * the function that returns a Collection instance for a particular key to be used in the Map - * @return a Single that emits a single item: a Map that contains the collection of mapped items from - * the source ObservableSource + * the function that returns a {@code Collection} instance for a particular key to be used in the {@code Map} + * @return a {@code Single} that emits a single item: a {@code Map} that contains the {@code Collection} of mapped items from + * the current {@code Observable} + * @throws NullPointerException if {@code keySelector}, {@code valueSelector}, {@code mapSupplier} or {@code collectionFactory} is {@code null} * @see ReactiveX operators documentation: To */ @CheckReturnValue @@ -14572,30 +15011,31 @@ public final Single> toMap( } /** - * Returns a Single that emits a single Map, returned by a specified {@code mapFactory} function, that - * contains an ArrayList of values, extracted by a specified {@code valueSelector} function from items - * emitted by the finite source ObservableSource and keyed by the {@code keySelector} function. + * Returns a {@link Single} that emits a single {@link Map} (subclass), returned by a specified {@code mapFactory} function, that + * contains an {@link ArrayList} of values, extracted by a specified {@code valueSelector} function from items + * emitted by the current and finite {@code Observable} and keyed by the {@code keySelector} function. *

* *

- * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to + * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code Map} to * be emitted. Sources that are infinite and never complete will never emit anything through this - * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. + * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}. *

*
Scheduler:
*
{@code toMultimap} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the key type of the Map - * @param the value type of the Map + * @param the key type of the {@code Map} + * @param the value type of the {@code Map} * @param keySelector - * the function that extracts a key from the source items to be used as the key in the Map + * the function that extracts a key from the source items to be used as the key in the {@code Map} * @param valueSelector - * the function that extracts a value from the source items to be used as the value in the Map + * the function that extracts a value from the source items to be used as the value in the {@code Map} * @param mapSupplier - * the function that returns a Map instance to be used - * @return a Single that emits a single item: a Map that contains a list items mapped from the source - * ObservableSource + * the function that returns a {@code Map} instance to be used + * @return a {@code Single} that emits a single item: a {@code Map} that contains an {@code ArrayList} items mapped from the current + * {@code Observable} + * @throws NullPointerException if {@code keySelector}, {@code valueSelector} or {@code mapSupplier} is {@code null} * @see ReactiveX operators documentation: To */ @CheckReturnValue @@ -14610,7 +15050,7 @@ public final Single> toMap( } /** - * Converts the current Observable into a Flowable by applying the specified backpressure strategy. + * Converts the current {@code Observable} into a {@link Flowable} by applying the specified backpressure strategy. *

* Marble diagrams for the various backpressure strategies are as follows: *

    @@ -14643,15 +15083,16 @@ public final Single> toMap( *
* * @param strategy the backpressure strategy to apply - * @return the new Flowable instance + * @return the new {@code Flowable} instance + * @throws NullPointerException if {@code strategy} is {@code null} */ @BackpressureSupport(BackpressureKind.SPECIAL) @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @NonNull public final Flowable toFlowable(@NonNull BackpressureStrategy strategy) { + Objects.requireNonNull(strategy, "strategy is null"); Flowable f = new FlowableFromObservable<>(this); - switch (strategy) { case DROP: return f.onBackpressureDrop(); @@ -14667,26 +15108,29 @@ public final Flowable toFlowable(@NonNull BackpressureStrategy strategy) { } /** - * Returns a Single that emits a list that contains the items emitted by the finite source ObservableSource, in a - * sorted order. Each item emitted by the ObservableSource must implement {@link Comparable} with respect to all + * Returns a {@link Single} that emits a {@link List} that contains the items emitted by the current and finite {@code Observable}, in a + * sorted order. Each item emitted by the current {@code Observable} must implement {@link Comparable} with respect to all * other items in the sequence. * - *

If any item emitted by this Observable does not implement {@link Comparable} with respect to - * all other items emitted by this Observable, no items will be emitted and the - * sequence is terminated with a {@link ClassCastException}. + *

+ * If any item emitted by the current {@code Observable} does not implement {@code Comparable} with respect to + * all other items emitted by the current {@code Observable}, no items will be emitted and the + * sequence is terminated with a {@link ClassCastException}. *

* *

- * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to + * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code List} to * be emitted. Sources that are infinite and never complete will never emit anything through this - * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. + * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}. *

*
Scheduler:
*
{@code toSortedList} does not operate by default on a particular {@link Scheduler}.
*
- * @return a Single that emits a list that contains the items emitted by the source ObservableSource in + * @return a {@code Single} that emits a list that contains the items emitted by the current {@code Observable} in * sorted order * @see ReactiveX operators documentation: To + * @see #toSortedList(int) + * @see #toSortedList(Comparator) */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -14696,24 +15140,25 @@ public final Flowable toFlowable(@NonNull BackpressureStrategy strategy) { } /** - * Returns a Single that emits a list that contains the items emitted by the finite source ObservableSource, in a + * Returns a {@link Single} that emits a {@link List} that contains the items emitted by the current and finite {@code Observable}, in a * sorted order based on a specified comparison function. *

* *

- * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to + * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code List} to * be emitted. Sources that are infinite and never complete will never emit anything through this - * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. + * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}. *

*
Scheduler:
*
{@code toSortedList} does not operate by default on a particular {@link Scheduler}.
*
* * @param comparator - * a function that compares two items emitted by the source ObservableSource and returns an Integer + * a function that compares two items emitted by the current {@code Observable} and returns an {@code int} * that indicates their sort order - * @return a Single that emits a list that contains the items emitted by the source ObservableSource in + * @return a {@code Single} that emits a {@code List} that contains the items emitted by the current {@code Observable} in * sorted order + * @throws NullPointerException if {@code comparator} is {@code null} * @see ReactiveX operators documentation: To */ @CheckReturnValue @@ -14725,26 +15170,28 @@ public final Flowable toFlowable(@NonNull BackpressureStrategy strategy) { } /** - * Returns a Single that emits a list that contains the items emitted by the finite source ObservableSource, in a + * Returns a {@link Single} that emits a {@link List} that contains the items emitted by the current and finite {@code Observable}, in a * sorted order based on a specified comparison function. *

* *

- * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to + * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code List} to * be emitted. Sources that are infinite and never complete will never emit anything through this - * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. + * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}. *

*
Scheduler:
*
{@code toSortedList} does not operate by default on a particular {@link Scheduler}.
*
* * @param comparator - * a function that compares two items emitted by the source ObservableSource and returns an Integer + * a function that compares two items emitted by the current {@code Observable} and returns an {@code int} * that indicates their sort order * @param capacityHint - * the initial capacity of the ArrayList used to accumulate items before sorting - * @return a Single that emits a list that contains the items emitted by the source ObservableSource in + * the initial capacity of the {@code List} used to accumulate items before sorting + * @return a {@code Single} that emits a {@code List} that contains the items emitted by the current {@code Observable} in * sorted order + * @throws NullPointerException if {@code comparator} is {@code null} + * @throws IllegalArgumentException if {@code capacityHint} is non-positive * @see ReactiveX operators documentation: To * @since 2.0 */ @@ -14757,30 +15204,32 @@ public final Flowable toFlowable(@NonNull BackpressureStrategy strategy) { } /** - * Returns a Single that emits a list that contains the items emitted by the finite source ObservableSource, in a - * sorted order. Each item emitted by the ObservableSource must implement {@link Comparable} with respect to all + * Returns a {@link Single} that emits a {@link List} that contains the items emitted by the current and finite {@code Observable}, in a + * sorted order. Each item emitted by the current {@code Observable} must implement {@link Comparable} with respect to all * other items in the sequence. - * - *

If any item emitted by this Observable does not implement {@link Comparable} with respect to - * all other items emitted by this Observable, no items will be emitted and the - * sequence is terminated with a {@link ClassCastException}. + *

+ * If any item emitted by the current {@code Observable} does not implement {@code Comparable} with respect to + * all other items emitted by the current {@code Observable}, no items will be emitted and the + * sequence is terminated with a {@link ClassCastException}. *

* *

- * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to + * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code List} to * be emitted. Sources that are infinite and never complete will never emit anything through this - * operator and an infinite source may lead to a fatal {@code OutOfMemoryError}. + * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}. *

*
Scheduler:
*
{@code toSortedList} does not operate by default on a particular {@link Scheduler}.
*
* * @param capacityHint - * the initial capacity of the ArrayList used to accumulate items before sorting - * @return a Single that emits a list that contains the items emitted by the source ObservableSource in + * the initial capacity of the {@code List} used to accumulate items before sorting + * @return a {@code Single} that emits a {@code List} that contains the items emitted by the current {@code Observable} in * sorted order + * @throws IllegalArgumentException if {@code capacityHint} is non-positive * @see ReactiveX operators documentation: To * @since 2.0 + * @see #toSortedList(Comparator, int) */ @CheckReturnValue @SchedulerSupport(SchedulerSupport.NONE) @@ -14790,19 +15239,19 @@ public final Flowable toFlowable(@NonNull BackpressureStrategy strategy) { } /** - * Modifies the source ObservableSource so that subscribers will dispose it on a specified - * {@link Scheduler}. + * Return an {@code Observable} that schedules the downstream {@link Observer}s' {@code dispose} calls + * aimed at the current {@code Observable} on the given {@link Scheduler}. *

* *

*
Scheduler:
- *
You specify which {@link Scheduler} this operator will use.
+ *
You specify which {@code Scheduler} this operator will use.
*
* * @param scheduler - * the {@link Scheduler} to perform the call to dispose() of the upstream Disposable - * @return the source ObservableSource modified so that its dispose() calls happen on the specified - * {@link Scheduler} + * the {@code Scheduler} to perform the call to {@code dispose()} of the upstream {@link Disposable} + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code scheduler} is {@code null} * @see ReactiveX operators documentation: SubscribeOn */ @CheckReturnValue @@ -14814,10 +15263,10 @@ public final Observable unsubscribeOn(@NonNull Scheduler scheduler) { } /** - * Returns an Observable that emits windows of items it collects from the source ObservableSource. The resulting - * ObservableSource emits connected, non-overlapping windows, each containing {@code count} items. When the source - * ObservableSource completes or encounters an error, the resulting ObservableSource emits the current window and - * propagates the notification from the source ObservableSource. + * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits connected, non-overlapping windows, each containing {@code count} items. When the current + * {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the current window and + * propagates the notification from the current {@code Observable}. *

* *

@@ -14827,9 +15276,9 @@ public final Observable unsubscribeOn(@NonNull Scheduler scheduler) { * * @param count * the maximum size of each window before it should be emitted - * @return an Observable that emits connected, non-overlapping windows, each containing at most - * {@code count} items from the source ObservableSource - * @throws IllegalArgumentException if either count is non-positive + * @return an {@code Observable} that emits connected, non-overlapping windows, each containing at most + * {@code count} items from the current {@code Observable} + * @throws IllegalArgumentException if {@code count} is non-positive * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -14840,10 +15289,10 @@ public final Observable> window(long count) { } /** - * Returns an Observable that emits windows of items it collects from the source ObservableSource. The resulting - * ObservableSource emits windows every {@code skip} items, each containing no more than {@code count} items. When - * the source ObservableSource completes or encounters an error, the resulting ObservableSource emits the current window - * and propagates the notification from the source ObservableSource. + * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits windows every {@code skip} items, each containing no more than {@code count} items. When + * the current {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the current window + * and propagates the notification from the current {@code Observable}. *

* *

@@ -14856,9 +15305,9 @@ public final Observable> window(long count) { * @param skip * how many items need to be skipped before starting a new window. Note that if {@code skip} and * {@code count} are equal this is the same operation as {@link #window(long)}. - * @return an Observable that emits windows every {@code skip} items containing at most {@code count} items - * from the source ObservableSource - * @throws IllegalArgumentException if either count or skip is non-positive + * @return an {@code Observable} that emits windows every {@code skip} items containing at most {@code count} items + * from the current {@code Observable} + * @throws IllegalArgumentException if {@code count} or {@code skip} is non-positive * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -14869,10 +15318,10 @@ public final Observable> window(long count, long skip) { } /** - * Returns an Observable that emits windows of items it collects from the source ObservableSource. The resulting - * ObservableSource emits windows every {@code skip} items, each containing no more than {@code count} items. When - * the source ObservableSource completes or encounters an error, the resulting ObservableSource emits the current window - * and propagates the notification from the source ObservableSource. + * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits windows every {@code skip} items, each containing no more than {@code count} items. When + * the current {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the current window + * and propagates the notification from the current {@code Observable}. *

* *

@@ -14887,9 +15336,9 @@ public final Observable> window(long count, long skip) { * {@code count} are equal this is the same operation as {@link #window(long)}. * @param bufferSize * the capacity hint for the buffer in the inner windows - * @return an Observable that emits windows every {@code skip} items containing at most {@code count} items - * from the source ObservableSource - * @throws IllegalArgumentException if either count or skip is non-positive + * @return an {@code Observable} that emits windows every {@code skip} items containing at most {@code count} items + * from the current {@code Observable} + * @throws IllegalArgumentException if {@code count}, {@code skip} or {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -14903,11 +15352,11 @@ public final Observable> window(long count, long skip, int bufferS } /** - * Returns an Observable that emits windows of items it collects from the source ObservableSource. The resulting - * ObservableSource starts a new window periodically, as determined by the {@code timeskip} argument. It emits - * each window after a fixed timespan, specified by the {@code timespan} argument. When the source - * ObservableSource completes or ObservableSource completes or encounters an error, the resulting ObservableSource emits the - * current window and propagates the notification from the source ObservableSource. + * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting + * {@code Observable} starts a new window periodically, as determined by the {@code timeskip} argument. It emits + * each window after a fixed timespan, specified by the {@code timespan} argument. When the current + * {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the + * current window and propagates the notification from the current {@code Observable}. *

* *

@@ -14926,7 +15375,9 @@ public final Observable> window(long count, long skip, int bufferS * the period of time after which a new window will be created * @param unit * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments - * @return an Observable that emits new windows periodically as a fixed timespan elapses + * @return an {@code Observable} that emits new windows periodically as a fixed timespan elapses + * @throws NullPointerException if {@code unit} is {@code null} + * @throws IllegalArgumentException if {@code timespan} or {@code timeskip} is non-positive * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -14937,11 +15388,11 @@ public final Observable> window(long timespan, long timeskip, @Non } /** - * Returns an Observable that emits windows of items it collects from the source ObservableSource. The resulting - * ObservableSource starts a new window periodically, as determined by the {@code timeskip} argument. It emits - * each window after a fixed timespan, specified by the {@code timespan} argument. When the source - * ObservableSource completes or ObservableSource completes or encounters an error, the resulting ObservableSource emits the - * current window and propagates the notification from the source ObservableSource. + * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting + * {@code Observable} starts a new window periodically, as determined by the {@code timeskip} argument. It emits + * each window after a fixed timespan, specified by the {@code timespan} argument. When the current + * {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the + * current window and propagates the notification from the current {@code Observable}. *

* *

@@ -14961,8 +15412,10 @@ public final Observable> window(long timespan, long timeskip, @Non * @param unit * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments * @param scheduler - * the {@link Scheduler} to use when determining the end and start of a window - * @return an Observable that emits new windows periodically as a fixed timespan elapses + * the {@code Scheduler} to use when determining the end and start of a window + * @return an {@code Observable} that emits new windows periodically as a fixed timespan elapses + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} + * @throws IllegalArgumentException if {@code timespan} or {@code timeskip} is non-positive * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -14973,11 +15426,11 @@ public final Observable> window(long timespan, long timeskip, @Non } /** - * Returns an Observable that emits windows of items it collects from the source ObservableSource. The resulting - * ObservableSource starts a new window periodically, as determined by the {@code timeskip} argument. It emits - * each window after a fixed timespan, specified by the {@code timespan} argument. When the source - * ObservableSource completes or ObservableSource completes or encounters an error, the resulting ObservableSource emits the - * current window and propagates the notification from the source ObservableSource. + * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting + * {@code Observable} starts a new window periodically, as determined by the {@code timeskip} argument. It emits + * each window after a fixed timespan, specified by the {@code timespan} argument. When the current + * {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the + * current window and propagates the notification from the current {@code Observable}. *

* *

@@ -14997,10 +15450,12 @@ public final Observable> window(long timespan, long timeskip, @Non * @param unit * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments * @param scheduler - * the {@link Scheduler} to use when determining the end and start of a window + * the {@code Scheduler} to use when determining the end and start of a window * @param bufferSize * the capacity hint for the buffer in the inner windows - * @return an Observable that emits new windows periodically as a fixed timespan elapses + * @return an {@code Observable} that emits new windows periodically as a fixed timespan elapses + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} + * @throws IllegalArgumentException if {@code timespan}, {@code timeskip} or {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -15016,10 +15471,10 @@ public final Observable> window(long timespan, long timeskip, @Non } /** - * Returns an Observable that emits windows of items it collects from the source ObservableSource. The resulting - * ObservableSource emits connected, non-overlapping windows, each of a fixed duration specified by the - * {@code timespan} argument. When the source ObservableSource completes or encounters an error, the resulting - * ObservableSource emits the current window and propagates the notification from the source ObservableSource. + * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits connected, non-overlapping windows, each of a fixed duration specified by the + * {@code timespan} argument. When the current {@code Observable} completes or encounters an error, the resulting + * {@code Observable} emits the current window and propagates the notification from the current {@code Observable}. *

* *

@@ -15037,8 +15492,9 @@ public final Observable> window(long timespan, long timeskip, @Non * new window * @param unit * the unit of time that applies to the {@code timespan} argument - * @return an Observable that emits connected, non-overlapping windows representing items emitted by the - * source ObservableSource during fixed, consecutive durations + * @return an {@code Observable} that emits connected, non-overlapping windows representing items emitted by the + * current {@code Observable} during fixed, consecutive durations + * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -15049,11 +15505,11 @@ public final Observable> window(long timespan, @NonNull TimeUnit u } /** - * Returns an Observable that emits windows of items it collects from the source ObservableSource. The resulting - * ObservableSource emits connected, non-overlapping windows, each of a fixed duration as specified by the + * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits connected, non-overlapping windows, each of a fixed duration as specified by the * {@code timespan} argument or a maximum size as specified by the {@code count} argument (whichever is - * reached first). When the source ObservableSource completes or encounters an error, the resulting ObservableSource - * emits the current window and propagates the notification from the source ObservableSource. + * reached first). When the current {@code Observable} completes or encounters an error, the resulting {@code Observable} + * emits the current window and propagates the notification from the current {@code Observable}. *

* *

@@ -15073,9 +15529,11 @@ public final Observable> window(long timespan, @NonNull TimeUnit u * the unit of time that applies to the {@code timespan} argument * @param count * the maximum size of each window before it should be emitted - * @return an Observable that emits connected, non-overlapping windows of items from the source ObservableSource + * @return an {@code Observable} that emits connected, non-overlapping windows of items from the current {@code Observable} * that were emitted during a fixed duration of time or when the window has reached maximum capacity * (whichever occurs first) + * @throws NullPointerException if {@code unit} is {@code null} + * @throws IllegalArgumentException if {@code count} is non-positive * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -15087,11 +15545,11 @@ public final Observable> window(long timespan, @NonNull TimeUnit u } /** - * Returns an Observable that emits windows of items it collects from the source ObservableSource. The resulting - * ObservableSource emits connected, non-overlapping windows, each of a fixed duration as specified by the + * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits connected, non-overlapping windows, each of a fixed duration as specified by the * {@code timespan} argument or a maximum size as specified by the {@code count} argument (whichever is - * reached first). When the source ObservableSource completes or encounters an error, the resulting ObservableSource - * emits the current window and propagates the notification from the source ObservableSource. + * reached first). When the current {@code Observable} completes or encounters an error, the resulting {@code Observable} + * emits the current window and propagates the notification from the current {@code Observable}. *

* *

@@ -15112,10 +15570,12 @@ public final Observable> window(long timespan, @NonNull TimeUnit u * @param count * the maximum size of each window before it should be emitted * @param restart - * if true, when a window reaches the capacity limit, the timer is restarted as well - * @return an Observable that emits connected, non-overlapping windows of items from the source ObservableSource + * if {@code true}, when a window reaches the capacity limit, the timer is restarted as well + * @return an {@code Observable} that emits connected, non-overlapping windows of items from the current {@code Observable} * that were emitted during a fixed duration of time or when the window has reached maximum capacity * (whichever occurs first) + * @throws NullPointerException if {@code unit} is {@code null} + * @throws IllegalArgumentException if {@code count} is non-positive * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -15127,10 +15587,10 @@ public final Observable> window(long timespan, @NonNull TimeUnit u } /** - * Returns an Observable that emits windows of items it collects from the source ObservableSource. The resulting - * ObservableSource emits connected, non-overlapping windows, each of a fixed duration as specified by the - * {@code timespan} argument. When the source ObservableSource completes or encounters an error, the resulting - * ObservableSource emits the current window and propagates the notification from the source ObservableSource. + * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits connected, non-overlapping windows, each of a fixed duration as specified by the + * {@code timespan} argument. When the current {@code Observable} completes or encounters an error, the resulting + * {@code Observable} emits the current window and propagates the notification from the current {@code Observable}. *

* *

@@ -15149,9 +15609,10 @@ public final Observable> window(long timespan, @NonNull TimeUnit u * @param unit * the unit of time which applies to the {@code timespan} argument * @param scheduler - * the {@link Scheduler} to use when determining the end and start of a window - * @return an Observable that emits connected, non-overlapping windows containing items emitted by the - * source ObservableSource within a fixed duration + * the {@code Scheduler} to use when determining the end and start of a window + * @return an {@code Observable} that emits connected, non-overlapping windows containing items emitted by the + * current {@code Observable} within a fixed duration + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -15163,11 +15624,11 @@ public final Observable> window(long timespan, @NonNull TimeUnit u } /** - * Returns an Observable that emits windows of items it collects from the source ObservableSource. The resulting - * ObservableSource emits connected, non-overlapping windows, each of a fixed duration specified by the + * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits connected, non-overlapping windows, each of a fixed duration specified by the * {@code timespan} argument or a maximum size specified by the {@code count} argument (whichever is reached - * first). When the source ObservableSource completes or encounters an error, the resulting ObservableSource emits the - * current window and propagates the notification from the source ObservableSource. + * first). When the current {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the + * current window and propagates the notification from the current {@code Observable}. *

* *

@@ -15188,10 +15649,12 @@ public final Observable> window(long timespan, @NonNull TimeUnit u * @param count * the maximum size of each window before it should be emitted * @param scheduler - * the {@link Scheduler} to use when determining the end and start of a window - * @return an Observable that emits connected, non-overlapping windows of items from the source ObservableSource + * the {@code Scheduler} to use when determining the end and start of a window + * @return an {@code Observable} that emits connected, non-overlapping windows of items from the current {@code Observable} * that were emitted during a fixed duration of time or when the window has reached maximum capacity * (whichever occurs first) + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} + * @throws IllegalArgumentException if {@code count} is non-positive * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -15203,11 +15666,11 @@ public final Observable> window(long timespan, @NonNull TimeUnit u } /** - * Returns an Observable that emits windows of items it collects from the source ObservableSource. The resulting - * ObservableSource emits connected, non-overlapping windows, each of a fixed duration specified by the + * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits connected, non-overlapping windows, each of a fixed duration specified by the * {@code timespan} argument or a maximum size specified by the {@code count} argument (whichever is reached - * first). When the source ObservableSource completes or encounters an error, the resulting ObservableSource emits the - * current window and propagates the notification from the source ObservableSource. + * first). When the current {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the + * current window and propagates the notification from the current {@code Observable}. *

* *

@@ -15228,12 +15691,14 @@ public final Observable> window(long timespan, @NonNull TimeUnit u * @param count * the maximum size of each window before it should be emitted * @param scheduler - * the {@link Scheduler} to use when determining the end and start of a window + * the {@code Scheduler} to use when determining the end and start of a window * @param restart - * if true, when a window reaches the capacity limit, the timer is restarted as well - * @return an Observable that emits connected, non-overlapping windows of items from the source ObservableSource + * if {@code true}, when a window reaches the capacity limit, the timer is restarted as well + * @return an {@code Observable} that emits connected, non-overlapping windows of items from the current {@code Observable} * that were emitted during a fixed duration of time or when the window has reached maximum capacity * (whichever occurs first) + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} + * @throws IllegalArgumentException if {@code count} is non-positive * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -15245,11 +15710,11 @@ public final Observable> window(long timespan, @NonNull TimeUnit u } /** - * Returns an Observable that emits windows of items it collects from the source ObservableSource. The resulting - * ObservableSource emits connected, non-overlapping windows, each of a fixed duration specified by the + * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits connected, non-overlapping windows, each of a fixed duration specified by the * {@code timespan} argument or a maximum size specified by the {@code count} argument (whichever is reached - * first). When the source ObservableSource completes or encounters an error, the resulting ObservableSource emits the - * current window and propagates the notification from the source ObservableSource. + * first). When the current {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the + * current window and propagates the notification from the current {@code Observable}. *

* *

@@ -15270,14 +15735,16 @@ public final Observable> window(long timespan, @NonNull TimeUnit u * @param count * the maximum size of each window before it should be emitted * @param scheduler - * the {@link Scheduler} to use when determining the end and start of a window + * the {@code Scheduler} to use when determining the end and start of a window * @param restart - * if true, when a window reaches the capacity limit, the timer is restarted as well + * if {@code true}, when a window reaches the capacity limit, the timer is restarted as well * @param bufferSize * the capacity hint for the buffer in the inner windows - * @return an Observable that emits connected, non-overlapping windows of items from the source ObservableSource + * @return an {@code Observable} that emits connected, non-overlapping windows of items from the current {@code Observable} * that were emitted during a fixed duration of time or when the window has reached maximum capacity * (whichever occurs first) + * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null} + * @throws IllegalArgumentException if {@code count} or {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -15294,9 +15761,9 @@ public final Observable> window( } /** - * Returns an Observable that emits non-overlapping windows of items it collects from the source ObservableSource + * Returns an {@code Observable} that emits non-overlapping windows of items it collects from the current {@code Observable} * where the boundary of each window is determined by the items emitted from a specified boundary-governing - * ObservableSource. + * {@link ObservableSource}. *

* *

@@ -15312,10 +15779,11 @@ public final Observable> window( * @param * the window element type (ignored) * @param boundary - * an ObservableSource whose emitted items close and open windows - * @return an Observable that emits non-overlapping windows of items it collects from the source ObservableSource + * an {@code ObservableSource} whose emitted items close and open windows + * @return an {@code Observable} that emits non-overlapping windows of items it collects from the current {@code Observable} * where the boundary of each window is determined by the items emitted from the {@code boundary} - * ObservableSource + * {@code ObservableSource} + * @throws NullPointerException if {@code boundary} is {@code null} * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -15326,9 +15794,9 @@ public final Observable> window(@NonNull ObservableSource b } /** - * Returns an Observable that emits non-overlapping windows of items it collects from the source ObservableSource + * Returns an {@code Observable} that emits non-overlapping windows of items it collects from the current {@code Observable} * where the boundary of each window is determined by the items emitted from a specified boundary-governing - * ObservableSource. + * {@link ObservableSource}. *

* *

@@ -15344,12 +15812,14 @@ public final Observable> window(@NonNull ObservableSource b * @param * the window element type (ignored) * @param boundary - * an ObservableSource whose emitted items close and open windows + * an {@code ObservableSource} whose emitted items close and open windows * @param bufferSize * the capacity hint for the buffer in the inner windows - * @return an Observable that emits non-overlapping windows of items it collects from the source ObservableSource + * @return an {@code Observable} that emits non-overlapping windows of items it collects from the current {@code Observable} * where the boundary of each window is determined by the items emitted from the {@code boundary} - * ObservableSource + * {@code ObservableSource} + * @throws NullPointerException if {@code boundary} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -15362,9 +15832,9 @@ public final Observable> window(@NonNull ObservableSource b } /** - * Returns an Observable that emits windows of items it collects from the source ObservableSource. The resulting - * ObservableSource emits windows that contain those items emitted by the source ObservableSource between the time when - * the {@code openingIndicator} ObservableSource emits an item and when the ObservableSource returned by + * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits windows that contain those items emitted by the current {@code Observable} between the time when + * the {@code openingIndicator} {@link ObservableSource} emits an item and when the {@code ObservableSource} returned by * {@code closingIndicator} emits an item. *

* @@ -15378,15 +15848,16 @@ public final Observable> window(@NonNull ObservableSource b *

This version of {@code window} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the element type of the window-opening ObservableSource - * @param the element type of the window-closing ObservableSources + * @param the element type of the window-opening {@code ObservableSource} + * @param the element type of the window-closing {@code ObservableSource}s * @param openingIndicator - * an ObservableSource that, when it emits an item, causes another window to be created + * an {@code ObservableSource} that, when it emits an item, causes another window to be created * @param closingIndicator - * a {@link Function} that produces an ObservableSource for every window created. When this ObservableSource - * emits an item, the associated window is closed and emitted - * @return an Observable that emits windows of items emitted by the source ObservableSource that are governed by - * the specified window-governing ObservableSources + * a {@link Function} that produces an {@code ObservableSource} for every window created. When this indicator {@code ObservableSource} + * emits an item, the associated window is completed + * @return an {@code Observable} that emits windows of items emitted by the current {@code Observable} that are governed by + * the specified window-governing {@code ObservableSource}s + * @throws NullPointerException if {@code openingIndicator} or {@code closingIndicator} is {@code null} * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -15399,9 +15870,9 @@ public final Observable> window( } /** - * Returns an Observable that emits windows of items it collects from the source ObservableSource. The resulting - * ObservableSource emits windows that contain those items emitted by the source ObservableSource between the time when - * the {@code openingIndicator} ObservableSource emits an item and when the ObservableSource returned by + * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting + * {@code Observable} emits windows that contain those items emitted by the current {@code Observable} between the time when + * the {@code openingIndicator} {@link ObservableSource} emits an item and when the {@code ObservableSource} returned by * {@code closingIndicator} emits an item. *

* @@ -15415,17 +15886,19 @@ public final Observable> window( *

This version of {@code window} does not operate by default on a particular {@link Scheduler}.
*
* - * @param the element type of the window-opening ObservableSource - * @param the element type of the window-closing ObservableSources + * @param the element type of the window-opening {@code ObservableSource} + * @param the element type of the window-closing {@code ObservableSource}s * @param openingIndicator - * an ObservableSource that, when it emits an item, causes another window to be created + * an {@code ObservableSource} that, when it emits an item, causes another window to be created * @param closingIndicator - * a {@link Function} that produces an ObservableSource for every window created. When this ObservableSource - * emits an item, the associated window is closed and emitted + * a {@link Function} that produces an {@code ObservableSource} for every window created. When this indicator {@code ObservableSource} + * emits an item, the associated window is completed * @param bufferSize * the capacity hint for the buffer in the inner windows - * @return an Observable that emits windows of items emitted by the source ObservableSource that are governed by - * the specified window-governing ObservableSources + * @return an {@code Observable} that emits windows of items emitted by the current {@code Observable} that are governed by + * the specified window-governing {@code ObservableSource}s + * @throws NullPointerException if {@code openingIndicator} or {@code closingIndicator} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @see ReactiveX operators documentation: Window */ @CheckReturnValue @@ -15441,8 +15914,8 @@ public final Observable> window( } /** - * Merges the specified ObservableSource into this ObservableSource sequence by using the {@code resultSelector} - * function only when the source ObservableSource (this instance) emits an item. + * Merges the specified {@link ObservableSource} into the current {@code Observable} sequence by using the {@code resultSelector} + * function only when the current {@code Observable} emits an item. *

* * @@ -15451,16 +15924,17 @@ public final Observable> window( *

This operator, by default, doesn't run any particular {@link Scheduler}.
*
* - * @param the element type of the other ObservableSource + * @param the element type of the other {@code ObservableSource} * @param the result type of the combination * @param other - * the other ObservableSource + * the other {@code ObservableSource} * @param combiner - * the function to call when this ObservableSource emits an item and the other ObservableSource has already - * emitted an item, to generate the item to be emitted by the resulting ObservableSource - * @return an Observable that merges the specified ObservableSource into this ObservableSource by using the - * {@code resultSelector} function only when the source ObservableSource sequence (this instance) emits an + * the function to call when the current {@code Observable} emits an item and the other {@code ObservableSource} has already + * emitted an item, to generate the item to be emitted by the resulting {@code Observable} + * @return an {@code Observable} that merges the specified {@code ObservableSource} into the current {@code Observable} by using the + * {@code resultSelector} function only when the current {@code Observable} sequence (this instance) emits an * item + * @throws NullPointerException if {@code other} or {@code combiner} is {@code null} * @since 2.0 * @see ReactiveX operators documentation: CombineLatest */ @@ -15475,12 +15949,12 @@ public final Observable withLatestFrom(@NonNull ObservableSourceNote that this operator doesn't emit anything until all other sources have produced at - * least one value. The resulting emission only happens when this ObservableSource emits (and - * not when any of the other sources emit, unlike combineLatest). + * least one value. The resulting emission only happens when the current {@code Observable} emits (and + * not when any of the other sources emit, unlike {@code combineLatest}). * If a source doesn't produce any value and just completes, the sequence is completed immediately. *

* @@ -15492,10 +15966,11 @@ public final Observable withLatestFrom(@NonNull ObservableSource the first other source's value type * @param the second other source's value type * @param the result value type - * @param source1 the first other ObservableSource - * @param source2 the second other ObservableSource - * @param combiner the function called with an array of values from each participating ObservableSource - * @return the new ObservableSource instance + * @param source1 the first other {@code ObservableSource} + * @param source2 the second other {@code ObservableSource} + * @param combiner the function called with an array of values from each participating {@code ObservableSource} + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code source1}, {@code source2} or {@code combiner} is {@code null} * @since 2.0 */ @CheckReturnValue @@ -15512,11 +15987,11 @@ public final Observable withLatestFrom( } /** - * Combines the value emission from this ObservableSource with the latest emissions from the - * other ObservableSources via a function to produce the output item. + * Combines the value emission from the current {@code Observable} with the latest emissions from the + * other {@link ObservableSource}s via a function to produce the output item. * *

Note that this operator doesn't emit anything until all other sources have produced at - * least one value. The resulting emission only happens when this ObservableSource emits (and + * least one value. The resulting emission only happens when the current {@code Observable} emits (and * not when any of the other sources emit, unlike combineLatest). * If a source doesn't produce any value and just completes, the sequence is completed immediately. *

@@ -15530,11 +16005,12 @@ public final Observable withLatestFrom( * @param the second other source's value type * @param the third other source's value type * @param the result value type - * @param source1 the first other ObservableSource - * @param source2 the second other ObservableSource - * @param source3 the third other ObservableSource - * @param combiner the function called with an array of values from each participating ObservableSource - * @return the new ObservableSource instance + * @param source1 the first other {@code ObservableSource} + * @param source2 the second other {@code ObservableSource} + * @param source3 the third other {@code ObservableSource} + * @param combiner the function called with an array of values from each participating {@code ObservableSource} + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code combiner} is {@code null} * @since 2.0 */ @CheckReturnValue @@ -15553,11 +16029,11 @@ public final Observable withLatestFrom( } /** - * Combines the value emission from this ObservableSource with the latest emissions from the - * other ObservableSources via a function to produce the output item. + * Combines the value emission from the current {@code Observable} with the latest emissions from the + * other {@link ObservableSource}s via a function to produce the output item. * *

Note that this operator doesn't emit anything until all other sources have produced at - * least one value. The resulting emission only happens when this ObservableSource emits (and + * least one value. The resulting emission only happens when the current {@code Observable} emits (and * not when any of the other sources emit, unlike combineLatest). * If a source doesn't produce any value and just completes, the sequence is completed immediately. *

@@ -15572,12 +16048,14 @@ public final Observable withLatestFrom( * @param the third other source's value type * @param the fourth other source's value type * @param the result value type - * @param source1 the first other ObservableSource - * @param source2 the second other ObservableSource - * @param source3 the third other ObservableSource - * @param source4 the fourth other ObservableSource - * @param combiner the function called with an array of values from each participating ObservableSource - * @return the new ObservableSource instance + * @param source1 the first other {@code ObservableSource} + * @param source2 the second other {@code ObservableSource} + * @param source3 the third other {@code ObservableSource} + * @param source4 the fourth other {@code ObservableSource} + * @param combiner the function called with an array of values from each participating {@code ObservableSource} + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, + * {@code source4} or {@code combiner} is {@code null} * @since 2.0 */ @CheckReturnValue @@ -15597,11 +16075,11 @@ public final Observable withLatestFrom( } /** - * Combines the value emission from this ObservableSource with the latest emissions from the - * other ObservableSources via a function to produce the output item. + * Combines the value emission from the current {@code Observable} with the latest emissions from the + * other {@link ObservableSource}s via a function to produce the output item. * *

Note that this operator doesn't emit anything until all other sources have produced at - * least one value. The resulting emission only happens when this ObservableSource emits (and + * least one value. The resulting emission only happens when the current {@code Observable} emits (and * not when any of the other sources emit, unlike combineLatest). * If a source doesn't produce any value and just completes, the sequence is completed immediately. *

@@ -15613,8 +16091,9 @@ public final Observable withLatestFrom( * * @param the result value type * @param others the array of other sources - * @param combiner the function called with an array of values from each participating ObservableSource - * @return the new ObservableSource instance + * @param combiner the function called with an array of values from each participating {@code ObservableSource} + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code others} or {@code combiner} is {@code null} * @since 2.0 */ @CheckReturnValue @@ -15627,12 +16106,12 @@ public final Observable withLatestFrom(@NonNull ObservableSource[] oth } /** - * Combines the value emission from this ObservableSource with the latest emissions from the - * other ObservableSources via a function to produce the output item. + * Combines the value emission from the current {@code Observable} with the latest emissions from the + * other {@link ObservableSource}s via a function to produce the output item. * *

Note that this operator doesn't emit anything until all other sources have produced at - * least one value. The resulting emission only happens when this ObservableSource emits (and - * not when any of the other sources emit, unlike combineLatest). + * least one value. The resulting emission only happens when the current {@code Observable} emits (and + * not when any of the other sources emit, unlike {@code combineLatest}). * If a source doesn't produce any value and just completes, the sequence is completed immediately. *

* @@ -15643,8 +16122,9 @@ public final Observable withLatestFrom(@NonNull ObservableSource[] oth * * @param the result value type * @param others the iterable of other sources - * @param combiner the function called with an array of values from each participating ObservableSource - * @return the new ObservableSource instance + * @param combiner the function called with an array of values from each participating {@code ObservableSource} + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code others} or {@code combiner} is {@code null} * @since 2.0 */ @CheckReturnValue @@ -15657,12 +16137,12 @@ public final Observable withLatestFrom(@NonNull Iterable * *

- * Note that the {@code other} Iterable is evaluated as items are observed from the source ObservableSource; it is + * Note that the {@code other} {@code Iterable} is evaluated as items are observed from the current {@code Observable}; it is * not pre-consumed. This allows you to zip infinite streams on either side. *

*
Scheduler:
@@ -15670,16 +16150,17 @@ public final Observable withLatestFrom(@NonNull Iterable * * @param - * the type of items in the {@code other} Iterable + * the type of items in the {@code other} {@code Iterable} * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param other - * the Iterable sequence + * the {@code Iterable} sequence * @param zipper - * a function that combines the pairs of items from the ObservableSource and the Iterable to generate - * the items to be emitted by the resulting ObservableSource - * @return an Observable that pairs up values from the source ObservableSource and the {@code other} Iterable + * a function that combines the pairs of items from the current {@code Observable} and the {@code Iterable} to generate + * the items to be emitted by the resulting {@code Observable} + * @return an {@code Observable} that pairs up values from the current {@code Observable} and the {@code other} {@code Iterable} * sequence and emits the results of {@code zipFunction} applied to these pairs + * @throws NullPointerException if {@code other} or {@code zipper} is {@code null} * @see ReactiveX operators documentation: Zip */ @CheckReturnValue @@ -15692,8 +16173,8 @@ public final Observable zipWith(@NonNull Iterable other, @NonNull B } /** - * Returns an Observable that emits items that are the result of applying a specified function to pairs of - * values, one each from the source ObservableSource and another specified ObservableSource. + * Returns an {@code Observable} that emits items that are the result of applying a specified function to pairs of + * values, one each from the current {@code Observable} and another specified {@link ObservableSource}. *

* *

@@ -15714,16 +16195,17 @@ public final Observable zipWith(@NonNull Iterable other, @NonNull B *

* * @param - * the type of items emitted by the {@code other} ObservableSource + * the type of items emitted by the {@code other} {@code ObservableSource} * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param other - * the other ObservableSource + * the other {@code ObservableSource} * @param zipper - * a function that combines the pairs of items from the two ObservableSources to generate the items to - * be emitted by the resulting ObservableSource - * @return an Observable that pairs up values from the source ObservableSource and the {@code other} ObservableSource + * a function that combines the pairs of items from the current {@code Observable} and the other {@code ObservableSource} to generate the items to + * be emitted by the resulting {@code Observable} + * @return an {@code Observable} that pairs up values from the current {@code Observable} and the {@code other} {@code ObservableSource} * and emits the results of {@code zipFunction} applied to these pairs + * @throws NullPointerException if {@code other} or {@code zipper} is {@code null} * @see ReactiveX operators documentation: Zip */ @CheckReturnValue @@ -15736,8 +16218,8 @@ public final Observable zipWith(@NonNull ObservableSource } /** - * Returns an Observable that emits items that are the result of applying a specified function to pairs of - * values, one each from the source ObservableSource and another specified ObservableSource. + * Returns an {@code Observable} that emits items that are the result of applying a specified function to pairs of + * values, one each from the current {@code Observable} and another specified {@link ObservableSource}. *

* *

@@ -15758,18 +16240,19 @@ public final Observable zipWith(@NonNull ObservableSource *

* * @param - * the type of items emitted by the {@code other} ObservableSource + * the type of items emitted by the {@code other} {@code ObservableSource} * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param other - * the other ObservableSource + * the other {@code ObservableSource} * @param zipper - * a function that combines the pairs of items from the two ObservableSources to generate the items to - * be emitted by the resulting ObservableSource + * a function that combines the pairs of items from the current {@code Observable} and the other {@code ObservableSource} to generate the items to + * be emitted by the resulting {@code Observable} * @param delayError - * if true, errors from the current Observable or the other ObservableSource is delayed until both terminate - * @return an Observable that pairs up values from the source ObservableSource and the {@code other} ObservableSource + * if {@code true}, errors from the current {@code Observable} or the other {@code ObservableSource} is delayed until both terminate + * @return an {@code Observable} that pairs up values from the current {@code Observable} and the {@code other} {@code ObservableSource} * and emits the results of {@code zipFunction} applied to these pairs + * @throws NullPointerException if {@code other} or {@code zipper} is {@code null} * @see ReactiveX operators documentation: Zip * @since 2.0 */ @@ -15782,8 +16265,8 @@ public final Observable zipWith(@NonNull ObservableSource } /** - * Returns an Observable that emits items that are the result of applying a specified function to pairs of - * values, one each from the source ObservableSource and another specified ObservableSource. + * Returns an {@code Observable} that emits items that are the result of applying a specified function to pairs of + * values, one each from the current {@code Observable} and another specified {@link ObservableSource}. *

* *

@@ -15804,21 +16287,23 @@ public final Observable zipWith(@NonNull ObservableSource *

* * @param - * the type of items emitted by the {@code other} ObservableSource + * the type of items emitted by the {@code other} {@code ObservableSource} * @param - * the type of items emitted by the resulting ObservableSource + * the type of items emitted by the resulting {@code Observable} * @param other - * the other ObservableSource + * the other {@code ObservableSource} * @param zipper - * a function that combines the pairs of items from the two ObservableSources to generate the items to - * be emitted by the resulting ObservableSource + * a function that combines the pairs of items from the current {@code Observable} and the other {@code ObservableSource} to generate the items to + * be emitted by the resulting {@code Observable} * @param bufferSize * the capacity hint for the buffer in the inner windows * @param delayError - * if true, errors from the current Observable or the other ObservableSource is delayed until both terminate - * @return an Observable that pairs up values from the source ObservableSource and the {@code other} ObservableSource + * if {@code true}, errors from the current {@code Observable} or the other {@code ObservableSource} is delayed until both terminate + * @return an {@code Observable} that pairs up values from the current {@code Observable} and the {@code other} {@code ObservableSource} * and emits the results of {@code zipFunction} applied to these pairs * @see ReactiveX operators documentation: Zip + * @throws NullPointerException if {@code other} or {@code zipper} is {@code null} + * @throws IllegalArgumentException if {@code bufferSize} is non-positive * @since 2.0 */ @CheckReturnValue @@ -15833,13 +16318,12 @@ public final Observable zipWith(@NonNull ObservableSource // Fluent test support, super handy and reduces test preparation boilerplate // ------------------------------------------------------------------------- /** - * Creates a TestObserver and subscribes - * it to this Observable. + * Creates a {@link TestObserver} and subscribes it to the current {@code Observable}. *
*
Scheduler:
*
{@code test} does not operate by default on a particular {@link Scheduler}.
*
- * @return the new TestObserver instance + * @return the new {@code TestObserver} instance * @since 2.0 */ @CheckReturnValue @@ -15852,15 +16336,16 @@ public final TestObserver test() { // NoPMD } /** - * Creates a TestObserver, optionally disposes it and then subscribes - * it to this Observable. + * Creates a {@link TestObserver}, optionally disposes it and then subscribes + * it to the current {@code Observable}. * *
*
Scheduler:
*
{@code test} does not operate by default on a particular {@link Scheduler}.
*
- * @param dispose dispose the TestObserver before it is subscribed to this Observable? - * @return the new TestObserver instance + * @param dispose indicates if the {@code TestObserver} should be disposed before + * it is subscribed to the current {@code Observable} + * @return the new {@code TestObserver} instance * @since 2.0 */ @CheckReturnValue @@ -15897,7 +16382,8 @@ public final TestObserver test(boolean dispose) { // NoPMD *
* @param the element type of the optional value * @param optional the optional value to convert into an {@code Observable} - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code optional} is {@code null} * @since 3.0.0 * @see #just(Object) * @see #empty() @@ -15930,9 +16416,10 @@ public final TestObserver test(boolean dispose) { // NoPMD *
Scheduler:
*
{@code fromCompletionStage} does not operate by default on a particular {@link Scheduler}.
*
- * @param the element type of the CompletionStage - * @param stage the CompletionStage to convert to Observable and signal its terminal value or error - * @return the new Observable instance + * @param the element type of the {@code CompletionStage} + * @param stage the {@code CompletionStage} to convert to {@code Observable} and signal its terminal value or error + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code stage} is {@code null} * @since 3.0.0 */ @CheckReturnValue @@ -15948,7 +16435,7 @@ public final TestObserver test(boolean dispose) { // NoPMD *

* *

- * The operator closes the {@code Stream} upon cancellation and when it terminates. Exceptions raised when + * The operator closes the {@code Stream} upon cancellation and when it terminates. The exceptions raised when * closing a {@code Stream} are routed to the global error handler ({@link RxJavaPlugins#onError(Throwable)}. * If a {@code Stream} should not be closed, turn it into an {@link Iterable} and use {@link #fromIterable(Iterable)}: * 


@@ -15973,7 +16460,8 @@ public final TestObserver test(boolean dispose) { // NoPMD
      *
* @param the element type of the source {@code Stream} * @param stream the {@code Stream} of values to emit - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code stream} is {@code null} * @since 3.0.0 * @see #fromIterable(Iterable) */ @@ -15994,10 +16482,11 @@ public final TestObserver test(boolean dispose) { // NoPMD *
Scheduler:
*
{@code mapOptional} does not operate by default on a particular {@link Scheduler}.
*
- * @param the non-null output type + * @param the non-{@code null} output type * @param mapper the function that receives the upstream item and should return a non-empty {@code Optional} * to emit as the output or an empty {@code Optional} to skip to the next upstream value - * @return the new Observable instance + * @return the new {@code Observable} instance + * @throws NullPointerException if {@code mapper} is {@code null} * @since 3.0.0 * @see #map(Function) * @see #filter(Predicate) @@ -16011,8 +16500,8 @@ public final TestObserver test(boolean dispose) { // NoPMD } /** - * Collects the finite upstream's values into a container via a Stream {@link Collector} callback set and emits - * it as the success result. + * Collects the finite upstream's values into a container via a {@link Stream} {@link Collector} callback set and emits + * it as the success result as a {@link Single}. *

* * @@ -16020,11 +16509,12 @@ public final TestObserver test(boolean dispose) { // NoPMD *

Scheduler:
*
{@code collect} does not operate by default on a particular {@link Scheduler}.
* - * @param the non-null result type + * @param the non-{@code null} result type * @param the intermediate container type used for the accumulation * @param collector the interface defining the container supplier, accumulator and finisher functions; * see {@link Collectors} for some standard implementations - * @return the new Single instance + * @return the new {@code Single} instance + * @throws NullPointerException if {@code collector} is {@code null} * @since 3.0.0 * @see Collectors * @see #collect(Supplier, BiConsumer) @@ -16059,7 +16549,8 @@ public final TestObserver test(boolean dispose) { // NoPMD *
{@code firstStage} does not operate by default on a particular {@link Scheduler}.
* * @param defaultItem the item to signal if the upstream is empty - * @return the new CompletionStage instance + * @return the new {@code CompletionStage} instance + * @throws NullPointerException if {@code defaultItem} is {@code null} * @since 3.0.0 * @see #firstOrErrorStage() */ @@ -16093,7 +16584,8 @@ public final CompletionStage firstStage(@Nullable T defaultItem) { *
{@code singleStage} does not operate by default on a particular {@link Scheduler}.
* * @param defaultItem the item to signal if the upstream is empty - * @return the new CompletionStage instance + * @return the new {@code CompletionStage} instance + * @throws NullPointerException if {@code defaultItem} is {@code null} * @since 3.0.0 * @see #singleOrErrorStage() */ @@ -16126,7 +16618,8 @@ public final CompletionStage singleStage(@Nullable T defaultItem) { *
{@code lastStage} does not operate by default on a particular {@link Scheduler}.
* * @param defaultItem the item to signal if the upstream is empty - * @return the new CompletionStage instance + * @return the new {@code CompletionStage} instance + * @throws NullPointerException if {@code defaultItem} is {@code null} * @since 3.0.0 * @see #lastOrErrorStage() */ @@ -16152,7 +16645,7 @@ public final CompletionStage lastStage(@Nullable T defaultItem) { *
Scheduler:
*
{@code firstOrErrorStage} does not operate by default on a particular {@link Scheduler}.
* - * @return the new CompletionStage instance + * @return the new {@code CompletionStage} instance * @since 3.0.0 * @see #firstStage(Object) */ @@ -16179,7 +16672,7 @@ public final CompletionStage firstOrErrorStage() { *
Scheduler:
*
{@code singleOrErrorStage} does not operate by default on a particular {@link Scheduler}.
* - * @return the new CompletionStage instance + * @return the new {@code CompletionStage} instance * @since 3.0.0 * @see #singleStage(Object) */ @@ -16205,7 +16698,7 @@ public final CompletionStage singleOrErrorStage() { *
Scheduler:
*
{@code lastOrErrorStage} does not operate by default on a particular {@link Scheduler}.
* - * @return the new CompletionStage instance + * @return the new {@code CompletionStage} instance * @since 3.0.0 * @see #lastStage(Object) */ @@ -16217,7 +16710,7 @@ public final CompletionStage lastOrErrorStage() { } /** - * Creates a sequential {@link Stream} to consume or process this {@code Observable} in a blocking manner via + * Creates a sequential {@link Stream} to consume or process the current {@code Observable} in a blocking manner via * the Java {@code Stream} API. *

* @@ -16237,7 +16730,7 @@ public final CompletionStage lastOrErrorStage() { *

{@code blockingStream} does not operate by default on a particular {@link Scheduler}.
* * - * @return the new Stream instance + * @return the new {@code Stream} instance * @since 3.0.0 * @see #blockingStream(int) */ @@ -16249,7 +16742,7 @@ public final Stream blockingStream() { } /** - * Creates a sequential {@link Stream} to consume or process this {@code Observable} in a blocking manner via + * Creates a sequential {@link Stream} to consume or process the current {@code Observable} in a blocking manner via * the Java {@code Stream} API. *

* @@ -16270,7 +16763,8 @@ public final Stream blockingStream() { * * * @param capacityHint the expected number of items to be buffered - * @return the new Stream instance + * @return the new {@code Stream} instance + * @throws IllegalArgumentException if {@code capacityHint} is non-positive * @since 3.0.0 */ @CheckReturnValue @@ -16287,11 +16781,11 @@ public final Stream blockingStream(int capacityHint) { *

* *

- * Due to the blocking and sequential nature of Java {@link Stream}s, the streams are mapped and consumed in a sequential fashion + * Due to the blocking and sequential nature of Java {@code Stream}s, the streams are mapped and consumed in a sequential fashion * without interleaving (unlike a more general {@link #flatMap(Function)}). Therefore, {@code flatMapStream} and * {@code concatMapStream} are identical operators and are provided as aliases. *

- * The operator closes the {@code Stream} upon cancellation and when it terminates. Exceptions raised when + * The operator closes the {@code Stream} upon cancellation and when it terminates. The exceptions raised when * closing a {@code Stream} are routed to the global error handler ({@link RxJavaPlugins#onError(Throwable)}. * If a {@code Stream} should not be closed, turn it into an {@link Iterable} and use {@link #concatMapIterable(Function)}: * 


@@ -16316,8 +16810,9 @@ public final Stream blockingStream(int capacityHint) {
      * @param  the element type of the {@code Stream}s and the result
      * @param mapper the function that receives an upstream item and should return a {@code Stream} whose elements
      * will be emitted to the downstream
-     * @return the new Observable instance
+     * @return the new {@code Observable} instance
      * @since 3.0.0
+     * @throws NullPointerException if {@code mapper} is {@code null}
      * @see #concatMap(Function)
      * @see #concatMapIterable(Function)
      * @see #flatMapStream(Function)
@@ -16334,11 +16829,11 @@ public final Stream blockingStream(int capacityHint) {
      * 

      * 
      * 

-     * Due to the blocking and sequential nature of Java {@link Stream}s, the streams are mapped and consumed in a sequential fashion
+     * Due to the blocking and sequential nature of Java {@code Stream}s, the streams are mapped and consumed in a sequential fashion
      * without interleaving (unlike a more general {@link #flatMap(Function)}). Therefore, {@code flatMapStream} and
      * {@code concatMapStream} are identical operators and are provided as aliases.
      * 

-     * The operator closes the {@code Stream} upon cancellation and when it terminates. Exceptions raised when
+     * The operator closes the {@code Stream} upon cancellation and when it terminates. The exceptions raised when
      * closing a {@code Stream} are routed to the global error handler ({@link RxJavaPlugins#onError(Throwable)}.
      * If a {@code Stream} should not be closed, turn it into an {@link Iterable} and use {@link #flatMapIterable(Function)}:
      * 

@@ -16363,8 +16858,9 @@ public final Stream blockingStream(int capacityHint) {
      * @param  the element type of the {@code Stream}s and the result
      * @param mapper the function that receives an upstream item and should return a {@code Stream} whose elements
      * will be emitted to the downstream
-     * @return the new Observable instance
+     * @return the new {@code Observable} instance
      * @since 3.0.0
+     * @throws NullPointerException if {@code mapper} is {@code null}
      * @see #flatMap(Function)
      * @see #flatMapIterable(Function)
      */
diff --git a/src/main/java/io/reactivex/rxjava3/core/Single.java b/src/main/java/io/reactivex/rxjava3/core/Single.java
index 93779d4f5a..9b60269cd3 100644
--- a/src/main/java/io/reactivex/rxjava3/core/Single.java
+++ b/src/main/java/io/reactivex/rxjava3/core/Single.java
@@ -152,6 +152,7 @@ public static  Single amb(@NonNull Iterable Single amb(@NonNull Iterable Single ambArray(@NonNull SingleSource... sources) {
+        Objects.requireNonNull(sources, "sources is null");
         if (sources.length == 0) {
             return error(SingleInternalHelper.emptyThrower());
         }
diff --git a/src/main/java/io/reactivex/rxjava3/internal/operators/flowable/FlowableBlockingSubscribe.java b/src/main/java/io/reactivex/rxjava3/internal/operators/flowable/FlowableBlockingSubscribe.java
index 9caafbc8e5..26287a0ccc 100644
--- a/src/main/java/io/reactivex/rxjava3/internal/operators/flowable/FlowableBlockingSubscribe.java
+++ b/src/main/java/io/reactivex/rxjava3/internal/operators/flowable/FlowableBlockingSubscribe.java
@@ -36,17 +36,17 @@ private FlowableBlockingSubscribe() {
     /**
      * Subscribes to the source and calls the Subscriber methods on the current thread.
      * 

-     * @param o the source publisher
+     * @param source the source publisher
      * The cancellation and backpressure is composed through.
      * @param subscriber the subscriber to forward events and calls to in the current thread
      * @param  the value type
      */
-    public static  void subscribe(Publisher o, Subscriber subscriber) {
+    public static  void subscribe(Publisher source, Subscriber subscriber) {
         final BlockingQueue queue = new LinkedBlockingQueue<>();
 
         BlockingSubscriber bs = new BlockingSubscriber<>(queue);
 
-        o.subscribe(bs);
+        source.subscribe(bs);
 
         try {
             for (;;) {
@@ -77,15 +77,15 @@ public static  void subscribe(Publisher o, Subscriber
 
     /**
      * Runs the source observable to a terminal event, ignoring any values and rethrowing any exception.
-     * @param o the source publisher
+     * @param source the source to await
      * @param  the value type
      */
-    public static  void subscribe(Publisher o) {
+    public static  void subscribe(Publisher source) {
         BlockingIgnoringReceiver callback = new BlockingIgnoringReceiver();
         LambdaSubscriber ls = new LambdaSubscriber<>(Functions.emptyConsumer(),
         callback, callback, Functions.REQUEST_MAX);
 
-        o.subscribe(ls);
+        source.subscribe(ls);
 
         BlockingHelper.awaitForComplete(callback, ls);
         Throwable e = callback.error;
diff --git a/src/main/java/io/reactivex/rxjava3/internal/operators/observable/ObservableBlockingSubscribe.java b/src/main/java/io/reactivex/rxjava3/internal/operators/observable/ObservableBlockingSubscribe.java
index 2c88f007e9..fe06c2099f 100644
--- a/src/main/java/io/reactivex/rxjava3/internal/operators/observable/ObservableBlockingSubscribe.java
+++ b/src/main/java/io/reactivex/rxjava3/internal/operators/observable/ObservableBlockingSubscribe.java
@@ -39,6 +39,7 @@ private ObservableBlockingSubscribe() {
      * The call to dispose() is composed through.
      * @param observer the subscriber to forward events and calls to in the current thread
      * @param  the value type
+     * @throws NullPointerException if {@code observer} is {@code null}
      */
     public static  void subscribe(ObservableSource o, Observer observer) {
         final BlockingQueue queue = new LinkedBlockingQueue<>();
diff --git a/src/main/java/io/reactivex/rxjava3/parallel/ParallelFlowable.java b/src/main/java/io/reactivex/rxjava3/parallel/ParallelFlowable.java
index ea09fb53d4..df1861c032 100644
--- a/src/main/java/io/reactivex/rxjava3/parallel/ParallelFlowable.java
+++ b/src/main/java/io/reactivex/rxjava3/parallel/ParallelFlowable.java
@@ -72,8 +72,11 @@ public abstract class ParallelFlowable<@NonNull T> {
      *
      * @param subscribers the array of Subscribers
      * @return true if the number of subscribers equals to the parallelism level
+     * @throws NullPointerException if {@code subscribers} is {@code null}
+     * @throws IllegalArgumentException if {@code subscribers.length} is different from {@link #parallelism()}
      */
     protected final boolean validate(@NonNull Subscriber[] subscribers) {
+        Objects.requireNonNull(subscribers, "subscribers is null");
         int p = parallelism();
         if (subscribers.length != p) {
             Throwable iae = new IllegalArgumentException("parallelism = " + p + ", subscribers = " + subscribers.length);
@@ -156,7 +159,7 @@ public static  ParallelFlowable from(@NonNull Publisher sourc
     @BackpressureSupport(BackpressureKind.FULL)
     public static <@NonNull T> ParallelFlowable from(@NonNull Publisher source,
             int parallelism, int prefetch) {
-        Objects.requireNonNull(source, "source");
+        Objects.requireNonNull(source, "source is null");
         ObjectHelper.verifyPositive(parallelism, "parallelism");
         ObjectHelper.verifyPositive(prefetch, "prefetch");
 
@@ -183,7 +186,7 @@ public static  ParallelFlowable from(@NonNull Publisher sourc
     @SchedulerSupport(SchedulerSupport.NONE)
     @BackpressureSupport(BackpressureKind.PASS_THROUGH)
     public final  ParallelFlowable map(@NonNull Function mapper) {
-        Objects.requireNonNull(mapper, "mapper");
+        Objects.requireNonNull(mapper, "mapper is null");
         return RxJavaPlugins.onAssembly(new ParallelMap<>(this, mapper));
     }
 
@@ -212,7 +215,7 @@ public final  ParallelFlowable map(@NonNull Function ParallelFlowable map(@NonNull Function mapper, @NonNull ParallelFailureHandling errorHandler) {
-        Objects.requireNonNull(mapper, "mapper");
+        Objects.requireNonNull(mapper, "mapper is null");
         Objects.requireNonNull(errorHandler, "errorHandler is null");
         return RxJavaPlugins.onAssembly(new ParallelMapTry<>(this, mapper, errorHandler));
     }
@@ -243,7 +246,7 @@ public final  ParallelFlowable map(@NonNull Function ParallelFlowable map(@NonNull Function mapper, @NonNull BiFunction errorHandler) {
-        Objects.requireNonNull(mapper, "mapper");
+        Objects.requireNonNull(mapper, "mapper is null");
         Objects.requireNonNull(errorHandler, "errorHandler is null");
         return RxJavaPlugins.onAssembly(new ParallelMapTry<>(this, mapper, errorHandler));
     }
@@ -267,7 +270,7 @@ public final  ParallelFlowable map(@NonNull Function filter(@NonNull Predicate predicate) {
-        Objects.requireNonNull(predicate, "predicate");
+        Objects.requireNonNull(predicate, "predicate is null");
         return RxJavaPlugins.onAssembly(new ParallelFilter<>(this, predicate));
     }
 
@@ -295,7 +298,7 @@ public final ParallelFlowable filter(@NonNull Predicate predicate)
     @SchedulerSupport(SchedulerSupport.NONE)
     @BackpressureSupport(BackpressureKind.PASS_THROUGH)
     public final ParallelFlowable filter(@NonNull Predicate predicate, @NonNull ParallelFailureHandling errorHandler) {
-        Objects.requireNonNull(predicate, "predicate");
+        Objects.requireNonNull(predicate, "predicate is null");
         Objects.requireNonNull(errorHandler, "errorHandler is null");
         return RxJavaPlugins.onAssembly(new ParallelFilterTry<>(this, predicate, errorHandler));
     }
@@ -325,7 +328,7 @@ public final ParallelFlowable filter(@NonNull Predicate predicate,
     @SchedulerSupport(SchedulerSupport.NONE)
     @BackpressureSupport(BackpressureKind.PASS_THROUGH)
     public final ParallelFlowable filter(@NonNull Predicate predicate, @NonNull BiFunction errorHandler) {
-        Objects.requireNonNull(predicate, "predicate");
+        Objects.requireNonNull(predicate, "predicate is null");
         Objects.requireNonNull(errorHandler, "errorHandler is null");
         return RxJavaPlugins.onAssembly(new ParallelFilterTry<>(this, predicate, errorHandler));
     }
@@ -401,7 +404,7 @@ public final ParallelFlowable runOn(@NonNull Scheduler scheduler) {
     @BackpressureSupport(BackpressureKind.FULL)
     @SchedulerSupport(SchedulerSupport.CUSTOM)
     public final ParallelFlowable runOn(@NonNull Scheduler scheduler, int prefetch) {
-        Objects.requireNonNull(scheduler, "scheduler");
+        Objects.requireNonNull(scheduler, "scheduler is null");
         ObjectHelper.verifyPositive(prefetch, "prefetch");
         return RxJavaPlugins.onAssembly(new ParallelRunOn<>(this, scheduler, prefetch));
     }
@@ -426,7 +429,7 @@ public final ParallelFlowable runOn(@NonNull Scheduler scheduler, int prefetc
     @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
     @SchedulerSupport(SchedulerSupport.NONE)
     public final Flowable reduce(@NonNull BiFunction reducer) {
-        Objects.requireNonNull(reducer, "reducer");
+        Objects.requireNonNull(reducer, "reducer is null");
         return RxJavaPlugins.onAssembly(new ParallelReduceFull<>(this, reducer));
     }
 
@@ -453,8 +456,8 @@ public final Flowable reduce(@NonNull BiFunction reducer) {
     @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
     @SchedulerSupport(SchedulerSupport.NONE)
     public final  ParallelFlowable reduce(@NonNull Supplier initialSupplier, @NonNull BiFunction reducer) {
-        Objects.requireNonNull(initialSupplier, "initialSupplier");
-        Objects.requireNonNull(reducer, "reducer");
+        Objects.requireNonNull(initialSupplier, "initialSupplier is null");
+        Objects.requireNonNull(reducer, "reducer is null");
         return RxJavaPlugins.onAssembly(new ParallelReduce<>(this, initialSupplier, reducer));
     }
 
@@ -1024,6 +1027,7 @@ public final  ParallelFlowable collect(@NonNull Supplier coll
      * @param  the value type
      * @param publishers the array of publishers
      * @return the new ParallelFlowable instance
+     * @throws IllegalArgumentException if {@code publishers} is an empty array
      */
     @CheckReturnValue
     @NonNull
@@ -1031,6 +1035,7 @@ public final  ParallelFlowable collect(@NonNull Supplier coll
     @BackpressureSupport(BackpressureKind.PASS_THROUGH)
     @SchedulerSupport(SchedulerSupport.NONE)
     public static <@NonNull T> ParallelFlowable fromArray(@NonNull Publisher... publishers) {
+        Objects.requireNonNull(publishers, "publishers is null");
         if (publishers.length == 0) {
             throw new IllegalArgumentException("Zero publishers not supported");
         }
@@ -1427,7 +1432,7 @@ public final  ParallelFlowable flatMapIterable(@NonNull Function ParallelFlowable mapOptional(@NonNull Function> mapper) {
-        Objects.requireNonNull(mapper, "mapper");
+        Objects.requireNonNull(mapper, "mapper is null");
         return RxJavaPlugins.onAssembly(new ParallelMapOptional<>(this, mapper));
     }
 
@@ -1456,7 +1461,7 @@ public final  ParallelFlowable mapOptional(@NonNull Function ParallelFlowable mapOptional(@NonNull Function> mapper, @NonNull ParallelFailureHandling errorHandler) {
-        Objects.requireNonNull(mapper, "mapper");
+        Objects.requireNonNull(mapper, "mapper is null");
         Objects.requireNonNull(errorHandler, "errorHandler is null");
         return RxJavaPlugins.onAssembly(new ParallelMapTryOptional<>(this, mapper, errorHandler));
     }
@@ -1487,7 +1492,7 @@ public final  ParallelFlowable mapOptional(@NonNull Function ParallelFlowable mapOptional(@NonNull Function> mapper, @NonNull BiFunction errorHandler) {
-        Objects.requireNonNull(mapper, "mapper");
+        Objects.requireNonNull(mapper, "mapper is null");
         Objects.requireNonNull(errorHandler, "errorHandler is null");
         return RxJavaPlugins.onAssembly(new ParallelMapTryOptional<>(this, mapper, errorHandler));
     }
diff --git a/src/test/java/io/reactivex/rxjava3/internal/operators/flowable/FlowableSkipLastTest.java b/src/test/java/io/reactivex/rxjava3/internal/operators/flowable/FlowableSkipLastTest.java
index 53e4e24a93..7b1fb2a45f 100644
--- a/src/test/java/io/reactivex/rxjava3/internal/operators/flowable/FlowableSkipLastTest.java
+++ b/src/test/java/io/reactivex/rxjava3/internal/operators/flowable/FlowableSkipLastTest.java
@@ -97,7 +97,7 @@ public void skipLastWithBackpressure() {
 
     }
 
-    @Test(expected = IndexOutOfBoundsException.class)
+    @Test(expected = IllegalArgumentException.class)
     public void skipLastWithNegativeCount() {
         Flowable.just("one").skipLast(-1);
     }
diff --git a/src/test/java/io/reactivex/rxjava3/internal/operators/flowable/FlowableTakeLastTest.java b/src/test/java/io/reactivex/rxjava3/internal/operators/flowable/FlowableTakeLastTest.java
index c62ff85db0..de6a431844 100644
--- a/src/test/java/io/reactivex/rxjava3/internal/operators/flowable/FlowableTakeLastTest.java
+++ b/src/test/java/io/reactivex/rxjava3/internal/operators/flowable/FlowableTakeLastTest.java
@@ -89,7 +89,7 @@ public void takeLastWithZeroCount() {
         verify(subscriber, times(1)).onComplete();
     }
 
-    @Test(expected = IndexOutOfBoundsException.class)
+    @Test(expected = IllegalArgumentException.class)
     public void takeLastWithNegativeCount() {
         Flowable.just("one").takeLast(-1);
     }
diff --git a/src/test/java/io/reactivex/rxjava3/internal/operators/flowable/FlowableTakeLastTimedTest.java b/src/test/java/io/reactivex/rxjava3/internal/operators/flowable/FlowableTakeLastTimedTest.java
index 3f8c22a47f..836700d2aa 100644
--- a/src/test/java/io/reactivex/rxjava3/internal/operators/flowable/FlowableTakeLastTimedTest.java
+++ b/src/test/java/io/reactivex/rxjava3/internal/operators/flowable/FlowableTakeLastTimedTest.java
@@ -32,7 +32,7 @@
 
 public class FlowableTakeLastTimedTest extends RxJavaTest {
 
-    @Test(expected = IndexOutOfBoundsException.class)
+    @Test(expected = IllegalArgumentException.class)
     public void takeLastTimedWithNegativeCount() {
         Flowable.just("one").takeLast(-1, 1, TimeUnit.SECONDS);
     }
diff --git a/src/test/java/io/reactivex/rxjava3/internal/operators/observable/ObservableConcatMapEagerTest.java b/src/test/java/io/reactivex/rxjava3/internal/operators/observable/ObservableConcatMapEagerTest.java
index ab4ba0273f..e13124bf5d 100644
--- a/src/test/java/io/reactivex/rxjava3/internal/operators/observable/ObservableConcatMapEagerTest.java
+++ b/src/test/java/io/reactivex/rxjava3/internal/operators/observable/ObservableConcatMapEagerTest.java
@@ -535,7 +535,7 @@ public void badCapacityHint() throws Exception {
         try {
             Observable.concatEager(Arrays.asList(source, source, source), 1, -99);
         } catch (IllegalArgumentException ex) {
-            assertEquals("prefetch > 0 required but it was -99", ex.getMessage());
+            assertEquals("bufferSize > 0 required but it was -99", ex.getMessage());
         }
 
     }
@@ -547,7 +547,7 @@ public void mappingBadCapacityHint() throws Exception {
         try {
             Observable.just(source, source, source).concatMapEager((Function)Functions.identity(), 10, -99);
         } catch (IllegalArgumentException ex) {
-            assertEquals("prefetch > 0 required but it was -99", ex.getMessage());
+            assertEquals("bufferSize > 0 required but it was -99", ex.getMessage());
         }
 
     }
diff --git a/src/test/java/io/reactivex/rxjava3/internal/operators/observable/ObservableSkipLastTest.java b/src/test/java/io/reactivex/rxjava3/internal/operators/observable/ObservableSkipLastTest.java
index 8edf026fe1..712da24ea9 100644
--- a/src/test/java/io/reactivex/rxjava3/internal/operators/observable/ObservableSkipLastTest.java
+++ b/src/test/java/io/reactivex/rxjava3/internal/operators/observable/ObservableSkipLastTest.java
@@ -92,7 +92,7 @@ public void skipLastWithBackpressure() {
 
     }
 
-    @Test(expected = IndexOutOfBoundsException.class)
+    @Test(expected = IllegalArgumentException.class)
     public void skipLastWithNegativeCount() {
         Observable.just("one").skipLast(-1);
     }
diff --git a/src/test/java/io/reactivex/rxjava3/internal/operators/observable/ObservableTakeLastTest.java b/src/test/java/io/reactivex/rxjava3/internal/operators/observable/ObservableTakeLastTest.java
index 2aa9e37985..b9ed392381 100644
--- a/src/test/java/io/reactivex/rxjava3/internal/operators/observable/ObservableTakeLastTest.java
+++ b/src/test/java/io/reactivex/rxjava3/internal/operators/observable/ObservableTakeLastTest.java
@@ -83,7 +83,7 @@ public void takeLastWithZeroCount() {
         verify(observer, times(1)).onComplete();
     }
 
-    @Test(expected = IndexOutOfBoundsException.class)
+    @Test(expected = IllegalArgumentException.class)
     public void takeLastWithNegativeCount() {
         Observable.just("one").takeLast(-1);
     }
diff --git a/src/test/java/io/reactivex/rxjava3/internal/operators/observable/ObservableTakeLastTimedTest.java b/src/test/java/io/reactivex/rxjava3/internal/operators/observable/ObservableTakeLastTimedTest.java
index a81fd1d9cb..f8d17474c2 100644
--- a/src/test/java/io/reactivex/rxjava3/internal/operators/observable/ObservableTakeLastTimedTest.java
+++ b/src/test/java/io/reactivex/rxjava3/internal/operators/observable/ObservableTakeLastTimedTest.java
@@ -30,7 +30,7 @@
 
 public class ObservableTakeLastTimedTest extends RxJavaTest {
 
-    @Test(expected = IndexOutOfBoundsException.class)
+    @Test(expected = IllegalArgumentException.class)
     public void takeLastTimedWithNegativeCount() {
         Observable.just("one").takeLast(-1, 1, TimeUnit.SECONDS);
     }
diff --git a/src/test/java/io/reactivex/rxjava3/validators/JavadocCodesAndLinks.java b/src/test/java/io/reactivex/rxjava3/validators/JavadocCodesAndLinks.java
index 222409ef3c..30dc074813 100644
--- a/src/test/java/io/reactivex/rxjava3/validators/JavadocCodesAndLinks.java
+++ b/src/test/java/io/reactivex/rxjava3/validators/JavadocCodesAndLinks.java
@@ -50,8 +50,13 @@ public void checkMaybe() throws Exception {
         checkSource("Maybe", "io.reactivex.rxjava3.core");
     }
 
+    @Test
+    public void checkObservable() throws Exception {
+        checkSource("Observable", "io.reactivex.rxjava3.core");
+    }
+
     static void checkSource(String baseClassName, String packageName) throws Exception {
-        File f = TestHelper.findSource(baseClassName);
+        File f = TestHelper.findSource(baseClassName, packageName);
         if (f == null) {
             return;
         }
diff --git a/src/test/java/io/reactivex/rxjava3/validators/JavadocWording.java b/src/test/java/io/reactivex/rxjava3/validators/JavadocWording.java
index e5746cc69b..4bcb1c41c1 100644
--- a/src/test/java/io/reactivex/rxjava3/validators/JavadocWording.java
+++ b/src/test/java/io/reactivex/rxjava3/validators/JavadocWording.java
@@ -990,5 +990,5 @@ static void backpressureMentionedWithoutAnnotation(StringBuilder e, RxMethod m,
         }
     }
 
-    static final String[] AT_RETURN_WORDS = { "@return a ", "@return the new ", "@return a new " };
+    static final String[] AT_RETURN_WORDS = { "@return a ", "@return an ", "@return the new ", "@return a new " };
 }
diff --git a/src/test/java/io/reactivex/rxjava3/validators/ParamValidationCheckerTest.java b/src/test/java/io/reactivex/rxjava3/validators/ParamValidationCheckerTest.java
index 85a6c4b0bd..b46f59f42a 100644
--- a/src/test/java/io/reactivex/rxjava3/validators/ParamValidationCheckerTest.java
+++ b/src/test/java/io/reactivex/rxjava3/validators/ParamValidationCheckerTest.java
@@ -890,6 +890,12 @@ void checkClass(Class clazz) {
                                 error = ex;
                             }
 
+                            if (!success && error.getCause() instanceof NullPointerException) {
+                                if (!error.getCause().toString().contains("is null")) {
+                                    fail++;
+                                    b.append("\r\nNPEs should indicate which argument failed: " + m + " # " + i + " = " + p + ", tag = " + tag + ", params = " + Arrays.toString(callParams2));
+                                }
+                            }
                             if (success != shouldSucceed) {
                                 fail++;
                                 if (shouldSucceed) {
diff --git a/src/test/java/io/reactivex/rxjava3/validators/ParamValidationNaming.java b/src/test/java/io/reactivex/rxjava3/validators/ParamValidationNaming.java
index 12b0d43dc4..e19048f473 100644
--- a/src/test/java/io/reactivex/rxjava3/validators/ParamValidationNaming.java
+++ b/src/test/java/io/reactivex/rxjava3/validators/ParamValidationNaming.java
@@ -223,19 +223,31 @@ static void processFile(Class clazz) throws Exception {
                     // FIXME enable for other types in separate PR!
                     if (!baseClassName.equals("Completable")
                             && !baseClassName.equals("Single")
-                            && !baseClassName.equals("Maybe")) {
+                            && !baseClassName.equals("Maybe")
+                            && !baseClassName.equals("Observable")
+                    ) {
                         continue;
                     }
 
+                    int midx = j - 1;
+                    // find the method declaration
+                    for (; midx >= 0; midx--) {
+                        String linek = lines.get(midx).trim();
+                        if (linek.startsWith("public") || linek.startsWith("private")
+                                || linek.startsWith("protected")) {
+                            break;
+                        }
+                    }
+
                     // find JavaDoc of throws
                     boolean found = false;
-                    for (int k = j - 1; k >= 0; k--) {
+                    for (int k = midx - 1; k >= 0; k--) {
                         String linek = lines.get(k).trim();
                         if (linek.startsWith("/**")) {
                             break;
                         }
                         if (linek.startsWith("}")) {
-                            found = true; // no JavaDoc
+                            found = true; // no method JavaDoc present
                             break;
                         }
                         if (linek.startsWith(validatorStr.javadoc)) {
@@ -278,6 +290,56 @@ static void processFile(Class clazz) throws Exception {
                     }
                 }
             }
+
+            for (ValidatorStrings validatorStr : EXCEPTION_STRINGS) {
+                int strIdx = line.indexOf(validatorStr.code);
+                if (strIdx >= 0) {
+
+                    int midx = j - 1;
+                    // find the method declaration
+                    for (; midx >= 0; midx--) {
+                        String linek = lines.get(midx).trim();
+                        if (linek.startsWith("public") || linek.startsWith("private")
+                                || linek.startsWith("protected")) {
+                            break;
+                        }
+                    }
+
+                    // find JavaDoc of throws
+                    boolean found = false;
+                    for (int k = midx - 1; k >= 0; k--) {
+                        String linek = lines.get(k).trim();
+                        if (linek.startsWith("/**")) {
+                            break;
+                        }
+                        if (linek.startsWith("}")) {
+                            found = true; // no JavaDoc
+                            break;
+                        }
+                        if (linek.startsWith(validatorStr.javadoc)) {
+                            found = true;
+                        }
+                    }
+
+                    if (!found) {
+                        errorCount++;
+                        errors.append("L")
+                        .append(j)
+                        .append(" : missing '")
+                        .append(validatorStr.javadoc)
+                        .append("' for exception\r\n    ")
+                        .append(line)
+                        .append("\r\n at ")
+                        .append(fullClassName)
+                        .append(".method(")
+                        .append(f.getName())
+                        .append(":")
+                        .append(j + 1)
+                        .append(")\r\n")
+                        ;
+                    }
+                }
+            }
         }
 
         if (errorCount != 0) {
@@ -301,4 +363,10 @@ static final class ValidatorStrings {
             new ValidatorStrings("ObjectHelper.verifyPositive(", "* @throws IllegalArgumentException")
     );
 
+    static final List EXCEPTION_STRINGS = Arrays.asList(
+            new ValidatorStrings("throw new NullPointerException(", "* @throws NullPointerException"),
+            new ValidatorStrings("throw new IllegalArgumentException(", "* @throws IllegalArgumentException"),
+            new ValidatorStrings("throw new IndexOutOfBoundsException(", "* @throws IndexOutOfBoundsException")
+    );
+
 }