2.x: Improve JavaDoc of XObserver types. (#5841)

* 2.x: Improve JavaDoc of XObserver types.

* Use "disposing", add missing space

* Add more explanation about throwing exceptions.

Author: akarnokd

src/main/java/io/reactivex/CompletableObserver.java

@@ -17,7 +17,36 @@
 import io.reactivex.disposables.Disposable;
 
 /**
- * Represents the subscription API callbacks when subscribing to a Completable instance.
+ * Provides a mechanism for receiving push-based notification of a valueless completion or an error.
+ * <p>
+ * When a {@code CompletableObserver} is subscribed to a {@link CompletableSource} through the {@link CompletableSource#subscribe(CompletableObserver)} method,
+ * the {@code CompletableSource} calls {@link #onSubscribe(Disposable)}  with a {@link Disposable} that allows
+ * disposing the sequence at any time. A well-behaved
+ * {@code CompletableSource} will call a {@code CompletableObserver}'s {@link #onError(Throwable)}
+ * or {@link #onComplete()} method exactly once as they are considered mutually exclusive <strong>terminal signals</strong>.
+ * <p>
+ * Calling the {@code CompletableObserver}'s method must happen in a serialized fashion, that is, they must not
+ * be invoked concurrently by multiple threads in an overlapping fashion and the invocation pattern must
+ * adhere to the following protocol:
+ * <p>
+ * <pre><code>    onSubscribe (onError | onComplete)?</code></pre>
+ * <p>
+ * Subscribing a {@code CompletableObserver} to multiple {@code CompletableSource}s is not recommended. If such reuse
+ * happens, it is the duty of the {@code CompletableObserver} implementation to be ready to receive multiple calls to
+ * its methods and ensure proper concurrent behavior of its business logic.
+ * <p>
+ * Calling {@link #onSubscribe(Disposable)} or {@link #onError(Throwable)} with a
+ * {@code null} argument is forbidden.
+ * <p>
+ * The implementations of the {@code onXXX} methods should avoid throwing runtime exceptions other than the following cases:
+ * <ul>
+ * <li>If the argument is {@code null}, the methods can throw a {@code NullPointerException}.
+ * Note though that RxJava prevents {@code null}s to enter into the flow and thus there is generally no
+ * need to check for nulls in flows assembled from standard sources and intermediate operators.
+ * </li>
+ * <li>If there is a fatal error (such as {@code VirtualMachineError}).</li>
+ * </ul>
+ * @since 2.0
  */
 public interface CompletableObserver {
     /**

src/main/java/io/reactivex/MaybeObserver.java

@@ -17,14 +17,38 @@
 import io.reactivex.disposables.Disposable;
 
 /**
- * Provides a mechanism for receiving push-based notifications.
+ * Provides a mechanism for receiving push-based notification of a single value, an error or completion without any value.
  * <p>
- * After a MaybeObserver calls a {@link Maybe}'s {@link Maybe#subscribe subscribe} method,
- * first the Maybe calls {@link #onSubscribe(Disposable)} with a {@link Disposable} that allows
- * cancelling the sequence at any time, then the
- * {@code Maybe} calls only one of the MaybeObserver's {@link #onSuccess}, {@link #onError} or
- * {@link #onComplete} methods to provide notifications.
- *
+ * When a {@code MaybeObserver} is subscribed to a {@link MaybeSource} through the {@link MaybeSource#subscribe(MaybeObserver)} method,
+ * the {@code MaybeSource} calls {@link #onSubscribe(Disposable)}  with a {@link Disposable} that allows
+ * disposing the sequence at any time. A well-behaved
+ * {@code MaybeSource} will call a {@code MaybeObserver}'s {@link #onSuccess(Object)}, {@link #onError(Throwable)}
+ * or {@link #onComplete()} method exactly once as they are considered mutually exclusive <strong>terminal signals</strong>.
+ * <p>
+ * Calling the {@code MaybeObserver}'s method must happen in a serialized fashion, that is, they must not
+ * be invoked concurrently by multiple threads in an overlapping fashion and the invocation pattern must
+ * adhere to the following protocol:
+ * <p>
+ * <pre><code>    onSubscribe (onSuccess | onError | onComplete)?</code></pre>
+ * <p>
+ * Note that unlike with the {@code Observable} protocol, {@link #onComplete()} is not called after the success item has been
+ * signalled via {@link #onSuccess(Object)}.
+ * <p>
+ * Subscribing a {@code MaybeObserver} to multiple {@code MaybeSource}s is not recommended. If such reuse
+ * happens, it is the duty of the {@code MaybeObserver} implementation to be ready to receive multiple calls to
+ * its methods and ensure proper concurrent behavior of its business logic.
+ * <p>
+ * Calling {@link #onSubscribe(Disposable)}, {@link #onSuccess(Object)} or {@link #onError(Throwable)} with a
+ * {@code null} argument is forbidden.
+ * <p>
+ * The implementations of the {@code onXXX} methods should avoid throwing runtime exceptions other than the following cases:
+ * <ul>
+ * <li>If the argument is {@code null}, the methods can throw a {@code NullPointerException}.
+ * Note though that RxJava prevents {@code null}s to enter into the flow and thus there is generally no
+ * need to check for nulls in flows assembled from standard sources and intermediate operators.
+ * </li>
+ * <li>If there is a fatal error (such as {@code VirtualMachineError}).</li>
+ * </ul>
  * @see <a href="http://reactivex.io/documentation/observable.html">ReactiveX documentation: Observable</a>
  * @param <T>
  *          the type of item the MaybeObserver expects to observe

src/main/java/io/reactivex/Observer.java

@@ -19,14 +19,57 @@
 /**
  * Provides a mechanism for receiving push-based notifications.
  * <p>
- * After an Observer calls an {@link Observable}'s {@link Observable#subscribe subscribe} method,
- * first the Observable calls {@link #onSubscribe(Disposable)} with a {@link Disposable} that allows
- * cancelling the sequence at any time, then the
- * {@code Observable} may call the Observer's {@link #onNext} method any number of times
+ * When an {@code Observer} is subscribed to an {@link ObservableSource} through the {@link ObservableSource#subscribe(Observer)} method,
+ * the {@code ObservableSource} calls {@link #onSubscribe(Disposable)}  with a {@link Disposable} that allows
+ * disposing the sequence at any time, then the
+ * {@code ObservableSource} may call the Observer's {@link #onNext} method any number of times
  * to provide notifications. A well-behaved
- * {@code Observable} will call an Observer's {@link #onComplete} method exactly once or the Observer's
+ * {@code ObservableSource} will call an {@code Observer}'s {@link #onComplete} method exactly once or the {@code Observer}'s
  * {@link #onError} method exactly once.
- *
+ * <p>
+ * Calling the {@code Observer}'s method must happen in a serialized fashion, that is, they must not
+ * be invoked concurrently by multiple threads in an overlapping fashion and the invocation pattern must
+ * adhere to the following protocol:
+ * <p>
+ * <pre><code>    onSubscribe onNext* (onError | onComplete)?</code></pre>
+ * <p>
+ * Subscribing an {@code Observer} to multiple {@code ObservableSource}s is not recommended. If such reuse
+ * happens, it is the duty of the {@code Observer} implementation to be ready to receive multiple calls to
+ * its methods and ensure proper concurrent behavior of its business logic.
+ * <p>
+ * Calling {@link #onSubscribe(Disposable)}, {@link #onNext(Object)} or {@link #onError(Throwable)} with a
+ * {@code null} argument is forbidden.
+ * <p>
+ * The implementations of the {@code onXXX} methods should avoid throwing runtime exceptions other than the following cases
+ * (see <a href="https://github.com/reactive-streams/reactive-streams-jvm#2.13">Rule 2.13</a> of the Reactive Streams specification):
+ * <ul>
+ * <li>If the argument is {@code null}, the methods can throw a {@code NullPointerException}.
+ * Note though that RxJava prevents {@code null}s to enter into the flow and thus there is generally no
+ * need to check for nulls in flows assembled from standard sources and intermediate operators.
+ * </li>
+ * <li>If there is a fatal error (such as {@code VirtualMachineError}).</li>
+ * </ul>
+ * <p>
+ * Violating Rule 2.13 results in undefined flow behavior. Generally, the following can happen:
+ * <ul>
+ * <li>An upstream operator turns it into an {@link #onError} call.</li>
+ * <li>If the flow is synchronous, the {@link ObservableSource#subscribe(Observer)} throws instead of returning normally.</li>
+ * <li>If the flow is asynchronous, the exception propagates up to the component ({@link Scheduler} or {@link java.util.concurrent.Executor})
+ * providing the asynchronous boundary the code is running and either routes the exception to the global
+ * {@link io.reactivex.plugins.RxJavaPlugins#onError(Throwable)} handler or the current thread's
+ * {@link java.lang.Thread.UncaughtExceptionHandler#uncaughtException(Thread, Throwable)} handler.</li>
+ * </ul>
+ * From the {@code Observable}'s perspective, an {@code Observer} is the end consumer thus it is the {@code Observer}'s
+ * responsibility to handle the error case and signal it "further down". This means unreliable code in the {@code onXXX}
+ * methods should be wrapped into `try-catch`es, specifically in {@link #onError(Throwable)} or {@link #onComplete()}, and handled there
+ * (for example, by logging it or presenting the user with an error dialog). However, if the error would be thrown from
+ * {@link #onNext(Object)}, <a href="https://github.com/reactive-streams/reactive-streams-jvm#2.13">Rule 2.13</a> mandates
+ * the implementation calls {@link Disposable#dispose()} and signals the exception in a way that is adequate to the target context,
+ * for example, by calling {@link #onError(Throwable)} on the same {@code Observer} instance.
+ * <p>
+ * If, for some reason, the {@code Observer} won't follow Rule 2.13, the {@link Observable#safeSubscribe(Observer)} can wrap it
+ * with the necessary safeguards and route exceptions thrown from {@code onNext} into {@code onError} and route exceptions thrown
+ * from {@code onError} and {@code onComplete} into the global error handler via {@link io.reactivex.plugins.RxJavaPlugins#onError(Throwable)}.
  * @see <a href="http://reactivex.io/documentation/observable.html">ReactiveX documentation: Observable</a>
  * @param <T>
  *          the type of item the Observer expects to observe

src/main/java/io/reactivex/SingleObserver.java

@@ -17,14 +17,35 @@
 import io.reactivex.disposables.Disposable;
 
 /**
- * Provides a mechanism for receiving push-based notifications.
+ * Provides a mechanism for receiving push-based notification of a single value or an error.
  * <p>
- * After a SingleObserver calls a {@link Single}'s {@link Single#subscribe subscribe} method,
- * first the Single calls {@link #onSubscribe(Disposable)} with a {@link Disposable} that allows
- * cancelling the sequence at any time, then the
- * {@code Single} calls only one of the SingleObserver {@link #onSuccess} and {@link #onError} methods to provide
- * notifications.
- *
+ * When a {@code SingleObserver} is subscribed to a {@link SingleSource} through the {@link SingleSource#subscribe(SingleObserver)} method,
+ * the {@code SingleSource} calls {@link #onSubscribe(Disposable)}  with a {@link Disposable} that allows
+ * disposing the sequence at any time. A well-behaved
+ * {@code SingleSource} will call a {@code SingleObserver}'s {@link #onSuccess(Object)} method exactly once or the {@code SingleObserver}'s
+ * {@link #onError} method exactly once as they are considered mutually exclusive <strong>terminal signals</strong>.
+ * <p>
+ * Calling the {@code SingleObserver}'s method must happen in a serialized fashion, that is, they must not
+ * be invoked concurrently by multiple threads in an overlapping fashion and the invocation pattern must
+ * adhere to the following protocol:
+ * <p>
+ * <pre><code>    onSubscribe (onSuccess | onError)?</code></pre>
+ * <p>
+ * Subscribing a {@code SingleObserver} to multiple {@code SingleSource}s is not recommended. If such reuse
+ * happens, it is the duty of the {@code SingleObserver} implementation to be ready to receive multiple calls to
+ * its methods and ensure proper concurrent behavior of its business logic.
+ * <p>
+ * Calling {@link #onSubscribe(Disposable)}, {@link #onSuccess(Object)} or {@link #onError(Throwable)} with a
+ * {@code null} argument is forbidden.
+ * <p>
+ * The implementations of the {@code onXXX} methods should avoid throwing runtime exceptions other than the following cases:
+ * <ul>
+ * <li>If the argument is {@code null}, the methods can throw a {@code NullPointerException}.
+ * Note though that RxJava prevents {@code null}s to enter into the flow and thus there is generally no
+ * need to check for nulls in flows assembled from standard sources and intermediate operators.
+ * </li>
+ * <li>If there is a fatal error (such as {@code VirtualMachineError}).</li>
+ * </ul>
  * @see <a href="http://reactivex.io/documentation/observable.html">ReactiveX documentation: Observable</a>
  * @param <T>
  *          the type of item the SingleObserver expects to observe