2.x: Improve class Javadoc of Single, Maybe and Completable (#6080)

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

@@ -33,9 +33,74 @@
 import io.reactivex.schedulers.Schedulers;
 
 /**
- * Represents a deferred computation without any value but only indication for completion or exception.
+ * The {@code Completable} class represents a deferred computation without any value but
+ * only indication for completion or exception.
+ * <p>
+ * {@code Completable} behaves similarly to {@link Observable} except that it can only emit either
+ * a completion or error signal (there is no {@code onNext} or {@code onSuccess} as with the other
+ * reactive types).
+ * <p>
+ * The {@code Completable} class implements the {@link CompletableSource} base interface and the default consumer
+ * type it interacts with is the {@link CompletableObserver} via the {@link #subscribe(CompletableObserver)} method.
+ * The {@code Completable} operates with the following sequential protocol:
+ * <pre><code>
+ *     onSubscribe (onError | onComplete)?
+ * </code></pre>
+ * <p>
+ * Note that as with the {@code Observable} protocol, {@code onError} and {@code onComplete} are mutually exclusive events.
+ * <p>
+ * Like {@link Observable}, a running {@code Completable} can be stopped through the {@link Disposable} instance
+ * provided to consumers through {@link SingleObserver#onSubscribe}.
+ * <p>
+ * Like an {@code Observable}, a {@code Completable} is lazy, can be either "hot" or "cold", synchronous or
+ * asynchronous. {@code Completable} instances returned by the methods of this class are <em>cold</em>
+ * and there is a standard <em>hot</em> implementation in the form of a subject:
+ * {@link io.reactivex.subjects.CompletableSubject CompletableSubject}.
+ * <p>
+ * The documentation for this class makes use of marble diagrams. The following legend explains these diagrams:
+ * <p>
+ * <img width="640" height="577" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.png" alt="">
+ * <p>
+ * See {@link Flowable} or {@link Observable} for the
+ * implementation of the Reactive Pattern for a stream or vector of values.
+ * <p>
+ * Example:
+ * <pre><code>
+ * Disposable d = Completable.complete()
+ *    .delay(10, TimeUnit.SECONDS, Schedulers.io())
+ *    .subscribeWith(new DisposableCompletableObserver() {
+ *        &#64;Override
+ *        public void onStart() {
+ *            System.out.println("Started");
+ *        }
  *
- * The class follows a similar event pattern as Reactive-Streams: onSubscribe (onError|onComplete)?
+ *        &#64;Override
+ *        public void onError(Throwable error) {
+ *            error.printStackTrace();
+ *        }
+ *
+ *        &#64;Override
+ *        public void onComplete() {
+ *            System.out.println("Done!");
+ *        }
+ *    });
+ * 
+ * Thread.sleep(5000);
+ * 
+ * d.dispose();
+ * </code></pre>
+ * <p>
+ * Note that by design, subscriptions via {@link #subscribe(CompletableObserver)} can't be cancelled/disposed
+ * from the outside (hence the
+ * {@code void} return of the {@link #subscribe(CompletableObserver)} method) and it is the
+ * responsibility of the implementor of the {@code CompletableObserver} to allow this to happen.
+ * RxJava supports such usage with the standard
+ * {@link io.reactivex.observers.DisposableCompletableObserver DisposableCompletableObserver} instance.
+ * For convenience, the {@link #subscribeWith(CompletableObserver)} method is provided as well to
+ * allow working with a {@code CompletableObserver} (or subclass) instance to be applied with in
+ * a fluent manner (such as in the example above).
+ *
+ * @see io.reactivex.observers.DisposableCompletableObserver
  */
 public abstract class Completable implements CompletableSource {
     /**

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

@@ -34,18 +34,78 @@
 import io.reactivex.schedulers.Schedulers;
 
 /**
- * Represents a deferred computation and emission of a maybe value or exception.
+ * The {@code Maybe} class represents a deferred computation and emission of a single value, no value at all or an exception.
  * <p>
- * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/maybe.png" alt="">
+ * The {@code Maybe} class implements the {@link MaybeSource} base interface and the default consumer
+ * type it interacts with is the {@link MaybeObserver} via the {@link #subscribe(MaybeObserver)} method.
  * <p>
- * The main consumer type of Maybe is {@link MaybeObserver} whose methods are called
- * in a sequential fashion following this protocol:<br>
- * {@code onSubscribe (onSuccess | onError | onComplete)?}.
+ * The {@code Maybe} operates with the following sequential protocol:
+ * <pre><code>
+ *     onSubscribe (onSuccess | onError | onComplete)?
+ * </code></pre>
  * <p>
  * Note that {@code onSuccess}, {@code onError} and {@code onComplete} are mutually exclusive events; unlike {@code Observable},
  * {@code onSuccess} is never followed by {@code onError} or {@code onComplete}.
+ * <p>
+ * Like {@link Observable}, a running {@code Maybe} can be stopped through the {@link Disposable} instance
+ * provided to consumers through {@link MaybeObserver#onSubscribe}.
+ * <p>
+ * Like an {@code Observable}, a {@code Maybe} is lazy, can be either "hot" or "cold", synchronous or
+ * asynchronous. {@code Maybe} instances returned by the methods of this class are <em>cold</em>
+ * and there is a standard <em>hot</em> implementation in the form of a subject:
+ * {@link io.reactivex.subjects.MaybeSubject MaybeSubject}.
+ * <p>
+ * The documentation for this class makes use of marble diagrams. The following legend explains these diagrams:
+ * <p>
+ * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/maybe.png" alt="">
+ * <p>
+ * See {@link Flowable} or {@link Observable} for the
+ * implementation of the Reactive Pattern for a stream or vector of values.
+ * <p>
+ * Example:
+ * <pre><code>
+ * Disposable d = Maybe.just("Hello World")
+ *    .delay(10, TimeUnit.SECONDS, Schedulers.io())
+ *    .subscribeWith(new DisposableMaybeObserver&lt;String&gt;() {
+ *        &#64;Override
+ *        public void onStart() {
+ *            System.out.println("Started");
+ *        }
+ *
+ *        &#64;Override
+ *        public void onSuccess(String value) {
+ *            System.out.println("Success: " + value);
+ *        }
+ *
+ *        &#64;Override
+ *        public void onError(Throwable error) {
+ *            error.printStackTrace();
+ *        }
+ *
+ *        &#64;Override
+ *        public void onComplete() {
+ *            System.out.println("Done!");
+ *        }
+ *    });
+ * 
+ * Thread.sleep(5000);
+ * 
+ * d.dispose();
+ * </code></pre>
+ * <p>
+ * Note that by design, subscriptions via {@link #subscribe(MaybeObserver)} can't be cancelled/disposed
+ * from the outside (hence the
+ * {@code void} return of the {@link #subscribe(MaybeObserver)} method) and it is the
+ * responsibility of the implementor of the {@code MaybeObserver} to allow this to happen.
+ * RxJava supports such usage with the standard
+ * {@link io.reactivex.observers.DisposableMaybeObserver DisposableMaybeObserver} instance.
+ * For convenience, the {@link #subscribeWith(MaybeObserver)} method is provided as well to
+ * allow working with a {@code MaybeObserver} (or subclass) instance to be applied with in
+ * a fluent manner (such as in the example above).
+ *
  * @param <T> the value type
  * @since 2.0
+ * @see io.reactivex.observers.DisposableMaybeObserver
  */
 public abstract class Maybe<T> implements MaybeSource<T> {
 

src/main/java/io/reactivex/Single.java

@@ -37,26 +37,79 @@
 import io.reactivex.schedulers.Schedulers;
 
 /**
- * The Single class implements the Reactive Pattern for a single value response.
- * See {@link Flowable} or {@link Observable} for the
- * implementation of the Reactive Pattern for a stream or vector of values.
+ * The {@code Single} class implements the Reactive Pattern for a single value response.
+ * <p>
+ * {@code Single} behaves similarly to {@link Observable} except that it can only emit either a single successful
+ * value or an error (there is no "onComplete" notification as there is for an {@link Observable}).
+ * <p>
+ * The {@code Single} class implements the {@link SingleSource} base interface and the default consumer
+ * type it interacts with is the {@link SingleObserver} via the {@link #subscribe(SingleObserver)} method.
+ * <p>
+ * The {@code Single} operates with the following sequential protocol:
+ * <pre>
+ *     <code>onSubscribe (onSuccess | onError)?</code>
+ * </pre>
+ * <p>
+ * Note that {@code onSuccess} and {@code onError} are mutually exclusive events; unlike {@code Observable},
+ * {@code onSuccess} is never followed by {@code onError}.
  * <p>
- * {@code Single} behaves the same as {@link Observable} except that it can only emit either a single successful
- * value, or an error (there is no "onComplete" notification as there is for {@link Observable})
+ * Like {@code Observable}, a running {@code Single} can be stopped through the {@link Disposable} instance
+ * provided to consumers through {@link SingleObserver#onSubscribe}.
  * <p>
- * Like an {@link Observable}, a {@code Single} is lazy, can be either "hot" or "cold", synchronous or
- * asynchronous.
+ * Like an {@code Observable}, a {@code Single} is lazy, can be either "hot" or "cold", synchronous or
+ * asynchronous. {@code Single} instances returned by the methods of this class are <em>cold</em>
+ * and there is a standard <em>hot</em> implementation in the form of a subject:
+ * {@link io.reactivex.subjects.SingleSubject SingleSubject}.
  * <p>
  * The documentation for this class makes use of marble diagrams. The following legend explains these diagrams:
  * <p>
  * <img width="640" height="301" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.legend.png" alt="">
  * <p>
+ * See {@link Flowable} or {@link Observable} for the
+ * implementation of the Reactive Pattern for a stream or vector of values.
+ * <p>
  * For more information see the <a href="http://reactivex.io/documentation/single.html">ReactiveX
  * documentation</a>.
+ * <p>
+ * Example:
+ * <pre><code>
+ * Disposable d = Single.just("Hello World")
+ *    .delay(10, TimeUnit.SECONDS, Schedulers.io())
+ *    .subscribeWith(new DisposableSingleObserver&lt;String&gt;() {
+ *        &#64;Override
+ *        public void onStart() {
+ *            System.out.println("Started");
+ *        }
+ *
+ *        &#64;Override
+ *        public void onSuccess(String value) {
+ *            System.out.println("Success: " + value);
+ *        }
  *
+ *        &#64;Override
+ *        public void onError(Throwable error) {
+ *            error.printStackTrace();
+ *        }
+ *    });
+ * 
+ * Thread.sleep(5000);
+ * 
+ * d.dispose();
+ * </code></pre>
+ * <p>
+ * Note that by design, subscriptions via {@link #subscribe(SingleObserver)} can't be cancelled/disposed
+ * from the outside (hence the
+ * {@code void} return of the {@link #subscribe(SingleObserver)} method) and it is the
+ * responsibility of the implementor of the {@code SingleObserver} to allow this to happen.
+ * RxJava supports such usage with the standard
+ * {@link io.reactivex.observers.DisposableSingleObserver DisposableSingleObserver} instance.
+ * For convenience, the {@link #subscribeWith(SingleObserver)} method is provided as well to
+ * allow working with a {@code SingleObserver} (or subclass) instance to be applied with in
+ * a fluent manner (such as in the example above).
  * @param <T>
  *            the type of the item emitted by the Single
  * @since 2.0
+ * @see io.reactivex.observers.DisposableSingleObserver
  */
 public abstract class Single<T> implements SingleSource<T> {