3.x: fromRunnable/fromAction javadoc improvements (#7071)

Author: akarnokd

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

@@ -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>
@@ -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}
      */
@@ -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
@@ -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

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

@@ -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="">
@@ -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
@@ -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

src/main/java/io/reactivex/rxjava3/core/Maybe.java

@@ -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="">
@@ -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}
      */
@@ -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

src/main/java/io/reactivex/rxjava3/core/Observable.java

@@ -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>
@@ -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
@@ -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