Skip to content

Commit

Permalink
3.x: fromRunnable/fromAction javadoc improvements (#7071)
Browse files Browse the repository at this point in the history
  • Loading branch information
@akarnokd
akarnokd authored Sep 12, 2020
1 parent 7693126 commit 0f21ba8
Show file tree
Hide file tree
Showing 4 changed files with 54 additions and 23 deletions.
16 changes: 11 additions & 5 deletions src/main/java/io/reactivex/rxjava3/core/Completable.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -528,8 +528,8 @@ public static Completable error(@NonNull Throwable throwable) {
}

/**
* Returns a {@code Completable} instance that runs the given {@link Action} for each subscriber and
* emits either an unchecked exception or simply completes.
* Returns a {@code Completable} instance that runs the given {@link Action} for each {@link CompletableObserver} and
* emits either an exception or simply completes.
* <p>
* <img width="640" height="297" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.fromAction.png" alt="">
* <dl>
Expand All @@ -543,7 +543,7 @@ public static Completable error(@NonNull Throwable throwable) {
* {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
* </dd>
* </dl>
* @param action the {@code Action} to run for each subscribing {@link CompletableObserver}
* @param action the {@code Action} to run for each subscribing {@code CompletableObserver}
* @return the new {@code Completable} instance
* @throws NullPointerException if {@code action} is {@code null}
*/
Expand Down Expand Up @@ -636,14 +636,19 @@ public static <T> Completable fromMaybe(@NonNull MaybeSource<T> maybe) {

/**
* Returns a {@code Completable} instance that runs the given {@link Runnable} for each {@link CompletableObserver} and
* emits either its exception or simply completes.
* emits either its unchecked exception or simply completes.
* <p>
* <img width="640" height="297" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.fromRunnable.png" alt="">
* <p>
* If the code to be wrapped needs to throw a checked or more broader {@link Throwable} exception, that
* exception has to be converted to an unchecked exception by the wrapped code itself. Alternatively,
* use the {@link #fromAction(Action)} method which allows the wrapped code to throw any {@code Throwable}
* exception and will signal it to observers as-is.
* <dl>
* <dt><b>Scheduler:</b></dt>
* <dd>{@code fromRunnable} does not operate by default on a particular {@link Scheduler}.</dd>
* <dt><b>Error handling:</b></dt>
* <dd> If the {@code Runnable} throws an exception, the respective {@link Throwable} is
* <dd> If the {@code Runnable} throws an exception, the respective {@code Throwable} is
* delivered to the downstream via {@link CompletableObserver#onError(Throwable)},
* except when the downstream has disposed this {@code Completable} source.
* In this latter case, the {@code Throwable} is delivered to the global error handler via
Expand All @@ -653,6 +658,7 @@ public static <T> Completable fromMaybe(@NonNull MaybeSource<T> maybe) {
* @param run the {@code Runnable} to run for each {@code CompletableObserver}
* @return the new {@code Completable} instance
* @throws NullPointerException if {@code run} is {@code null}
* @see #fromAction(Action)
*/
@CheckReturnValue
@NonNull
Expand Down
18 changes: 12 additions & 6 deletions src/main/java/io/reactivex/rxjava3/core/Flowable.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2113,7 +2113,7 @@ public static <T> Flowable<T> error(@NonNull Throwable throwable) {
}

/**
* Returns a {@code Flowable} instance that runs the given {@link Action} for each subscriber and
* Returns a {@code Flowable} instance that runs the given {@link Action} for each {@link Subscriber} and
* emits either its exception or simply completes.
* <p>
* <img width="640" height="285" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.fromAction.png" alt="">
Expand All @@ -2131,7 +2131,7 @@ public static <T> Flowable<T> error(@NonNull Throwable throwable) {
* </dd>
* </dl>
* @param <T> the target type
* @param action the {@code Action} to run for each subscriber
* @param action the {@code Action} to run for each {@code Subscriber}
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code action} is {@code null}
* @since 3.0.0
Expand Down Expand Up @@ -2497,28 +2497,34 @@ public static <T> Flowable<T> fromPublisher(@NonNull Publisher<@NonNull ? extend
}

/**
* Returns a {@code Flowable} instance that runs the given {@link Runnable} for each subscriber and
* emits either its exception or simply completes.
* Returns a {@code Flowable} instance that runs the given {@link Runnable} for each {@link Subscriber} and
* emits either its unchecked exception or simply completes.
* <p>
* <img width="640" height="286" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.fromRunnable.png" alt="">
* <p>
* If the code to be wrapped needs to throw a checked or more broader {@link Throwable} exception, that
* exception has to be converted to an unchecked exception by the wrapped code itself. Alternatively,
* use the {@link #fromAction(Action)} method which allows the wrapped code to throw any {@code Throwable}
* exception and will signal it to observers as-is.
* <dl>
* <dt><b>Backpressure:</b></dt>
* <dd>This source doesn't produce any elements and effectively ignores downstream backpressure.</dd>
* <dt><b>Scheduler:</b></dt>
* <dd>{@code fromRunnable} does not operate by default on a particular {@link Scheduler}.</dd>
* <dt><b>Error handling:</b></dt>
* <dd> If the {@code Runnable} throws an exception, the respective {@link Throwable} is
* <dd> If the {@code Runnable} throws an exception, the respective {@code Throwable} is
* delivered to the downstream via {@link Subscriber#onError(Throwable)},
* except when the downstream has canceled the resulting {@code Flowable} source.
* In this latter case, the {@code Throwable} is delivered to the global error handler via
* {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
* </dd>
* </dl>
* @param <T> the target type
* @param run the {@code Runnable} to run for each subscriber
* @param run the {@code Runnable} to run for each {@code Subscriber}
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code run} is {@code null}
* @since 3.0.0
* @see #fromAction(Action)
*/
@CheckReturnValue
@NonNull
Expand Down
23 changes: 18 additions & 5 deletions src/main/java/io/reactivex/rxjava3/core/Maybe.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -967,7 +967,7 @@ public static <T> Maybe<T> error(@NonNull Supplier<? extends Throwable> supplier
}

/**
* Returns a {@code Maybe} instance that runs the given {@link Action} for each observer and
* Returns a {@code Maybe} instance that runs the given {@link Action} for each {@link MaybeObserver} and
* emits either its exception or simply completes.
* <p>
* <img width="640" height="287" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Maybe.fromAction.png" alt="">
Expand All @@ -983,7 +983,7 @@ public static <T> Maybe<T> error(@NonNull Supplier<? extends Throwable> supplier
* </dd>
* </dl>
* @param <T> the target type
* @param action the {@code Action} to run for each observer
* @param action the {@code Action} to run for each {@code MaybeObserver}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code action} is {@code null}
*/
Expand Down Expand Up @@ -1208,18 +1208,31 @@ public static <T> Maybe<T> fromPublisher(@NonNull Publisher<T> source) {
}

/**
* Returns a {@code Maybe} instance that runs the given {@link Runnable} for each observer and
* emits either its exception or simply completes.
* Returns a {@code Maybe} instance that runs the given {@link Runnable} for each {@link MaybeObserver} and
* emits either its unchecked exception or simply completes.
* <p>
* <img width="640" height="287" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Maybe.fromRunnable.png" alt="">
* <p>
* If the code to be wrapped needs to throw a checked or more broader {@link Throwable} exception, that
* exception has to be converted to an unchecked exception by the wrapped code itself. Alternatively,
* use the {@link #fromAction(Action)} method which allows the wrapped code to throw any {@code Throwable}
* exception and will signal it to observers as-is.
* <dl>
* <dt><b>Scheduler:</b></dt>
* <dd>{@code fromRunnable} does not operate by default on a particular {@link Scheduler}.</dd>
* <dt><b>Error handling:</b></dt>
* <dd> If the {@code Runnable} throws an exception, the respective {@code Throwable} is
* delivered to the downstream via {@link MaybeObserver#onError(Throwable)},
* except when the downstream has disposed this {@code Maybe} source.
* In this latter case, the {@code Throwable} is delivered to the global error handler via
* {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
* </dd>
* </dl>
* @param <T> the target type
* @param run the {@code Runnable} to run for each observer
* @param run the {@code Runnable} to run for each {@code MaybeObserver}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code run} is {@code null}
* @see #fromAction(Action)
*/
@CheckReturnValue
@NonNull
Expand Down
20 changes: 13 additions & 7 deletions src/main/java/io/reactivex/rxjava3/core/Observable.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1855,10 +1855,10 @@ public static <T> Observable<T> error(@NonNull Throwable throwable) {
}

/**
* Returns an {@code Observable} instance that runs the given {@link Action} for each subscriber and
* Returns an {@code Observable} instance that runs the given {@link Action} for each {@link Observer} and
* emits either its exception or simply completes.
* <p>
* <img width="640" height="287" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Maybe.fromAction.png" alt="">
* <img width="640" height="287" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.fromAction.png" alt="">
* <dl>
* <dt><b>Scheduler:</b></dt>
* <dd>{@code fromAction} does not operate by default on a particular {@link Scheduler}.</dd>
Expand All @@ -1871,7 +1871,7 @@ public static <T> Observable<T> error(@NonNull Throwable throwable) {
* </dd>
* </dl>
* @param <T> the target type
* @param action the {@code Action} to run for each subscriber
* @param action the {@code Action} to run for each {@code Observer}
* @return the new {@code Observable} instance
* @throws NullPointerException if {@code action} is {@code null}
* @since 3.0.0
Expand Down Expand Up @@ -2145,26 +2145,32 @@ public static <T> Observable<T> fromPublisher(@NonNull Publisher<@NonNull ? exte
}

/**
* Returns an {@code Observable} instance that runs the given {@link Runnable} for each observer and
* emits either its exception or simply completes.
* Returns an {@code Observable} instance that runs the given {@link Runnable} for each {@link Observer} and
* emits either its unchecked exception or simply completes.
* <p>
* <img width="640" height="286" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.fromRunnable.png" alt="">
* <p>
* If the code to be wrapped needs to throw a checked or more broader {@link Throwable} exception, that
* exception has to be converted to an unchecked exception by the wrapped code itself. Alternatively,
* use the {@link #fromAction(Action)} method which allows the wrapped code to throw any {@code Throwable}
* exception and will signal it to observers as-is.
* <dl>
* <dt><b>Scheduler:</b></dt>
* <dd>{@code fromRunnable} does not operate by default on a particular {@link Scheduler}.</dd>
* <dt><b>Error handling:</b></dt>
* <dd> If the {@code Runnable} throws an exception, the respective {@link Throwable} is
* <dd> If the {@code Runnable} throws an exception, the respective {@code Throwable} is
* delivered to the downstream via {@link Observer#onError(Throwable)},
* except when the downstream has canceled the resulting {@code Observable} source.
* In this latter case, the {@code Throwable} is delivered to the global error handler via
* {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
* </dd>
* </dl>
* @param <T> the target type
* @param run the {@code Runnable} to run for each observer
* @param run the {@code Runnable} to run for each {@code Observer}
* @return the new {@code Observable} instance
* @throws NullPointerException if {@code run} is {@code null}
* @since 3.0.0
* @see #fromAction(Action)
*/
@CheckReturnValue
@NonNull
Expand Down

0 comments on commit 0f21ba8

Please sign in to comment.