diff --git a/src/main/java/io/reactivex/rxjava3/core/Completable.java b/src/main/java/io/reactivex/rxjava3/core/Completable.java index 3e8c84835f..7e788ea3b9 100644 --- a/src/main/java/io/reactivex/rxjava3/core/Completable.java +++ b/src/main/java/io/reactivex/rxjava3/core/Completable.java @@ -1596,7 +1596,7 @@ public final Completable doOnEvent(@NonNull Consumer<@Nullable ? super Throwable * * @param onSubscribe the consumer called when a {@link CompletableObserver} subscribes. * @param onError the consumer called when this emits an {@code onError} event - * @param onComplete the runnable called just before when the upstream {@code Completable} completes normally + * @param onComplete the runnable called just before when the current {@code Completable} completes normally * @param onAfterTerminate the runnable called after this {@code Completable} completes normally * @param onDispose the {@link Runnable} called when the downstream disposes the subscription * @return the new {@code Completable} instance @@ -1834,7 +1834,7 @@ public final Completable doFinally(@NonNull Action onFinally) { *

* Note also that it is not possible to stop the subscription phase in {@code lift()} as the {@code apply()} method * requires a non-{@code null} {@code CompletableObserver} instance to be returned, which is then unconditionally subscribed to - * the upstream {@code Completable}. For example, if the operator decided there is no reason to subscribe to the + * the current {@code Completable}. 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 a {@code CompletableObserver} that should immediately dispose the upstream's {@link Disposable} in its * {@code onSubscribe} method. Again, using a {@code CompletableTransformer} and extending the {@code Completable} is @@ -2692,7 +2692,7 @@ public final Flowable toFlowable() { * * @param the value type * @return a {@code Maybe} that only calls {@code onComplete} or {@code onError}, based on which one is - * called by the source {@code Completable}. + * called by the current {@code Completable}. */ @CheckReturnValue @SuppressWarnings("unchecked") diff --git a/src/main/java/io/reactivex/rxjava3/core/Flowable.java b/src/main/java/io/reactivex/rxjava3/core/Flowable.java index 486b0cb629..c1f4338cd2 100644 --- a/src/main/java/io/reactivex/rxjava3/core/Flowable.java +++ b/src/main/java/io/reactivex/rxjava3/core/Flowable.java @@ -7270,9 +7270,9 @@ public final Single collect(@NonNull Supplier initialItemSup } /** - * Transform a {@link Publisher} by applying a particular Transformer function to it. + * Transform the current {@code Flowable} by applying a particular {@link FlowableTransformer} function to it. *

- * This method operates on the {@code Publisher} itself whereas {@link #lift} operates on the {@code Publisher}'s + * This method operates on the {@code Flowable} itself whereas {@link #lift} operates on the {@code Flowable}'s * {@link Subscriber}s. *

* If the operator you are creating is designed to act on the individual items emitted by a current @@ -7281,7 +7281,7 @@ public final Single collect(@NonNull Supplier initialItemSup *

*
Backpressure:
*
The operator itself doesn't interfere with the backpressure behavior which only depends - * on what kind of {@code Publisher} the transformer returns.
+ * on what kind of {@link Publisher} the {@code FlowableTransformer} returns. *
Scheduler:
*
{@code compose} does not operate by default on a particular {@link Scheduler}.
*
@@ -9392,7 +9392,7 @@ public final Flowable doOnCancel(@NonNull Action onCancel) { } /** - * Modifies the current {@code Flowable} so that it invokes an action when it calls {@code onComplete}. + * Invokes an {@link Action} just before the current {@code Flowable} calls {@code onComplete}. *

* *

@@ -9449,7 +9449,8 @@ private Flowable doOnEach(@NonNull Consumer onNext, @NonNull Consu } /** - * Modifies the current {@code Flowable} so that it invokes an action for each item it emits. + * Invokes a {@link Consumer} with a {@link Notification} instances matching the signals emitted by the current {@code Flowable} + * before they are forwarded to the downstream. *

* *

@@ -9481,7 +9482,8 @@ public final Flowable doOnEach(@NonNull Consumer<@NonNull ? super Notificatio } /** - * Modifies the current {@code Flowable} so that it notifies a {@link Subscriber} for each item and terminal event it emits. + * Calls the appropriate methods of the given {@link Subscriber} when the current {@code Flowable} signals events before forwarding it + * to the downstream. *

* In case the {@code onError} of the supplied {@code Subscriber} throws, the downstream will receive a composite * exception containing the original exception and the exception thrown by {@code onError}. If either the @@ -9518,7 +9520,8 @@ public final Flowable doOnEach(@NonNull Subscriber<@NonNull ? super T> subscr } /** - * Modifies the current {@code Flowable} so that it invokes an action if it calls {@code onError}. + * Calls the given {@link Consumer} with the error {@link Throwable} if the current {@code Flowable} failed before forwarding it to + * the downstream. *

* 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}. @@ -9583,7 +9586,7 @@ public final Flowable doOnLifecycle(@NonNull Consumer o } /** - * Modifies the current {@code Flowable} so that it invokes an action when it calls {@code onNext}. + * Calls the given {@link Consumer} with the value emitted by the current {@code Flowable} before forwarding it to the downstream. *

* *

@@ -9599,6 +9602,7 @@ public final Flowable doOnLifecycle(@NonNull Consumer o * @return the current {@code Flowable} with the side-effecting behavior applied * @throws NullPointerException if {@code onNext} is {@code null} * @see ReactiveX operators documentation: Do + * @see #doAfterNext(Consumer) */ @CheckReturnValue @BackpressureSupport(BackpressureKind.PASS_THROUGH) @@ -9610,8 +9614,8 @@ public final Flowable doOnNext(@NonNull Consumer onNext) { } /** - * Modifies the current {@code Flowable} so that it invokes the given action when it receives a - * request for more items. + * Calls the given {@link LongConsumer} with the request amount from the downstream before forwarding it + * to the current {@code Flowable}. *

* Note: This operator is for tracing the internal behavior of back-pressure request * patterns and generally intended for debugging use. @@ -9641,10 +9645,9 @@ public final Flowable doOnRequest(@NonNull LongConsumer onRequest) { } /** - * Modifies the current {@code Flowable} 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 - * current {@code Flowable} is reference counted, in which case the current {@code Flowable} will invoke - * the given action for the first subscription. + * Calls the given {@link Consumer} with the {@link Subscription} provided by the current {@code Flowable} upon + * subscription from the downstream before forwarding it to the subscriber's + * {@link Subscriber#onSubscribe(Subscription) onSubscribe} method. *

* *

@@ -9656,7 +9659,7 @@ public final Flowable doOnRequest(@NonNull LongConsumer onRequest) { *
* * @param onSubscribe - * the {@link Consumer} that gets called when a {@link Subscriber} subscribes to the current {@code Flowable} + * the {@code Consumer} that gets called when a {@link Subscriber} subscribes to the current {@code Flowable} * @return the current {@code Flowable} modified so as to call this {@code Consumer} when appropriate * @throws NullPointerException if {@code onSubscribe} is {@code null} * @see ReactiveX operators documentation: Do @@ -9670,8 +9673,8 @@ public final Flowable doOnSubscribe(@NonNull Consumer o } /** - * Modifies the current {@code Flowable} so that it invokes an action when it calls {@code onComplete} or - * {@code onError}. + * Calls the given {@link Action} when the current {@code Flowable} completes normally or with an error before those signals + * are forwarded to the downstream. *

* *

@@ -9798,7 +9801,7 @@ public final Single elementAtOrError(long index) { } /** - * Filters items emitted by a {@link Publisher} by only emitting those that satisfy a specified predicate. + * Filters items emitted by the current {@code Flowable} by only emitting those that satisfy a specified predicate. *

* *

@@ -10917,7 +10920,7 @@ public final Flowable> groupBy(@NonNull Function Flowable> groupBy(@NonNull Function Flowable> groupBy(@NonNull Function Flowable> groupBy(@NonNull Function Flowable> groupBy(@NonNull Function mergeWith(@NonNull CompletableSource other) { } /** - * Modifies a {@link Publisher} to perform its emissions and notifications on a specified {@link Scheduler}, + * Signals the items and terminal signals of the current {@code Flowable} on the specified {@link Scheduler}, * asynchronously with a bounded buffer of {@link #bufferSize()} slots. * *

Note that {@code onError} notifications will cut ahead of {@code onNext} notifications on the emission thread if {@code Scheduler} is truly @@ -11945,7 +11948,7 @@ public final Flowable observeOn(@NonNull Scheduler scheduler) { } /** - * Modifies a {@link Publisher} to perform its emissions and notifications on a specified {@link Scheduler}, + * Signals the items and terminal signals of the current {@code Flowable} on the specified {@link Scheduler}, * asynchronously with a bounded buffer and optionally delays {@code onError} notifications. *

* @@ -11998,7 +12001,7 @@ public final Flowable observeOn(@NonNull Scheduler scheduler, boolean delayEr } /** - * Modifies a {@link Publisher} to perform its emissions and notifications on a specified {@link Scheduler}, + * Signals the items and terminal signals of the current {@code Flowable} on the specified {@link Scheduler}, * asynchronously with a bounded buffer of configurable size and optionally delays {@code onError} notifications. *

* @@ -12055,7 +12058,7 @@ public final Flowable observeOn(@NonNull Scheduler scheduler, boolean delayEr } /** - * Filters the items emitted by a {@link Publisher}, only emitting those of the specified type. + * Filters the items emitted by the current {@code Flowable}, only emitting those of the specified type. *

* *

@@ -12083,10 +12086,13 @@ public final Flowable ofType(@NonNull Class clazz) { } /** - * Instructs a {@link Publisher} that is emitting items faster than its {@link Subscriber} can consume them to buffer these - * items indefinitely until they can be emitted. + * Buffers an unlimited number of items from the current {@code Flowable} and allows it to emit as fast it can while allowing the + * downstream to consume the items at its own place. *

* + *

+ * An error from the current {@code Flowable} will cut ahead of any unconsumed item. Use {@link #onBackpressureBuffer(boolean)} + * to have the operator keep the original signal order. *

*
Backpressure:
*
The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded @@ -12097,6 +12103,7 @@ public final Flowable ofType(@NonNull Class clazz) { * * @return the current {@code Flowable} modified to buffer items to the extent system resources allow * @see ReactiveX operators documentation: backpressure operators + * #see {@link #onBackpressureBuffer(boolean)} */ @CheckReturnValue @BackpressureSupport(BackpressureKind.UNBOUNDED_IN) @@ -12107,8 +12114,8 @@ public final Flowable onBackpressureBuffer() { } /** - * Instructs a {@link Publisher} that is emitting items faster than its {@link Subscriber} can consume them to buffer these - * items indefinitely until they can be emitted. + * Buffers an unlimited number of items from the current {@code Flowable} and allows it to emit as fast it can while allowing the + * downstream to consume the items at its own place, optionally delaying an error until all buffered items have been consumed. *

* *

@@ -12134,12 +12141,15 @@ public final Flowable onBackpressureBuffer(boolean delayError) { } /** - * Instructs a {@link Publisher} that is emitting items faster than its {@link Subscriber} can consume them to buffer up to - * a given amount of items until they can be emitted. The resulting {@code Flowable} will signal - * a {@code BufferOverflowException} via {@code onError} as soon as the buffer's capacity is exceeded, dropping all undelivered - * items, and canceling the source. + * Buffers an limited number of items from the current {@code Flowable} and allows it to emit as fast it can while allowing the + * downstream to consume the items at its own place, however, the resulting {@code Flowable} will signal a + * {@link MissingBackpressureException} via {@code onError} as soon as the buffer's capacity is exceeded, dropping all undelivered + * items, and canceling the flow. *

* + *

+ * An error from the current {@code Flowable} will cut ahead of any unconsumed item. Use {@link #onBackpressureBuffer(int, boolean)} + * to have the operator keep the original signal order. *

*
Backpressure:
*
The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded @@ -12153,6 +12163,7 @@ public final Flowable onBackpressureBuffer(boolean delayError) { * @throws IllegalArgumentException if {@code capacity} is non-positive * @see ReactiveX operators documentation: backpressure operators * @since 1.1.0 + * @see #onBackpressureBuffer(long, Action, BackpressureOverflowStrategy) */ @CheckReturnValue @BackpressureSupport(BackpressureKind.ERROR) @@ -12163,10 +12174,10 @@ public final Flowable onBackpressureBuffer(int capacity) { } /** - * Instructs a {@link Publisher} that is emitting items faster than its {@link Subscriber} can consume them to buffer up to - * a given amount of items until they can be emitted. The resulting {@code Flowable} will signal - * a {@code BufferOverflowException} via {@code onError} as soon as the buffer's capacity is exceeded, dropping all undelivered - * items, and canceling the source. + * Buffers an limited number of items from the current {@code Flowable} and allows it to emit as fast it can while allowing the + * downstream to consume the items at its own place, however, the resulting {@code Flowable} will signal a + * {@link MissingBackpressureException} via {@code onError} as soon as the buffer's capacity is exceeded, dropping all undelivered + * items, and canceling the flow. *

* *

@@ -12196,10 +12207,11 @@ public final Flowable onBackpressureBuffer(int capacity, boolean delayError) } /** - * Instructs a {@link Publisher} that is emitting items faster than its {@link Subscriber} can consume them to buffer up to - * a given amount of items until they can be emitted. The resulting {@code Flowable} will signal - * a {@code BufferOverflowException} via {@code onError} as soon as the buffer's capacity is exceeded, dropping all undelivered - * items, and canceling the source. + * Buffers an optionally unlimited number of items from the current {@code Flowable} and allows it to emit as fast it can while allowing the + * downstream to consume the items at its own place. + * If {@code unbounded} is {@code true}, the resulting {@code Flowable} will signal a + * {@link MissingBackpressureException} via {@code onError} as soon as the buffer's capacity is exceeded, dropping all undelivered + * items, and canceling the flow. *

* *

@@ -12232,10 +12244,11 @@ public final Flowable onBackpressureBuffer(int capacity, boolean delayError, } /** - * Instructs a {@link Publisher} that is emitting items faster than its {@link Subscriber} can consume them to buffer up to - * a given amount of items until they can be emitted. The resulting {@code Flowable} will signal - * a {@code BufferOverflowException} via {@code onError} as soon as the buffer's capacity is exceeded, dropping all undelivered - * items, canceling the source, and notifying the producer with {@code onOverflow}. + * Buffers an optionally unlimited number of items from the current {@code Flowable} and allows it to emit as fast it can while allowing the + * downstream to consume the items at its own place. + * If {@code unbounded} is {@code true}, the resulting {@code Flowable} will signal a + * {@link MissingBackpressureException} via {@code onError} as soon as the buffer's capacity is exceeded, dropping all undelivered + * items, canceling the flow and calling the {@code onOverflow} action. *

* *

@@ -12253,7 +12266,7 @@ public final Flowable onBackpressureBuffer(int capacity, boolean delayError, * any buffered element * @param unbounded * if {@code true}, the capacity value is interpreted as the internal "island" size of the unbounded buffer - * @param onOverflow action to execute if an item needs to be buffered, but there are no available slots. Null is allowed. + * @param onOverflow action to execute if an item needs to be buffered, but there are no available slots. * @return the current {@code Flowable} modified to buffer items up to the given capacity * @throws NullPointerException if {@code onOverflow} is {@code null} * @throws IllegalArgumentException if {@code capacity} is non-positive @@ -12272,10 +12285,10 @@ public final Flowable onBackpressureBuffer(int capacity, boolean delayError, } /** - * Instructs a {@link Publisher} that is emitting items faster than its {@link Subscriber} can consume them to buffer up to - * a given amount of items until they can be emitted. The resulting {@code Flowable} will signal - * a {@code BufferOverflowException} via {@code onError} as soon as the buffer's capacity is exceeded, dropping all undelivered - * items, canceling the source, and notifying the producer with {@code onOverflow}. + * Buffers an limited number of items from the current {@code Flowable} and allows it to emit as fast it can while allowing the + * downstream to consume the items at its own place, however, the resulting {@code Flowable} will signal a + * {@link MissingBackpressureException} via {@code onError} as soon as the buffer's capacity is exceeded, dropping all undelivered + * items, canceling the flow and calling the {@code onOverflow} action. *

* *

@@ -12303,10 +12316,9 @@ public final Flowable onBackpressureBuffer(int capacity, @NonNull Action onOv } /** - * Instructs a {@link Publisher} that is emitting items faster than its {@link Subscriber} can consume them to buffer up to - * a given amount of items until they can be emitted. The resulting {@code Flowable} will behave as determined - * by {@code overflowStrategy} if the buffer capacity is exceeded. - * + * Buffers an optionally unlimited number of items from the current {@code Flowable} and allows it to emit as fast it can while allowing the + * downstream to consume the items at its own place. + * The resulting {@code Flowable} will behave as determined by {@code overflowStrategy} if the buffer capacity is exceeded: *
    *
  • {@link BackpressureOverflowStrategy#ERROR} (default) will call {@code onError} dropping all undelivered items, * canceling the source, and notifying the producer with {@code onOverflow}.
    • @@ -12330,7 +12342,7 @@ 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, {@code null} is allowed. - * @param overflowStrategy how should the {@code Publisher} react to buffer overflows, {@code null} is not allowed. + * @param overflowStrategy how should the resulting {@code Flowable} react to buffer overflows, {@code null} is not allowed. * @return the source {@code Flowable} modified to buffer items up to the given capacity * @throws NullPointerException if {@code onOverflow} or {@code overflowStrategy} is {@code null} * @throws IllegalArgumentException if {@code capacity} is non-positive @@ -12348,13 +12360,13 @@ public final Flowable onBackpressureBuffer(long capacity, @Nullable Action on } /** - * Instructs a {@link Publisher} that is emitting items faster than its {@link Subscriber} can consume them to discard, - * rather than emit, those items that its {@code Subscriber} is not prepared to observe. + * Drops items from the current {@code Flowable} if the downstream is not ready to receive new items (indicated + * by a lack of {@link Subscription#request(long)} calls from it). *

    * *

    - * If the downstream request count hits 0 then the {@code Publisher} will refrain from calling {@code onNext} until - * the {@code Subscriber} invokes {@code request(n)} again to increase the request count. + * If the downstream request count hits 0 then the resulting {@code Flowable} will refrain from calling {@code onNext} until + * the {@link Subscriber} invokes {@code request(n)} again to increase the request count. *

    *
    Backpressure:
    *
    The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded @@ -12375,13 +12387,14 @@ public final Flowable onBackpressureDrop() { } /** - * Instructs a {@link Publisher} that is emitting items faster than its {@link Subscriber} can consume them to discard, - * rather than emit, those items that its {@code Subscriber} is not prepared to observe. + * Drops items from the current {@code Flowable} if the downstream is not ready to receive new items (indicated + * by a lack of {@link Subscription#request(long)} calls from it) and calls the given {@link Consumer} with such + * dropped items. *

    * *

    - * If the downstream request count hits 0 then the {@code Publisher} will refrain from calling {@code onNext} until - * the {@code Subscriber} invokes {@code request(n)} again to increase the request count. + * If the downstream request count hits 0 then the resulting {@code Flowable} will refrain from calling {@code onNext} until + * the {@link Subscriber} invokes {@code request(n)} again to increase the request count. *

    *
    Backpressure:
    *
    The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded @@ -12406,8 +12419,9 @@ public final Flowable onBackpressureDrop(@NonNull Consumer onDrop) } /** - * Instructs a {@link Publisher} that is emitting items faster than its {@link Subscriber} can consume them to - * hold onto the latest value and emit that on request. + * Drops all but the latest item emitted by the current {@code Flowable} if the downstream is not ready to receive + * new items (indicated by a lack of {@link Subscription#request(long)} calls from it) and emits this latest + * item when the downstream becomes ready. *

    * *

    @@ -12439,8 +12453,8 @@ public final Flowable onBackpressureLatest() { } /** - * Instructs a {@link Publisher} to pass control to another {@code Publisher} rather than invoking - * {@link Subscriber#onError onError} if it encounters an error. + * Resumes the flow with a {@link Publisher} returned for the failure {@link Throwable} of the current {@code Flowable} by a + * function instead of signaling the error via {@code onError}. *

    * *

    @@ -12484,8 +12498,8 @@ public final Flowable onErrorResumeNext(@NonNull Function * *

    @@ -12529,12 +12543,12 @@ public final Flowable onErrorResumeWith(@NonNull Publisher<@NonNull ? extends } /** - * Instructs a {@link Publisher} to emit an item (returned by a specified function) rather than invoking - * {@link Subscriber#onError onError} if it encounters an error. + * Ends the flow with a last item returned by a function for the {@link Throwable} error signaled by the current + * {@code Flowable} instead of signaling the error via {@code onError}. *

    * *

    - * By default, when a {@code Publisher} encounters an error that prevents it from emitting the expected item to + * By default, when a {@link Publisher} encounters an error that prevents it from emitting the expected item to * its {@link Subscriber}, the {@code Publisher} invokes its {@code Subscriber}'s {@code onError} method, and then quits * without invoking any more of its {@code Subscriber}'s methods. The {@code onErrorReturn} method changes this * behavior. If you pass a function ({@code resumeFunction}) to a {@code Publisher}'s {@code onErrorReturn} @@ -12570,12 +12584,11 @@ public final Flowable onErrorReturn(@NonNull Function * *

    - * By default, when a {@code Publisher} encounters an error that prevents it from emitting the expected item to + * By default, when a {@link Publisher} encounters an error that prevents it from emitting the expected item to * its {@link Subscriber}, the {@code Publisher} invokes its {@code Subscriber}'s {@code onError} method, and then quits * without invoking any more of its {@code Subscriber}'s methods. The {@code onErrorReturn} method changes this * behavior. If you pass a function ({@code resumeFunction}) to a {@code Publisher}'s {@code onErrorReturn} @@ -14562,10 +14575,10 @@ public final Flowable scan(@NonNull BiFunction accumulator) { } /** - * Forces a {@link Publisher}'s emissions and notifications to be serialized and for it to obey + * Forces the current {@code Flowable}'s emissions and notifications to be serialized and for it to obey * the {@code Publisher} contract in other ways. *

    - * It is possible for a {@code Publisher} to invoke its {@link Subscriber}s' methods asynchronously, perhaps from + * It is possible for a {@link Publisher} to invoke its {@link Subscriber}s' methods asynchronously, perhaps from * different threads. This could make such a {@code Publisher} 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 a {@code Publisher} to be @@ -15273,7 +15286,7 @@ public final Flowable startWithArray(@NonNull T... items) { } /** - * Subscribes to a {@link Publisher} and ignores {@code onNext} and {@code onComplete} emissions. + * Subscribes to the current {@code Flowable} and ignores {@code onNext} and {@code onComplete} emissions. *

    * If the {@code Flowable} emits an error, it is wrapped into an * {@link io.reactivex.rxjava3.exceptions.OnErrorNotImplementedException OnErrorNotImplementedException} @@ -15287,7 +15300,7 @@ public final Flowable startWithArray(@NonNull T... items) { *

    * * @return a {@link Disposable} reference with which the caller can stop receiving items before - * the {@code Publisher} has finished sending them + * the current {@code Flowable} has finished sending them * @see ReactiveX operators documentation: Subscribe */ @BackpressureSupport(BackpressureKind.UNBOUNDED_IN) @@ -15298,7 +15311,7 @@ public final Disposable subscribe() { } /** - * Subscribes to a {@link Publisher} and provides a callback to handle the items it emits. + * Subscribes to the current {@code Flowable} and provides a callback to handle the items it emits. *

    * If the {@code Flowable} emits an error, it is wrapped into an * {@link io.reactivex.rxjava3.exceptions.OnErrorNotImplementedException OnErrorNotImplementedException} @@ -15312,9 +15325,9 @@ public final Disposable subscribe() { *

    * * @param onNext - * the {@code Consumer} you have designed to accept emissions from the {@code Publisher} + * the {@code Consumer} you have designed to accept emissions from the current {@code Flowable} * @return a {@link Disposable} reference with which the caller can stop receiving items before - * the {@code Publisher} has finished sending them + * the current {@code Flowable} has finished sending them * @throws NullPointerException * if {@code onNext} is {@code null} * @see ReactiveX operators documentation: Subscribe @@ -15328,7 +15341,7 @@ public final Disposable subscribe(@NonNull Consumer onNext) { } /** - * Subscribes to a {@link Publisher} and provides callbacks to handle the items it emits and any error + * Subscribes to the current {@code Flowable} and provides callbacks to handle the items it emits and any error * notification it issues. *
    *
    Backpressure:
    @@ -15339,12 +15352,12 @@ public final Disposable subscribe(@NonNull Consumer onNext) { *
    * * @param onNext - * the {@code Consumer} you have designed to accept emissions from the {@code Publisher} + * the {@code Consumer} you have designed to accept emissions from the current {@code Flowable} * @param onError * the {@code Consumer} you have designed to accept any error notification from the - * {@code Publisher} + * current {@code Flowable} * @return a {@link Disposable} reference with which the caller can stop receiving items before - * the {@code Publisher} has finished sending them + * the current {@code Flowable} has finished sending them * @see ReactiveX operators documentation: Subscribe * @throws NullPointerException * if {@code onNext} or {@code onError} is {@code null} @@ -15358,7 +15371,7 @@ public final Disposable subscribe(@NonNull Consumer onNext, @NonNull } /** - * Subscribes to a {@link Publisher} and provides callbacks to handle the items it emits and any error or + * Subscribes to the current {@code Flowable} and provides callbacks to handle the items it emits and any error or * completion notification it issues. *
    *
    Backpressure:
    @@ -15369,15 +15382,15 @@ public final Disposable subscribe(@NonNull Consumer onNext, @NonNull *
    * * @param onNext - * the {@code Consumer} you have designed to accept emissions from the {@code Publisher} + * the {@code Consumer} you have designed to accept emissions from the current {@code Flowable} * @param onError * the {@code Consumer} you have designed to accept any error notification from the - * {@code Publisher} + * current {@code Flowable} * @param onComplete * the {@link Action} you have designed to accept a completion notification from the - * {@code Publisher} + * the current {@code Flowable} * @return a {@link Disposable} reference with which the caller can stop receiving items before - * the {@code Publisher} has finished sending them + * the current {@code Flowable} has finished sending them * @throws NullPointerException * if {@code onNext}, {@code onError} or {@code onComplete} is {@code null} * @see ReactiveX operators documentation: Subscribe @@ -17549,9 +17562,9 @@ public final R to(@NonNull FlowableConverter converter) { * *

    * Normally, a {@code Publisher} that returns multiple items will do so by invoking its {@link Subscriber}'s - * {@link Subscriber#onNext onNext} method for each such item. You can change this behavior, instructing the - * {@code Publisher} to compose a list of all of these items and then to invoke the {@code Subscriber}'s {@code onNext} - * function once, passing it the entire list, by calling the {@code Publisher}'s {@code toList} method prior to + * {@link Subscriber#onNext onNext} method for each such item. You can change this behavior by having the + * operator compose a list of all of these items and then to invoke the {@link SingleObserver}'s {@code onSuccess} + * method once, passing it the entire list, by calling the {@code Flowable}'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 @@ -17584,9 +17597,9 @@ public final Single> toList() { * *

    * Normally, a {@code Publisher} that returns multiple items will do so by invoking its {@link Subscriber}'s - * {@link Subscriber#onNext onNext} method for each such item. You can change this behavior, instructing the - * {@code Publisher} to compose a list of all of these items and then to invoke the {@code Subscriber}'s {@code onNext} - * function once, passing it the entire list, by calling the {@code Publisher}'s {@code toList} method prior to + * {@link Subscriber#onNext onNext} method for each such item. You can change this behavior by having the + * operator compose a list of all of these items and then to invoke the {@link SingleObserver}'s {@code onSuccess} + * method once, passing it the entire list, by calling the {@code Flowable}'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 @@ -17623,9 +17636,9 @@ public final Single> toList(int capacityHint) { * *

    * Normally, a {@code Publisher} that returns multiple items will do so by invoking its {@link Subscriber}'s - * {@link Subscriber#onNext onNext} method for each such item. You can change this behavior, instructing the - * {@code Publisher} to compose a list of all of these items and then to invoke the {@code Subscriber}'s {@code onNext} - * function once, passing it the entire list, by calling the {@code Publisher}'s {@code toList} method prior to + * {@link Subscriber#onNext onNext} method for each such item. You can change this behavior by having the + * operator compose a collection of all of these items and then to invoke the {@link SingleObserver}'s {@code onSuccess} + * method once, passing it the entire collection, by calling the {@code Flowable}'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 @@ -18105,8 +18118,12 @@ public final Single> toSortedList(int capacityHint) { } /** - * Modifies the current {@code Flowable} so that subscribers will cancel it on a specified - * {@link Scheduler}. + * Cancels the current {@code Flowable} asynchronously by invoking {@link Subscription#cancel()} + * on the specified {@link Scheduler}. + *

    + * The operator suppresses signals from the current {@code Flowable} immediately when the + * downstream cancels the flow because the actual cancellation itself could take an arbitrary amount of time + * to take effect and make the flow stop producing items. *

    *
    Backpressure:
    *
    The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure diff --git a/src/main/java/io/reactivex/rxjava3/core/Maybe.java b/src/main/java/io/reactivex/rxjava3/core/Maybe.java index 6865558c05..ad4e824893 100644 --- a/src/main/java/io/reactivex/rxjava3/core/Maybe.java +++ b/src/main/java/io/reactivex/rxjava3/core/Maybe.java @@ -420,7 +420,7 @@ public static Flowable concatArrayDelayError(@NonNull MaybeSource - * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the + * Eager concatenation means that once an observer subscribes, this operator subscribes to all of the * source {@code MaybeSource}s. The operator buffers the value emitted by these {@code MaybeSource}s and then drains them * in order, each one after the previous one completes. *

    @@ -504,7 +504,7 @@ public static Flowable concatDelayError(@NonNull Publisher<@NonNull ? ext /** * Concatenates a sequence of {@link MaybeSource}s eagerly into a {@link Flowable} sequence. *

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

    @@ -2537,7 +2537,7 @@ public final Maybe cast(@NonNull Class clazz) { * This method operates on the {@code Maybe} itself whereas {@link #lift} operates on the {@code Maybe}'s {@link MaybeObserver}s. *

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

    *
    Scheduler:
    @@ -2559,7 +2559,7 @@ public final Maybe compose(@NonNull MaybeTransformer * @@ -2570,8 +2570,8 @@ public final Maybe compose(@NonNull MaybeTransformerNote that flatMap and concatMap for {@code Maybe} is the same operation. * @param the result value type * @param mapper - * a function that, when applied to the item emitted by the source {@code Maybe}, returns a {@code MaybeSource} - * @return the {@code Maybe} returned from {@code mapper} when applied to the item emitted by the source {@code Maybe} + * a function that, when applied to the item emitted by the current {@code Maybe}, returns a {@code MaybeSource} + * @return the {@code Maybe} returned from {@code mapper} when applied to the item emitted by the current {@code Maybe} * @see ReactiveX operators documentation: FlatMap * @throws NullPointerException if {@code mapper} is {@code null} */ @@ -2612,7 +2612,7 @@ public final Flowable concatWith(@NonNull MaybeSource other) { } /** - * Returns a {@link Single} that emits a {@link Boolean} that indicates whether the source {@code Maybe} emitted a + * Returns a {@link Single} that emits a {@link Boolean} that indicates whether the current {@code Maybe} emitted a * specified item. *

    * @@ -2622,9 +2622,9 @@ public final Flowable concatWith(@NonNull MaybeSource other) { *

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

    * @@ -2646,7 +2646,7 @@ public final Single contains(@NonNull Object item) { *

    {@code count} does not operate by default on a particular {@link Scheduler}.
    *
    * - * @return a {@code Single} that emits a single item: the number of items emitted by the source {@code Maybe} as a + * @return a {@code Single} that emits a single item: the number of items emitted by the current {@code Maybe} as a * 64-bit {@code Long} item * @see ReactiveX operators documentation: Count */ @@ -2658,8 +2658,8 @@ public final Single count() { } /** - * Returns a {@link Single} that emits the item emitted by the source {@code Maybe} or a specified default item - * if the source {@code Maybe} is empty. + * Returns a {@link Single} that emits the item emitted by the current {@code Maybe} or a specified default item + * if the current {@code Maybe} is empty. *

    * *

    @@ -2668,9 +2668,9 @@ public final Single count() { *
    * * @param defaultItem - * the item to emit if the source {@code Maybe} emits no items - * @return a {@code Single} that emits either the specified default item if the source {@code Maybe} emits no - * item, or the item emitted by the source {@code Maybe} + * the item to emit if the current {@code Maybe} emits no items + * @return a {@code Single} that emits either the specified default item if the current {@code Maybe} emits no + * item, or the item emitted by the current {@code Maybe} * @throws NullPointerException if {@code defaultItem} is {@code null} * @see ReactiveX operators documentation: DefaultIfEmpty */ @@ -2683,7 +2683,7 @@ public final Single defaultIfEmpty(@NonNull T defaultItem) { } /** - * Returns a {@code Maybe} that signals the events emitted by the source {@code Maybe} shifted forward in time by a + * Returns a {@code Maybe} that signals the events emitted by the current {@code Maybe} shifted forward in time by a * specified delay. *

    * @@ -2709,7 +2709,7 @@ public final Maybe delay(long delay, @NonNull TimeUnit unit) { } /** - * Returns a {@code Maybe} that signals the events emitted by the source {@code Maybe} shifted forward in time by a + * Returns a {@code Maybe} that signals the events emitted by the current {@code Maybe} shifted forward in time by a * specified delay running on the specified {@link Scheduler}. *

    * @@ -2796,7 +2796,7 @@ public final Maybe delaySubscription(@NonNull Publisher subscriptionIn } /** - * Returns a {@code Maybe} that delays the subscription to the source {@code Maybe} by a given amount of time. + * Returns a {@code Maybe} that delays the subscription to the current {@code Maybe} by a given amount of time. *

    * *

    @@ -2808,7 +2808,7 @@ public final Maybe delaySubscription(@NonNull Publisher subscriptionIn * the time to delay the subscription * @param unit * the time unit of {@code delay} - * @return a {@code Maybe} that delays the subscription to the source {@code Maybe} by the given amount + * @return a {@code Maybe} that delays the subscription to the current {@code Maybe} by the given amount * @throws NullPointerException if {@code unit} is {@code null} * @see ReactiveX operators documentation: Delay * @see #delaySubscription(long, TimeUnit, Scheduler) @@ -2821,7 +2821,7 @@ public final Maybe delaySubscription(long delay, @NonNull TimeUnit unit) { } /** - * Returns a {@code Maybe} that delays the subscription to the source {@code Maybe} by a given amount of time, + * Returns a {@code Maybe} that delays the subscription to the current {@code Maybe} by a given amount of time, * both waiting and subscribing on a given {@link Scheduler}. *

    * @@ -2836,7 +2836,7 @@ public final Maybe delaySubscription(long delay, @NonNull TimeUnit unit) { * the time unit of {@code delay} * @param scheduler * the {@code Scheduler} on which the waiting and subscription will happen - * @return a {@code Maybe} that delays the subscription to the source {@code Maybe} by a given + * @return a {@code Maybe} that delays the subscription to the current {@code Maybe} 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 @@ -2882,8 +2882,8 @@ public final Maybe doAfterSuccess(@NonNull Consumer onAfterSuccess *

    * * @param onAfterTerminate - * an {@code Action} to be invoked when the source {@code Maybe} finishes - * @return a {@code Maybe} that emits the same items as the source {@code Maybe}, then invokes the + * an {@code Action} to be invoked when the current {@code Maybe} finishes + * @return a {@code Maybe} that emits the same items as the current {@code Maybe}, then invokes the * {@code Action} * @throws NullPointerException if {@code onAfterTerminate} is {@code null} * @see ReactiveX operators documentation: Do @@ -2953,7 +2953,7 @@ public final Maybe doOnDispose(@NonNull Action onDispose) { } /** - * Modifies the source {@code Maybe} so that it invokes an action when it calls {@code onComplete}. + * Invokes an {@link Action} just before the current {@code Maybe} calls {@code onComplete}. *

    * *

    @@ -2962,7 +2962,7 @@ public final Maybe doOnDispose(@NonNull Action onDispose) { *
    * * @param onComplete - * the action to invoke when the source {@code Maybe} calls {@code onComplete} + * the action to invoke when the current {@code Maybe} calls {@code onComplete} * @return the new {@code Maybe} with the side-effecting behavior applied * @throws NullPointerException if {@code onComplete} is {@code null} * @see ReactiveX operators documentation: Do @@ -3124,9 +3124,9 @@ public final Maybe doOnSuccess(@NonNull Consumer onSuccess) { *
* * @param predicate - * a function that evaluates the item emitted by the source {@code Maybe}, returning {@code true} + * a function that evaluates the item emitted by the current {@code Maybe}, returning {@code true} * if it passes the filter - * @return a {@code Maybe} that emit the item emitted by the source {@code Maybe} that the filter + * @return a {@code Maybe} that emit the item emitted by the current {@code Maybe} that the filter * evaluates as {@code true} * @throws NullPointerException if {@code predicate} is {@code null} * @see ReactiveX operators documentation: Filter @@ -3140,7 +3140,7 @@ public final Maybe filter(@NonNull Predicate predicate) { } /** - * Returns a {@code Maybe} that is based on applying a specified function to the item emitted by the source {@code Maybe}, + * Returns a {@code Maybe} that is based on applying a specified function to the item emitted by the current {@code Maybe}, * where that function returns a {@link MaybeSource}. *

* @@ -3152,8 +3152,8 @@ public final Maybe filter(@NonNull Predicate predicate) { * * @param the result value type * @param mapper - * a function that, when applied to the item emitted by the source {@code Maybe}, returns a {@code MaybeSource} - * @return the {@code Maybe} returned from {@code mapper} when applied to the item emitted by the source {@code Maybe} + * a function that, when applied to the item emitted by the current {@code Maybe}, returns a {@code MaybeSource} + * @return the {@code Maybe} returned from {@code mapper} when applied to the item emitted by the current {@code Maybe} * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: FlatMap */ @@ -3202,7 +3202,7 @@ public final Maybe flatMap( /** * Returns a {@code Maybe} that emits the results of a specified function to the pair of values emitted by the - * source {@code Maybe} and a specified mapped {@link MaybeSource}. + * current {@code Maybe} and a specified mapped {@link MaybeSource}. *

* *

@@ -3215,7 +3215,7 @@ public final Maybe flatMap( * @param * the type of items emitted by the resulting {@code Maybe} * @param mapper - * a function that returns a {@code MaybeSource} for the item emitted by the source {@code Maybe} + * a function that returns a {@code MaybeSource} for the item emitted by the current {@code Maybe} * @param resultSelector * a function that combines one item emitted by each of the source and collection {@code MaybeSource} and * returns an item to be emitted by the resulting {@code MaybeSource} @@ -3234,7 +3234,7 @@ public final Maybe flatMap(@NonNull Function * @@ -3249,7 +3249,7 @@ public final Maybe flatMap(@NonNull FunctionReactiveX operators documentation: FlatMap @@ -3265,7 +3265,7 @@ public final Flowable flattenAsFlowable(@NonNull Function * @@ -3278,7 +3278,7 @@ public final Flowable flattenAsFlowable(@NonNull FunctionReactiveX operators documentation: FlatMap @@ -3292,7 +3292,7 @@ public final Observable flattenAsObservable(@NonNull Function * @@ -3303,8 +3303,8 @@ public final Observable flattenAsObservable(@NonNull Function the result value type * @param mapper - * a function that, when applied to the item emitted by the source {@code Maybe}, returns an {@code ObservableSource} - * @return the {@code Observable} returned from {@code mapper} when applied to the item emitted by the source {@code Maybe} + * a function that, when applied to the item emitted by the current {@code Maybe}, returns an {@code ObservableSource} + * @return the {@code Observable} returned from {@code mapper} when applied to the item emitted by the current {@code Maybe} * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: FlatMap */ @@ -3318,7 +3318,7 @@ public final Observable flatMapObservable(@NonNull Function * *
@@ -3330,9 +3330,9 @@ public final Observable flatMapObservable(@NonNull Function the result value type * @param mapper - * a function that, when applied to the item emitted by the source {@code Maybe}, returns a + * a function that, when applied to the item emitted by the current {@code Maybe}, returns a * {@code Flowable} - * @return the {@code Flowable} returned from {@code mapper} when applied to the item emitted by the source {@code Maybe} + * @return the {@code Flowable} returned from {@code mapper} when applied to the item emitted by the current {@code Maybe} * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: FlatMap */ @@ -3347,7 +3347,7 @@ public final Flowable flatMapPublisher(@NonNull Function * @@ -3358,9 +3358,9 @@ public final Flowable flatMapPublisher(@NonNull Function the result value type * @param mapper - * a function that, when applied to the item emitted by the source {@code Maybe}, returns a + * a function that, when applied to the item emitted by the current {@code Maybe}, returns a * {@code Single} - * @return the {@code Single} returned from {@code mapper} when applied to the item emitted by the source {@code Maybe} + * @return the {@code Single} returned from {@code mapper} when applied to the item emitted by the current {@code Maybe} * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: FlatMap */ @@ -3374,7 +3374,7 @@ public final Single flatMapSingle(@NonNull Function * @@ -3386,7 +3386,7 @@ public final Single flatMapSingle(@NonNull FunctionHistory: 2.0.2 - experimental * @param the result value type * @param mapper - * a function that, when applied to the item emitted by the source {@code Maybe}, returns a + * a function that, when applied to the item emitted by the current {@code Maybe}, returns a * {@code Single} * @return the new {@code Maybe} instance * @throws NullPointerException if {@code mapper} is {@code null} @@ -3403,7 +3403,7 @@ public final Maybe flatMapSingleElement(@NonNull Function * *
@@ -3412,9 +3412,9 @@ public final Maybe flatMapSingleElement(@NonNull Function * * @param mapper - * a function that, when applied to the item emitted by the source {@code Maybe}, returns a + * a function that, when applied to the item emitted by the current {@code Maybe}, returns a * {@code Completable} - * @return the {@code Completable} returned from {@code mapper} when applied to the item emitted by the source {@code Maybe} + * @return the {@code Completable} returned from {@code mapper} when applied to the item emitted by the current {@code Maybe} * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: FlatMap */ @@ -3446,7 +3446,7 @@ public final Maybe hide() { } /** - * Returns a {@link Completable} that ignores the item emitted by the source {@code Maybe} and only calls {@code onComplete} or {@code onError}. + * Returns a {@link Completable} that ignores the item emitted by the current {@code Maybe} and only calls {@code onComplete} or {@code onError}. *

* *

@@ -3455,7 +3455,7 @@ public final Maybe hide() { *
* * @return an empty {@code Completable} that only calls {@code onComplete} or {@code onError}, based on which one is - * called by the source {@code Maybe} + * called by the current {@code Maybe} * @see ReactiveX operators documentation: IgnoreElements */ @CheckReturnValue @@ -3466,7 +3466,7 @@ public final Completable ignoreElement() { } /** - * Returns a {@link Single} that emits {@code true} if the source {@code Maybe} is empty, otherwise {@code false}. + * Returns a {@link Single} that emits {@code true} if the current {@code Maybe} is empty, otherwise {@code false}. *

* *

@@ -3474,7 +3474,7 @@ public final Completable ignoreElement() { *
{@code isEmpty} does not operate by default on a particular {@link Scheduler}.
*
* - * @return a {@code Single} that emits {@code true} if the source {@code Maybe} is empty. + * @return a {@code Single} that emits {@code true} if the current {@code Maybe} is empty. * @see ReactiveX operators documentation: Contains */ @CheckReturnValue @@ -3614,7 +3614,7 @@ public final Single isEmpty() { *

* Note also that it is not possible to stop the subscription phase in {@code lift()} as the {@code apply()} method * requires a non-{@code null} {@code MaybeObserver} instance to be returned, which is then unconditionally subscribed to - * the upstream {@code Maybe}. For example, if the operator decided there is no reason to subscribe to the + * the current {@code Maybe}. 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 a {@code MaybeObserver} that should immediately dispose the upstream's {@link Disposable} in its * {@code onSubscribe} method. Again, using a {@code MaybeTransformer} and extending the {@code Maybe} is @@ -3643,7 +3643,7 @@ public final Maybe lift(@NonNull MaybeOperator li } /** - * Returns a {@code Maybe} that applies a specified function to the item emitted by the source {@code Maybe} and + * Returns a {@code Maybe} that applies a specified function to the item emitted by the current {@code Maybe} and * emits the result of this function application. *

* @@ -3655,7 +3655,7 @@ public final Maybe lift(@NonNull MaybeOperator li * @param the result value type * @param mapper * a function to apply to the item emitted by the {@code Maybe} - * @return a {@code Maybe} that emits the item from the source {@code Maybe}, transformed by the specified function + * @return a {@code Maybe} that emits the item from the current {@code Maybe}, transformed by the specified function * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: Map */ @@ -3756,7 +3756,7 @@ public final Maybe observeOn(@NonNull Scheduler scheduler) { * * @param the output type * @param clazz - * the class type to filter the items emitted by the source {@code Maybe} + * the class type to filter the items emitted by the current {@code Maybe} * @return the new {@code Maybe} instance * @throws NullPointerException if {@code clazz} is {@code null} * @see ReactiveX operators documentation: Filter @@ -3887,8 +3887,8 @@ public final Maybe onErrorComplete(@NonNull Predicate pred } /** - * Instructs a {@code Maybe} to pass control to another {@link MaybeSource} rather than invoking - * {@link MaybeObserver#onError onError} if it encounters an error. + * Resumes the flow with the given {@link MaybeSource} when the current {@code Maybe} fails instead of + * signaling the error via {@code onError}. *

* *

@@ -3900,7 +3900,7 @@ public final Maybe onErrorComplete(@NonNull Predicate pred *

* * @param next - * the next {@code MaybeSource} that will take over if the source {@code Maybe} encounters + * the next {@code MaybeSource} that will take over if the current {@code Maybe} encounters * an error * @return the new {@code Maybe} instance * @throws NullPointerException if {@code next} is {@code null} @@ -3915,8 +3915,8 @@ public final Maybe onErrorResumeWith(@NonNull MaybeSource next) } /** - * Instructs a {@code Maybe} to pass control to another {@link MaybeSource} rather than invoking - * {@link MaybeObserver#onError onError} if it encounters an error. + * Resumes the flow with a {@link MaybeSource} returned for the failure {@link Throwable} of the current {@code Maybe} by a + * function instead of signaling the error via {@code onError}. *

* *

@@ -3928,7 +3928,7 @@ public final Maybe onErrorResumeWith(@NonNull MaybeSource next) *

* * @param resumeFunction - * a function that returns a {@code MaybeSource} that will take over if the source {@code Maybe} encounters + * a function that returns a {@code MaybeSource} that will take over if the current {@code Maybe} encounters * an error * @return the new {@code Maybe} instance * @throws NullPointerException if {@code resumeFunction} is {@code null} @@ -3943,8 +3943,8 @@ public final Maybe onErrorResumeNext(@NonNull Function * *

@@ -3971,8 +3971,7 @@ public final Maybe onErrorReturn(@NonNull Function * *

@@ -3998,8 +3997,8 @@ public final Maybe onErrorReturnItem(@NonNull T item) { } /** - * Instructs a {@code Maybe} to pass control to another {@link MaybeSource} rather than invoking - * {@link MaybeObserver#onError onError} if it encounters an {@link java.lang.Exception}. + * Resumes the flow with the given {@link MaybeSource} when the current {@code Maybe} fails + * with an {@link Exception} subclass instead of signaling the error via {@code onError}. *

* This differs from {@link #onErrorResumeNext} in that this one does not handle {@link java.lang.Throwable} * or {@link java.lang.Error} but lets those continue through. @@ -4014,7 +4013,7 @@ public final Maybe onErrorReturnItem(@NonNull T item) { *

* * @param next - * the next {@code MaybeSource} that will take over if the source {@code Maybe} encounters + * the next {@code MaybeSource} that will take over if the current {@code Maybe} encounters * an exception * @return the new {@code Maybe} instance * @throws NullPointerException if {@code next} is {@code null} @@ -4048,7 +4047,7 @@ public final Maybe onTerminateDetach() { } /** - * Returns a {@link Flowable} that repeats the sequence of items emitted by the source {@code Maybe} indefinitely. + * Returns a {@link Flowable} that repeats the sequence of items emitted by the current {@code Maybe} indefinitely. *

* *

@@ -4058,7 +4057,7 @@ public final Maybe onTerminateDetach() { *
{@code repeat} does not operate by default on a particular {@link Scheduler}.
*
* - * @return a {@code Flowable} that emits the items emitted by the source {@code Maybe} repeatedly and in sequence + * @return a {@code Flowable} that emits the items emitted by the current {@code Maybe} repeatedly and in sequence * @see ReactiveX operators documentation: Repeat */ @BackpressureSupport(BackpressureKind.FULL) @@ -4070,7 +4069,7 @@ public final Flowable repeat() { } /** - * Returns a {@link Flowable} that repeats the sequence of items emitted by the source {@code Maybe} at most + * Returns a {@link Flowable} that repeats the sequence of items emitted by the current {@code Maybe} at most * {@code count} times. *

* @@ -4082,9 +4081,9 @@ public final Flowable repeat() { *

* * @param times - * the number of times the source {@code Maybe} items are repeated, a count of 0 will yield an empty + * the number of times the current {@code Maybe} items are repeated, a count of 0 will yield an empty * sequence - * @return a {@code Flowable} that repeats the sequence of items emitted by the source {@code Maybe} at most + * @return a {@code Flowable} that repeats the sequence of items emitted by the current {@code Maybe} at most * {@code count} times * @throws IllegalArgumentException * if {@code times} is negative @@ -4099,7 +4098,7 @@ public final Flowable repeat(long times) { } /** - * Returns a {@link Flowable} that repeats the sequence of items emitted by the source {@code Maybe} until + * Returns a {@link Flowable} that repeats the sequence of items emitted by the current {@code Maybe} until * the provided stop function returns {@code true}. *

* @@ -4127,12 +4126,12 @@ public final Flowable repeatUntil(@NonNull BooleanSupplier stop) { } /** - * Returns a {@link Flowable} that emits the same values as the source {@code Maybe} with the exception of an + * Returns a {@link Flowable} that emits the same values as the current {@code Maybe} 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 {@link Publisher} provided as an argument to the {@code notificationHandler} - * function. If that {@code Publisher} calls {@code onComplete} or {@code onError} then {@code repeatWhen} will - * call {@code onComplete} or {@code onError} on the child subscription. Otherwise, this {@code Publisher} will - * resubscribe to the source {@code Publisher}. + * a {@code void} item to the {@code Flowable} provided as an argument to the {@code notificationHandler} + * function. If that {@link Publisher} calls {@code onComplete} or {@code onError} then {@code repeatWhen} will + * call {@code onComplete} or {@code onError} on the child observer. Otherwise, this operator will + * resubscribe to the current {@code Maybe}. *

* *

@@ -4145,7 +4144,7 @@ public final Flowable repeatUntil(@NonNull BooleanSupplier stop) { * * @param handler * receives a {@code Publisher} of notifications with which a user can complete or error, aborting the repeat. - * @return the source {@code Publisher} modified with repeat logic + * @return the new {@code Flowable} instance * @throws NullPointerException if {@code handler} is {@code null} * @see ReactiveX operators documentation: Repeat */ @@ -4158,12 +4157,12 @@ public final Flowable repeatWhen(@NonNull Function, } /** - * Returns a {@code Maybe} that mirrors the source {@code Maybe}, resubscribing to it if it calls {@code onError} + * Returns a {@code Maybe} that mirrors the current {@code Maybe}, resubscribing to it if it calls {@code onError} * (infinite retry count). *

* *

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

*
Scheduler:
@@ -4181,7 +4180,7 @@ public final Maybe retry() { } /** - * Returns a {@code Maybe} that mirrors the source {@code Maybe}, resubscribing to it if it calls {@code onError} + * Returns a {@code Maybe} that mirrors the current {@code Maybe}, resubscribing to it if it calls {@code onError} * and the predicate returns {@code true} for that specific exception and retry count. *

* @@ -4206,12 +4205,12 @@ public final Maybe retry(@NonNull BiPredicate * *

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

@@ -4289,12 +4288,12 @@ public final Maybe retryUntil(@NonNull BooleanSupplier stop) { } /** - * Returns a {@code Maybe} that emits the same values as the source {@code Maybe} with the exception of an + * Returns a {@code Maybe} that emits the same values as the current {@code Maybe} 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 {@link Publisher} provided as an argument to the {@code notificationHandler} - * function. If that {@code Publisher} calls {@code onComplete} or {@code onError} then {@code retry} will call - * {@code onComplete} or {@code onError} on the child subscription. Otherwise, this {@code Publisher} will - * resubscribe to the source {@code Publisher}. + * {@link Throwable} item to the {@link Flowable} provided as an argument to the {@code notificationHandler} + * function. If the returned {@link Publisher} calls {@code onComplete} or {@code onError} then {@code retry} will call + * {@code onComplete} or {@code onError} on the child subscription. Otherwise, this operator will + * resubscribe to the current {@code Maybe}. *

* *

@@ -4565,7 +4564,7 @@ public final Maybe subscribeOn(@NonNull Scheduler scheduler) { } /** - * Returns a {@code Maybe} that emits the items emitted by the source {@code Maybe} or the items of an alternate + * Returns a {@code Maybe} that emits the items emitted by the current {@code Maybe} or the items of an alternate * {@link MaybeSource} if the current {@code Maybe} is empty. *

* @@ -4576,8 +4575,8 @@ public final Maybe subscribeOn(@NonNull Scheduler scheduler) { * * @param other * the alternate {@code MaybeSource} to subscribe to if the main does not emit any items - * @return a {@code Maybe} that emits the items emitted by the source {@code Maybe} or the items of an - * alternate {@code MaybeSource} if the source {@code Maybe} is empty. + * @return a {@code Maybe} that emits the items emitted by the current {@code Maybe} or the items of an + * alternate {@code MaybeSource} if the current {@code Maybe} is empty. * @throws NullPointerException if {@code other} is {@code null} */ @CheckReturnValue @@ -4589,7 +4588,7 @@ public final Maybe switchIfEmpty(@NonNull MaybeSource other) { } /** - * Returns a {@link Single} that emits the items emitted by the source {@code Maybe} or the item of an alternate + * Returns a {@link Single} that emits the items emitted by the current {@code Maybe} or the item of an alternate * {@link SingleSource} if the current {@code Maybe} is empty. *

* @@ -4600,8 +4599,8 @@ public final Maybe switchIfEmpty(@NonNull MaybeSource other) { *

History: 2.1.4 - experimental * @param other * the alternate {@code SingleSource} to subscribe to if the main does not emit any items - * @return a {@code Single} that emits the items emitted by the source {@code Maybe} or the item of an - * alternate {@code SingleSource} if the source {@code Maybe} is empty. + * @return a {@code Single} that emits the items emitted by the current {@code Maybe} or the item of an + * alternate {@code SingleSource} if the current {@code Maybe} is empty. * @throws NullPointerException if {@code other} is {@code null} * @since 2.2 */ @@ -4614,7 +4613,7 @@ public final Single switchIfEmpty(@NonNull SingleSource other) { } /** - * Returns a {@code Maybe} that emits the items emitted by the source {@code Maybe} until a second {@link MaybeSource} + * Returns a {@code Maybe} that emits the items emitted by the current {@code Maybe} until a second {@link MaybeSource} * emits an item. *

* @@ -4625,10 +4624,10 @@ public final Single switchIfEmpty(@NonNull SingleSource other) { * * @param other * the {@code MaybeSource} whose first emitted item will cause {@code takeUntil} to stop emitting items - * from the source {@code Maybe} + * from the current {@code Maybe} * @param * the type of items emitted by {@code other} - * @return a {@code Maybe} that emits the items emitted by the source {@code Maybe} until such time as {@code other} emits its first item + * @return a {@code Maybe} that emits the items emitted by the current {@code Maybe} until such time as {@code other} emits its first item * @throws NullPointerException if {@code other} is {@code null} * @see ReactiveX operators documentation: TakeUntil */ @@ -4641,7 +4640,7 @@ public final Maybe takeUntil(@NonNull MaybeSource other) { } /** - * Returns a {@code Maybe} that emits the item emitted by the source {@code Maybe} until a second {@link Publisher} + * Returns a {@code Maybe} that emits the item emitted by the current {@code Maybe} until a second {@link Publisher} * emits an item. *

* @@ -4658,7 +4657,7 @@ public final Maybe takeUntil(@NonNull MaybeSource other) { * from the source {@code Publisher} * @param * the type of items emitted by {@code other} - * @return a {@code Maybe} that emits the items emitted by the source {@code Maybe} until such time as {@code other} emits its first item + * @return a {@code Maybe} that emits the items emitted by the current {@code Maybe} until such time as {@code other} emits its first item * @throws NullPointerException if {@code other} is {@code null} * @see ReactiveX operators documentation: TakeUntil */ @@ -4672,7 +4671,7 @@ public final Maybe takeUntil(@NonNull Publisher other) { } /** - * Returns a {@code Maybe} that mirrors the source {@code Maybe} but applies a timeout policy for each emitted + * Returns a {@code Maybe} that mirrors the current {@code Maybe} 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 resulting {@code Maybe} terminates and notifies {@link MaybeObserver}s of a {@link TimeoutException}. *

@@ -4698,9 +4697,9 @@ public final Maybe timeout(long timeout, @NonNull TimeUnit unit) { } /** - * Returns a {@code Maybe} that mirrors the source {@code Maybe} but applies a timeout policy for each emitted + * Returns a {@code Maybe} that mirrors the current {@code Maybe} 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 {@link MaybeSource} is disposed and resulting {@code Maybe} begins instead to mirror a fallback {@code MaybeSource}. + * the current {@code Maybe} is disposed and resulting {@code Maybe} begins instead to mirror a fallback {@link MaybeSource}. *

* *

@@ -4727,10 +4726,10 @@ public final Maybe timeout(long timeout, @NonNull TimeUnit unit, @NonNull May } /** - * Returns a {@code Maybe} that mirrors the source {@code Maybe} but applies a timeout policy for each emitted + * Returns a {@code Maybe} that mirrors the current {@code Maybe} 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 source {@link MaybeSource} is disposed and resulting {@code Maybe} begins instead - * to mirror a fallback {@code MaybeSource}. + * starting from its predecessor, the current {@code Maybe} is disposed and resulting {@code Maybe} begins instead + * to mirror a fallback {@link MaybeSource}. *

* *

@@ -4759,7 +4758,7 @@ public final Maybe timeout(long timeout, @NonNull TimeUnit unit, @NonNull Sch } /** - * Returns a {@code Maybe} that mirrors the source {@code Maybe} but applies a timeout policy for each emitted + * Returns a {@code Maybe} that mirrors the current {@code Maybe} 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 Maybe} terminates and * notifies {@link MaybeObserver}s of a {@link TimeoutException}. diff --git a/src/main/java/io/reactivex/rxjava3/core/Observable.java b/src/main/java/io/reactivex/rxjava3/core/Observable.java index 6b118b70b5..2123f8e328 100644 --- a/src/main/java/io/reactivex/rxjava3/core/Observable.java +++ b/src/main/java/io/reactivex/rxjava3/core/Observable.java @@ -8493,7 +8493,8 @@ public final Observable doOnEach(@NonNull Observer observer) { } /** - * Modifies the current {@code Observable} so that it invokes an action if it calls {@code onError}. + * Calls the given {@link Consumer} with the error {@link Throwable} if the current {@code Observable} failed before forwarding it to + * the downstream. *

* 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}. @@ -8545,7 +8546,7 @@ public final Observable doOnLifecycle(@NonNull Consumer o } /** - * Modifies the current {@code Observable} so that it invokes an action when it calls {@code onNext}. + * Calls the given {@link Consumer} with the value emitted by the current {@code Observable} before forwarding it to the downstream. *

* *

@@ -10484,8 +10485,8 @@ public final Observable ofType(@NonNull Class clazz) { } /** - * Instructs the current {@code Observable} to pass control to another {@link ObservableSource} rather than invoking - * {@link Observer#onError onError} if it encounters an error. + * Resumes the flow with an {@link ObservableSource} returned for the failure {@link Throwable} of the current {@code Observable} by a + * function instead of signaling the error via {@code onError}. *

* *

@@ -10522,8 +10523,8 @@ public final Observable onErrorResumeNext(@NonNull Function * *

@@ -10560,8 +10561,8 @@ public final Observable onErrorResumeWith(@NonNull ObservableSource * *

@@ -10595,8 +10596,7 @@ public final Observable onErrorReturn(@NonNull Function * *

@@ -14724,9 +14724,9 @@ public final R to(@NonNull ObservableConverter converter) { * *

* 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 - * {@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 + * {@link Observer#onNext onNext} method for each such item. You can change this behavior by having the + * operator to compose a list of all of these items and then to invoke the {@link SingleObserver}'s {@code onSuccess} + * method once, passing it the entire list, by calling the {@code Observable}'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 @@ -14755,9 +14755,9 @@ public final R to(@NonNull ObservableConverter converter) { * *

* 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 - * {@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 + * {@link Observer#onNext onNext} method for each such item. You can change this behavior by having the + * operator to compose a list of all of these items and then to invoke the {@link SingleObserver}'s {@code onSuccess} + * method once, passing it the entire list, by calling the {@code Observable}'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 @@ -14790,9 +14790,9 @@ public final R to(@NonNull ObservableConverter converter) { * *

* 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 - * {@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 + * {@link Observer#onNext onNext} method for each such item. You can change this behavior by having the + * operator to compose a collection of all of these items and then to invoke the {@link SingleObserver}'s {@code onSuccess} + * method once, passing it the entire collection, by calling the {@code Observable}'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 diff --git a/src/main/java/io/reactivex/rxjava3/core/Single.java b/src/main/java/io/reactivex/rxjava3/core/Single.java index b5dde711ba..4b22be8dcf 100644 --- a/src/main/java/io/reactivex/rxjava3/core/Single.java +++ b/src/main/java/io/reactivex/rxjava3/core/Single.java @@ -2092,7 +2092,7 @@ public final Single hide() { * This method operates on the {@code Single} itself whereas {@link #lift} operates on {@link SingleObserver}s. *

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

*
Scheduler:
@@ -2158,7 +2158,7 @@ public final Single cast(@NonNull Class clazz) { } /** - * Returns a {@link Flowable} that emits the item emitted by the source {@code Single}, then the item emitted by the + * Returns a {@link Flowable} that emits the item emitted by the current {@code Single}, then the item emitted by the * specified {@link SingleSource}. *

* @@ -2171,7 +2171,7 @@ public final Single cast(@NonNull Class clazz) { * * @param other * a {@code SingleSource} to be concatenated after the current - * @return the new {@code Flowable} that emits the item emitted by the source {@code Single}, followed by the item emitted by + * @return the new {@code Flowable} that emits the item emitted by the current {@code Single}, followed by the item emitted by * {@code other} * @throws NullPointerException if {@code other} is {@code null} * @see ReactiveX operators documentation: Concat @@ -2520,8 +2520,8 @@ public final Single doAfterSuccess(@NonNull Consumer onAfterSucces * *

History: 2.0.6 - experimental * @param onAfterTerminate - * an {@code Action} to be invoked when the source {@code Single} finishes - * @return the new {@code Single} that emits the same items as the source {@code Single}, then invokes the + * an {@code Action} to be invoked when the current {@code Single} finishes + * @return the new {@code Single} that emits the same items as the current {@code Single}, then invokes the * {@code Action} * @throws NullPointerException if {@code onAfterTerminate} is {@code null} * @see ReactiveX operators documentation: Do @@ -2716,9 +2716,9 @@ public final Single doOnDispose(@NonNull Action onDispose) { *

* * @param predicate - * a function that evaluates the item emitted by the source {@code Single}, returning {@code true} + * a function that evaluates the item emitted by the current {@code Single}, returning {@code true} * if it passes the filter - * @return the new {@link Maybe} that emit the item emitted by the source {@code Single} that the filter + * @return the new {@link Maybe} that emit the item emitted by the current {@code Single} that the filter * evaluates as {@code true} * @throws NullPointerException if {@code predicate} is {@code null} * @see ReactiveX operators documentation: Filter @@ -2732,7 +2732,7 @@ public final Maybe filter(@NonNull Predicate predicate) { } /** - * Returns a {@code Single} that is based on applying a specified function to the item emitted by the source {@code Single}, + * Returns a {@code Single} that is based on applying a specified function to the item emitted by the current {@code Single}, * where that function returns a {@link SingleSource}. *

* @@ -2743,8 +2743,8 @@ public final Maybe filter(@NonNull Predicate predicate) { * * @param the result value type * @param mapper - * a function that, when applied to the item emitted by the source {@code Single}, returns a {@code SingleSource} - * @return the new {@code Single} returned from {@code mapper} when applied to the item emitted by the source {@code Single} + * a function that, when applied to the item emitted by the current {@code Single}, returns a {@code SingleSource} + * @return the new {@code Single} returned from {@code mapper} when applied to the item emitted by the current {@code Single} * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: FlatMap */ @@ -2757,7 +2757,7 @@ public final Single flatMap(@NonNull Function * @@ -2768,8 +2768,8 @@ public final Single flatMap(@NonNull Function the result value type * @param mapper - * a function that, when applied to the item emitted by the source {@code Single}, returns a {@code MaybeSource} - * @return the new {@code Maybe} returned from {@code mapper} when applied to the item emitted by the source {@code Single} + * a function that, when applied to the item emitted by the current {@code Single}, returns a {@code MaybeSource} + * @return the new {@code Maybe} returned from {@code mapper} when applied to the item emitted by the current {@code Single} * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: FlatMap */ @@ -2783,7 +2783,7 @@ public final Maybe flatMapMaybe(@NonNull Function * *

@@ -2796,7 +2796,7 @@ public final Maybe flatMapMaybe(@NonNull Function the result value type * @param mapper - * a function that, when applied to the item emitted by the source {@code Single}, returns a + * a function that, when applied to the item emitted by the current {@code Single}, returns a * {@code Publisher} * @return the new {@code Flowable} instance * @throws NullPointerException if {@code mapper} is {@code null} @@ -2812,7 +2812,7 @@ public final Flowable flatMapPublisher(@NonNull Function * @@ -2827,7 +2827,7 @@ public final Flowable flatMapPublisher(@NonNull FunctionReactiveX operators documentation: FlatMap @@ -2843,7 +2843,7 @@ public final Flowable flattenAsFlowable(@NonNull Function * @@ -2856,7 +2856,7 @@ public final Flowable flattenAsFlowable(@NonNull FunctionReactiveX operators documentation: FlatMap @@ -2871,7 +2871,7 @@ public final Flowable flattenAsFlowable(@NonNull Function * @@ -2882,7 +2882,7 @@ public final Flowable flattenAsFlowable(@NonNull Function the result value type * @param mapper - * a function that, when applied to the item emitted by the source {@code Single}, returns an {@code ObservableSource} + * a function that, when applied to the item emitted by the current {@code Single}, returns an {@code ObservableSource} * @return the new {@code Observable} instance * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: FlatMap @@ -2897,7 +2897,7 @@ public final Flowable flattenAsFlowable(@NonNull Function * *
@@ -2906,7 +2906,7 @@ public final Flowable flattenAsFlowable(@NonNull Function * * @param mapper - * a function that, when applied to the item emitted by the source {@code Single}, returns a + * a function that, when applied to the item emitted by the current {@code Single}, returns a * {@code CompletableSource} * @return the new {@code Completable} instance * @throws NullPointerException if {@code mapper} is {@code null} @@ -3069,7 +3069,7 @@ public final T blockingGet() { *

* Note also that it is not possible to stop the subscription phase in {@code lift()} as the {@code apply()} method * requires a non-{@code null} {@code SingleObserver} instance to be returned, which is then unconditionally subscribed to - * the upstream {@code Single}. For example, if the operator decided there is no reason to subscribe to the + * the current {@code Single}. 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 a {@code SingleObserver} that should immediately dispose the upstream's {@link Disposable} in its * {@code onSubscribe} method. Again, using a {@code SingleTransformer} and extending the {@code Single} is @@ -3098,7 +3098,7 @@ public final Single lift(@NonNull SingleOperator } /** - * Returns a {@code Single} that applies a specified function to the item emitted by the source {@code Single} and + * Returns a {@code Single} that applies a specified function to the item emitted by the current {@code Single} and * emits the result of this function application. *

* @@ -3110,7 +3110,7 @@ public final Single lift(@NonNull SingleOperator * @param the result value type * @param mapper * a function to apply to the item emitted by the {@code Single} - * @return the new {@code Single} that emits the item from the source {@code Single}, transformed by the specified function + * @return the new {@code Single} that emits the item from the current {@code Single}, transformed by the specified function * @throws NullPointerException if {@code mapper} is {@code null} * @see ReactiveX operators documentation: Map */ @@ -3206,7 +3206,7 @@ public final Single contains(@NonNull Object value, @NonNull BiPredicat * * @param other * a {@code SingleSource} to be merged - * @return that emits all of the items emitted by the source {@code Single}s + * @return that emits all of the items emitted by the current {@code Single}s * @throws NullPointerException if {@code other} is {@code null} * @see ReactiveX operators documentation: Merge */ @@ -3219,7 +3219,7 @@ public final Flowable mergeWith(@NonNull SingleSource other) { } /** - * Modifies a {@code Single} to emit its item (or notify of its error) on a specified {@link Scheduler}, + * Signals the success item or the terminal signals of the current {@code Single} on the specified {@link Scheduler}, * asynchronously. *

* @@ -3230,8 +3230,7 @@ public final Flowable mergeWith(@NonNull SingleSource other) { * * @param scheduler * the {@code Scheduler} to notify subscribers on - * @return the source {@code Single} modified so that its subscribers are notified on the specified - * {@code Scheduler} + * @return the new {@code Single} instance * @throws NullPointerException if {@code scheduler} is {@code null} * @see ReactiveX operators documentation: ObserveOn * @see RxJava Threading Examples @@ -3246,8 +3245,8 @@ public final Single observeOn(@NonNull Scheduler scheduler) { } /** - * Instructs a {@code Single} to emit an item (returned by a specified function) rather than invoking - * {@link SingleObserver#onError onError} if it encounters an error. + * Ends the flow with a success item returned by a function for the {@link Throwable} error signaled by the current + * {@code Single} instead of signaling the error via {@code onError}. *

* *

@@ -3266,7 +3265,7 @@ public final Single observeOn(@NonNull Scheduler scheduler) { *

* * @param resumeFunction - * a function that returns an item that the new {@code Single} will emit if the source {@code Single} encounters + * a function that returns an item that the new {@code Single} will emit if the current {@code Single} encounters * an error * @return the new {@code Single} instance * @throws NullPointerException if {@code resumeFunction} is {@code null} @@ -3302,8 +3301,8 @@ public final Single onErrorReturnItem(@NonNull T value) { } /** - * Instructs a {@code Single} to pass control to another {@code Single} rather than invoking - * {@link SingleObserver#onError(Throwable)} if it encounters an error. + * Resumes the flow with the given {@link SingleSource} when the current {@code Single} fails instead of + * signaling the error via {@code onError}. *

* *

@@ -3338,8 +3337,8 @@ public final Single onErrorResumeWith(@NonNull SingleSource fall } /** - * Instructs a {@code Single} to pass control to another {@code Single} rather than invoking - * {@link SingleObserver#onError(Throwable)} if it encounters an error. + * Resumes the flow with a {@link SingleSource} returned for the failure {@link Throwable} of the current {@code Single} by a + * function instead of signaling the error via {@code onError}. *

* *

@@ -3828,7 +3827,7 @@ public final void subscribe(@NonNull SingleObserver observer) { } /** - * Asynchronously subscribes subscribers to this {@code Single} on the specified {@link Scheduler}. + * Asynchronously subscribes {@link SingleObserver}s to this {@code Single} on the specified {@link Scheduler}. *

* *

@@ -3838,7 +3837,7 @@ public final void subscribe(@NonNull SingleObserver observer) { * * @param scheduler * the {@code Scheduler} to perform subscription actions on - * @return the source {@code Single} modified so that its subscriptions happen on the specified {@code Scheduler} + * @return the new {@code Single} instance * @throws NullPointerException if {@code scheduler} is {@code null} * @see ReactiveX operators documentation: SubscribeOn * @see RxJava Threading Examples @@ -3853,7 +3852,7 @@ public final Single subscribeOn(@NonNull Scheduler scheduler) { } /** - * Returns a {@code Single} that emits the item emitted by the source {@code Single} until a {@link CompletableSource} terminates. Upon + * Returns a {@code Single} that emits the item emitted by the current {@code Single} until a {@link CompletableSource} terminates. Upon * termination of {@code other}, this will emit a {@link CancellationException} rather than go to * {@link SingleObserver#onSuccess(Object)}. *

@@ -3864,9 +3863,9 @@ public final Single subscribeOn(@NonNull Scheduler scheduler) { *

* * @param other - * the {@code CompletableSource} whose termination will cause {@code takeUntil} to emit the item from the source + * the {@code CompletableSource} whose termination will cause {@code takeUntil} to emit the item from the current * {@code Single} - * @return the new {@code Single} that emits the item emitted by the source {@code Single} until such time as {@code other} terminates. + * @return the new {@code Single} that emits the item emitted by the current {@code Single} until such time as {@code other} terminates. * @throws NullPointerException if {@code other} is {@code null} * @see ReactiveX operators documentation: TakeUntil */ @@ -3879,7 +3878,7 @@ public final Single takeUntil(@NonNull CompletableSource other) { } /** - * Returns a {@code Single} that emits the item emitted by the source {@code Single} until a {@link Publisher} emits an item or completes. Upon + * Returns a {@code Single} that emits the item emitted by the current {@code Single} until a {@link Publisher} emits an item or completes. Upon * emission of an item from {@code other}, this will emit a {@link CancellationException} rather than go to * {@link SingleObserver#onSuccess(Object)}. *

@@ -3894,10 +3893,10 @@ public final Single takeUntil(@NonNull CompletableSource other) { * * @param other * the {@code Publisher} whose first emitted item or completion will cause {@code takeUntil} to emit {@code CancellationException} - * if the upstream {@code Single} hasn't completed till then + * if the current {@code Single} hasn't completed till then * @param * the type of items emitted by {@code other} - * @return the new {@code Single} that emits the item emitted by the source {@code Single} until such time as {@code other} emits + * @return the new {@code Single} that emits the item emitted by the current {@code Single} until such time as {@code other} emits * its first item * @throws NullPointerException if {@code other} is {@code null} * @see ReactiveX operators documentation: TakeUntil @@ -3912,7 +3911,7 @@ public final Single takeUntil(@NonNull Publisher other) { } /** - * Returns a {@code Single} that emits the item emitted by the source {@code Single} until a second {@code Single} emits an item. Upon + * Returns a {@code Single} that emits the item emitted by the current {@code Single} until a second {@code Single} emits an item. Upon * emission of an item from {@code other}, this will emit a {@link CancellationException} rather than go to * {@link SingleObserver#onSuccess(Object)}. *

@@ -3924,10 +3923,10 @@ public final Single takeUntil(@NonNull Publisher other) { * * @param other * the {@code Single} whose emitted item will cause {@code takeUntil} to emit {@code CancellationException} - * if the upstream {@code Single} hasn't completed till then + * if the current {@code Single} hasn't completed till then * @param * the type of item emitted by {@code other} - * @return the new {@code Single} that emits the item emitted by the source {@code Single} until such time as {@code other} emits its item + * @return the new {@code Single} that emits the item emitted by the current {@code Single} until such time as {@code other} emits its item * @throws NullPointerException if {@code other} is {@code null} * @see ReactiveX operators documentation: TakeUntil */ @@ -4075,7 +4074,7 @@ public final R to(@NonNull SingleConverter converter) { *

{@code ignoreElement} does not operate by default on a particular {@link Scheduler}.
*
* - * @return a {@code Completable} that signals {@code onComplete} on it's observer when the source {@code Single} + * @return a {@code Completable} that signals {@code onComplete} on it's observer when the current {@code Single} * calls {@code onSuccess}. * @since 2.1.13 */ @@ -4198,7 +4197,7 @@ public final Single unsubscribeOn(@NonNull Scheduler scheduler) { /** * Returns a {@code Single} that emits the result of applying a specified function to the pair of items emitted by - * the source {@code Single} and another specified {@link SingleSource}. + * the current {@code Single} and another specified {@link SingleSource}. *

* *

@@ -4215,7 +4214,7 @@ public final Single unsubscribeOn(@NonNull Scheduler scheduler) { * @param zipper * a function that combines the pairs of items from the two {@code SingleSource}s to generate the items to * be emitted by the resulting {@code Single} - * @return the new {@code Single} that pairs up values from the source {@code Single} and the {@code other} {@code SingleSource} + * @return the new {@code Single} that pairs up values from the current {@code Single} and the {@code other} {@code SingleSource} * 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 diff --git a/src/test/java/io/reactivex/rxjava3/validators/JavadocWording.java b/src/test/java/io/reactivex/rxjava3/validators/JavadocWording.java index 4bcb1c41c1..a20245d10b 100644 --- a/src/test/java/io/reactivex/rxjava3/validators/JavadocWording.java +++ b/src/test/java/io/reactivex/rxjava3/validators/JavadocWording.java @@ -250,11 +250,41 @@ public void flowableDocRefersToFlowableTypes() throws Exception { } jdx = 0; for (;;) { - int idx = m.javadoc.indexOf("Observer", jdx); + int idx = m.javadoc.indexOf(" Observer", jdx); if (idx >= 0) { if (!m.signature.contains("ObservableSource") && !m.signature.contains("Observable")) { - e.append("java.lang.RuntimeException: Flowable doc mentions Observer but not using Flowable\r\n at io.reactivex.rxjava3.core.") + e.append("java.lang.RuntimeException: Flowable doc mentions Observer but not using Observable\r\n at io.reactivex.rxjava3.core.") + .append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n"); + } + + jdx = idx + 6; + } else { + break; + } + } + jdx = 0; + for (;;) { + int idx = m.javadoc.indexOf(" SingleObserver", jdx); + if (idx >= 0) { + if (!m.signature.contains("SingleSource") + && !m.signature.contains("Single")) { + e.append("java.lang.RuntimeException: Flowable doc mentions SingleObserver but not using Single\r\n at io.reactivex.rxjava3.core.") + .append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n"); + } + + jdx = idx + 6; + } else { + break; + } + } + jdx = 0; + for (;;) { + int idx = m.javadoc.indexOf(" MaybeObserver", jdx); + if (idx >= 0) { + if (!m.signature.contains("MaybeSource") + && !m.signature.contains("Maybe")) { + e.append("java.lang.RuntimeException: Flowable doc mentions MaybeObserver but not using Maybe\r\n at io.reactivex.rxjava3.core.") .append("Flowable.method(Flowable.java:").append(m.javadocLine + lineNumber(m.javadoc, idx) - 1).append(")\r\n\r\n"); }