2.x: Improved XSubject JavaDocs (#5802)

* 2.x: Improved XSubject JavaDocs

* Remove "still"

Author: akarnokd

src/main/java/io/reactivex/processors/BehaviorProcessor.java

@@ -86,7 +86,7 @@
  * given {@code Subscription} being cancelled immediately.
  * <p>
  * Calling {@link #onNext(Object)}, {@link #onError(Throwable)} and {@link #onComplete()}
- * is still required to be serialized (called from the same thread or called non-overlappingly from different threads
+ * is required to be serialized (called from the same thread or called non-overlappingly from different threads
  * through external means of serialization). The {@link #toSerialized()} method available to all {@code FlowableProcessor}s
  * provides such serialization and also protects against reentrance (i.e., when a downstream {@code Subscriber}
  * consuming this processor also wants to call {@link #onNext(Object)} on this processor recursively).

src/main/java/io/reactivex/subjects/AsyncSubject.java

@@ -24,14 +24,86 @@
 import io.reactivex.plugins.RxJavaPlugins;
 
 /**
- * An Subject that emits the very last value followed by a completion event or the received error to Observers.
- *
- * <p>The implementation of onXXX methods are technically thread-safe but non-serialized calls
+ * A Subject that emits the very last value followed by a completion event or the received error to Observers.
+ * <p>
+ * This subject does not have a public constructor by design; a new empty instance of this
+ * {@code AsyncSubject} can be created via the {@link #create()} method.
+ * <p>
+ * Since a {@code Subject} is conceptionally derived from the {@code Processor} type in the Reactive Streams specification,
+ * {@code null}s are not allowed (<a href="https://github.com/reactive-streams/reactive-streams-jvm#2.13">Rule 2.13</a>)
+ * as parameters to {@link #onNext(Object)} and {@link #onError(Throwable)}. Such calls will result in a
+ * {@link NullPointerException} being thrown and the subject's state is not changed.
+ * <p>
+ * Since an {@code AsyncSubject} is an {@link io.reactivex.Observable}, it does not support backpressure.
+ * <p>
+ * When this {@code AsyncSubject} is terminated via {@link #onError(Throwable)}, the
+ * last observed item (if any) is cleared and late {@link io.reactivex.Observer}s only receive
+ * the {@code onError} event.
+ * <p>
+ * The {@code AsyncSubject} caches the latest item internally and it emits this item only when {@code onComplete} is called.
+ * Therefore, it is not recommended to use this {@code Subject} with infinite or never-completing sources.
+ * <p>
+ * Even though {@code AsyncSubject} implements the {@code Observer} interface, calling
+ * {@code onSubscribe} is not required (<a href="https://github.com/reactive-streams/reactive-streams-jvm#2.12">Rule 2.12</a>)
+ * if the subject is used as a standalone source. However, calling {@code onSubscribe}
+ * after the {@code AsyncSubject} reached its terminal state will result in the
+ * given {@code Disposable} being disposed immediately.
+ * <p>
+ * Calling {@link #onNext(Object)}, {@link #onError(Throwable)} and {@link #onComplete()}
+ * is required to be serialized (called from the same thread or called non-overlappingly from different threads
+ * through external means of serialization). The {@link #toSerialized()} method available to all {@code Subject}s
+ * provides such serialization and also protects against reentrance (i.e., when a downstream {@code Observer}
+ * consuming this subject also wants to call {@link #onNext(Object)} on this subject recursively).
+ * The implementation of onXXX methods are technically thread-safe but non-serialized calls
  * to them may lead to undefined state in the currently subscribed Observers.
+ * <p>
+ * This {@code AsyncSubject} supports the standard state-peeking methods {@link #hasComplete()}, {@link #hasThrowable()},
+ * {@link #getThrowable()} and {@link #hasObservers()} as well as means to read the very last observed value -
+ * after this {@code AsyncSubject} has been completed - in a non-blocking and thread-safe
+ * manner via {@link #hasValue()}, {@link #getValue()}, {@link #getValues()} or {@link #getValues(Object[])}.
+ * <dl>
+ *  <dt><b>Scheduler:</b></dt>
+ *  <dd>{@code AsyncSubject} does not operate by default on a particular {@link io.reactivex.Scheduler} and
+ *  the {@code Observer}s get notified on the thread where the terminating {@code onError} or {@code onComplete}
+ *  methods were invoked.</dd>
+ *  <dt><b>Error handling:</b></dt>
+ *  <dd>When the {@link #onError(Throwable)} is called, the {@code AsyncSubject} enters into a terminal state
+ *  and emits the same {@code Throwable} instance to the last set of {@code Observer}s. During this emission,
+ *  if one or more {@code Observer}s dispose their respective {@code Disposable}s, the
+ *  {@code Throwable} is delivered to the global error handler via
+ *  {@link io.reactivex.plugins.RxJavaPlugins#onError(Throwable)} (multiple times if multiple {@code Observer}s
+ *  cancel at once).
+ *  If there were no {@code Observer}s subscribed to this {@code AsyncSubject} when the {@code onError()}
+ *  was called, the global error handler is not invoked.
+ *  </dd>
+ * </dl>
+ * <p>
+ * Example usage:
+ * <pre><code>
+ * AsyncSubject&lt;Object&gt; subject = AsyncSubject.create();
+ * 
+ * TestObserver&lt;Object&gt; to1 = subject.test();
+ * 
+ * to1.assertEmpty();
+ * 
+ * subject.onNext(1);
+ * 
+ * // AsyncSubject only emits when onComplete was called.
+ * to1.assertEmpty();
  *
+ * subject.onNext(2);
+ * subject.onComplete();
+ * 
+ * // onComplete triggers the emission of the last cached item and the onComplete event.
+ * to1.assertResult(2);
+ * 
+ * TestObserver&lt;Object&gt; to2 = subject.test();
+ * 
+ * // late Observers receive the last cached item too
+ * to2.assertResult(2);
+ * </code></pre>
  * @param <T> the value type
  */
-
 public final class AsyncSubject<T> extends Subject<T> {
 
     @SuppressWarnings("rawtypes")

src/main/java/io/reactivex/subjects/BehaviorSubject.java

@@ -36,10 +36,11 @@
  * a new non-empty instance can be created via {@link #createDefault(Object)} (named as such to avoid
  * overload resolution conflict with {@code Observable.create} that creates an Observable, not a {@code BehaviorSubject}).
  * <p>
- * Since the {@code Subject} is conceptionally derived from the {@code Processor} type in the Reactive Streams specification,
+ * Since a {@code Subject} is conceptionally derived from the {@code Processor} type in the Reactive Streams specification,
  * {@code null}s are not allowed (<a href="https://github.com/reactive-streams/reactive-streams-jvm#2.13">Rule 2.13</a>) as
  * default initial values in {@link #createDefault(Object)} or as parameters to {@link #onNext(Object)} and
- * {@link #onError(Throwable)}.
+ * {@link #onError(Throwable)}. Such calls will result in a
+ * {@link NullPointerException} being thrown and the subject's state is not changed.
  * <p>
  * Since a {@code BehaviorSubject} is an {@link io.reactivex.Observable}, it does not support backpressure.
  * <p>
@@ -83,11 +84,11 @@
  * Even though {@code BehaviorSubject} implements the {@code Observer} interface, calling
  * {@code onSubscribe} is not required (<a href="https://github.com/reactive-streams/reactive-streams-jvm#2.12">Rule 2.12</a>)
  * if the subject is used as a standalone source. However, calling {@code onSubscribe}
- * after the {@code BehaviorSubjecct} reached its terminal state will result in the
+ * after the {@code BehaviorSubject} reached its terminal state will result in the
  * given {@code Disposable} being disposed immediately.
  * <p>
  * Calling {@link #onNext(Object)}, {@link #onError(Throwable)} and {@link #onComplete()}
- * is still required to be serialized (called from the same thread or called non-overlappingly from different threads
+ * is required to be serialized (called from the same thread or called non-overlappingly from different threads
  * through external means of serialization). The {@link #toSerialized()} method available to all {@code Subject}s
  * provides such serialization and also protects against reentrance (i.e., when a downstream {@code Observer}
  * consuming this subject also wants to call {@link #onNext(Object)} on this subject recursively).

src/main/java/io/reactivex/subjects/CompletableSubject.java

@@ -24,12 +24,61 @@
 /**
  * Represents a hot Completable-like source and consumer of events similar to Subjects.
  * <p>
- * All methods are thread safe. Calling onComplete multiple
- * times has no effect. Calling onError multiple times relays the Throwable to
- * the RxJavaPlugins' error handler.
+ * This subject does not have a public constructor by design; a new non-terminated instance of this
+ * {@code CompletableSubject} can be created via the {@link #create()} method.
  * <p>
- * The CompletableSubject doesn't store the Disposables coming through onSubscribe but
- * disposes them once the other onXXX methods were called (terminal state reached).
+ * Since the {@code CompletableSubject} is conceptionally derived from the {@code Processor} type in the Reactive Streams specification,
+ * {@code null}s are not allowed (<a href="https://github.com/reactive-streams/reactive-streams-jvm#2.13">Rule 2.13</a>)
+ * as parameters to {@link #onError(Throwable)}.
+ * <p>
+ * Even though {@code CompletableSubject} implements the {@code CompletableObserver} interface, calling
+ * {@code onSubscribe} is not required (<a href="https://github.com/reactive-streams/reactive-streams-jvm#2.12">Rule 2.12</a>)
+ * if the subject is used as a standalone source. However, calling {@code onSubscribe}
+ * after the {@code CompletableSubject} reached its terminal state will result in the
+ * given {@code Disposable} being disposed immediately.
+ * <p>
+ * All methods are thread safe. Calling {@link #onComplete()} multiple
+ * times has no effect. Calling {@link #onError(Throwable)} multiple times relays the {@code Throwable} to
+ * the {@link io.reactivex.plugins.RxJavaPlugins#onError(Throwable)} global error handler.
+ * <p>
+ * This {@code CompletableSubject} supports the standard state-peeking methods {@link #hasComplete()},
+ * {@link #hasThrowable()}, {@link #getThrowable()} and {@link #hasObservers()}.
+ * <dl>
+ *  <dt><b>Scheduler:</b></dt>
+ *  <dd>{@code CompletableSubject} does not operate by default on a particular {@link io.reactivex.Scheduler} and
+ *  the {@code CompletableObserver}s get notified on the thread where the terminating {@code onError} or {@code onComplete}
+ *  methods were invoked.</dd>
+ *  <dt><b>Error handling:</b></dt>
+ *  <dd>When the {@link #onError(Throwable)} is called, the {@code CompletableSubject} enters into a terminal state
+ *  and emits the same {@code Throwable} instance to the last set of {@code CompletableObserver}s. During this emission,
+ *  if one or more {@code CompletableObserver}s dispose their respective {@code Disposable}s, the
+ *  {@code Throwable} is delivered to the global error handler via
+ *  {@link io.reactivex.plugins.RxJavaPlugins#onError(Throwable)} (multiple times if multiple {@code CompletableObserver}s
+ *  cancel at once).
+ *  If there were no {@code CompletableObserver}s subscribed to this {@code CompletableSubject} when the {@code onError()}
+ *  was called, the global error handler is not invoked.
+ *  </dd>
+ * </dl>
+ * <p>
+ * Example usage:
+ * <pre><code>
+ * CompletableSubject subject = CompletableSubject.create();
+ * 
+ * TestObserver&lt;Void&gt; to1 = subject.test();
+ *
+ * // a fresh CompletableSubject is empty
+ * to1.assertEmpty();
+ * 
+ * subject.onComplete();
+ *
+ * // a CompletableSubject is always void of items
+ * to1.assertResult();
+ *
+ * TestObserver&lt;Void&gt; to2 = subject.test()
+ *
+ * // late CompletableObservers receive the terminal event
+ * to2.assertResult();
+ * </code></pre>
  * <p>History: 2.0.5 - experimental
  * @since 2.1
  */

src/main/java/io/reactivex/subjects/MaybeSubject.java

@@ -24,12 +24,85 @@
 /**
  * Represents a hot Maybe-like source and consumer of events similar to Subjects.
  * <p>
- * All methods are thread safe. Calling onSuccess or onComplete multiple
- * times has no effect. Calling onError multiple times relays the Throwable to
- * the RxJavaPlugins' error handler.
+ * This subject does not have a public constructor by design; a new non-terminated instance of this
+ * {@code MaybeSubject} can be created via the {@link #create()} method.
  * <p>
- * The MaybeSubject doesn't store the Disposables coming through onSubscribe but
- * disposes them once the other onXXX methods were called (terminal state reached).
+ * Since the {@code MaybeSubject} is conceptionally derived from the {@code Processor} type in the Reactive Streams specification,
+ * {@code null}s are not allowed (<a href="https://github.com/reactive-streams/reactive-streams-jvm#2.13">Rule 2.13</a>)
+ * as parameters to  {@link #onSuccess(Object)} and {@link #onError(Throwable)}. Such calls will result in a
+ * {@link NullPointerException} being thrown and the subject's state is not changed.
+ * <p>
+ * Since a {@code MaybeSubject} is a {@link io.reactivex.Maybe}, calling {@code onSuccess}, {@code onError}
+ * or {@code onComplete} will move this {@code MaybeSubject} into its terminal state atomically.
+ * <p>
+ * All methods are thread safe. Calling {@link #onSuccess(Object)} or {@link #onComplete()} multiple
+ * times has no effect. Calling {@link #onError(Throwable)} multiple times relays the {@code Throwable} to
+ * the {@link io.reactivex.plugins.RxJavaPlugins#onError(Throwable)} global error handler.
+ * <p>
+ * Even though {@code MaybeSubject} implements the {@code MaybeObserver} interface, calling
+ * {@code onSubscribe} is not required (<a href="https://github.com/reactive-streams/reactive-streams-jvm#2.12">Rule 2.12</a>)
+ * if the subject is used as a standalone source. However, calling {@code onSubscribe}
+ * after the {@code MaybeSubject} reached its terminal state will result in the
+ * given {@code Disposable} being disposed immediately.
+ * <p>
+ * This {@code MaybeSubject} supports the standard state-peeking methods {@link #hasComplete()}, {@link #hasThrowable()},
+ * {@link #getThrowable()} and {@link #hasObservers()} as well as means to read any success item in a non-blocking
+ * and thread-safe manner via {@link #hasValue()} and {@link #getValue()}.
+ * <p>
+ * The {@code MaybeSubject} does not support clearing its cached {@code onSuccess} value.
+ * <dl>
+ *  <dt><b>Scheduler:</b></dt>
+ *  <dd>{@code MaybeSubject} does not operate by default on a particular {@link io.reactivex.Scheduler} and
+ *  the {@code MaybeObserver}s get notified on the thread where the terminating {@code onSuccess}, {@code onError} or {@code onComplete}
+ *  methods were invoked.</dd>
+ *  <dt><b>Error handling:</b></dt>
+ *  <dd>When the {@link #onError(Throwable)} is called, the {@code MaybeSubject} enters into a terminal state
+ *  and emits the same {@code Throwable} instance to the last set of {@code MaybeObserver}s. During this emission,
+ *  if one or more {@code MaybeObserver}s dispose their respective {@code Disposable}s, the
+ *  {@code Throwable} is delivered to the global error handler via
+ *  {@link io.reactivex.plugins.RxJavaPlugins#onError(Throwable)} (multiple times if multiple {@code MaybeObserver}s
+ *  cancel at once).
+ *  If there were no {@code MaybeObserver}s subscribed to this {@code MaybeSubject} when the {@code onError()}
+ *  was called, the global error handler is not invoked.
+ *  </dd>
+ * </dl>
+ * <p>
+ * Example usage:
+ * <pre><code>
+ * MaybeSubject&lt;Integer&gt; subject1 = MaybeSubject.create();
+ * 
+ * TestObserver&lt;Integer&gt; to1 = subject1.test();
+ * 
+ * // MaybeSubjects are empty by default
+ * to1.assertEmpty();
+ * 
+ * subject1.onSuccess(1);
+ * 
+ * // onSuccess is a terminal event with MaybeSubjects
+ * // TestObserver converts onSuccess into onNext + onComplete
+ * to1.assertResult(1);
+ *
+ * TestObserver&lt;Integer&gt; to2 = subject1.test();
+ * 
+ * // late Observers receive the terminal signal (onSuccess) too
+ * to2.assertResult(1);
+ *
+ * // -----------------------------------------------------
+ *
+ * MaybeSubject&lt;Integer&gt; subject2 = MaybeSubject.create();
+ *
+ * TestObserver&lt;Integer&gt; to3 = subject2.test();
+ * 
+ * subject2.onComplete();
+ * 
+ * // a completed MaybeSubject completes its MaybeObservers
+ * to3.assertResult();
+ *
+ * TestObserver&lt;Integer&gt; to4 = subject1.test();
+ * 
+ * // late Observers receive the terminal signal (onComplete) too
+ * to4.assertResult();
+ * </code></pre>
  * <p>History: 2.0.5 - experimental
  * @param <T> the value type received and emitted
  * @since 2.1

src/main/java/io/reactivex/subjects/PublishSubject.java

@@ -22,11 +22,57 @@
 import io.reactivex.plugins.RxJavaPlugins;
 
 /**
- * Subject that, once an {@link Observer} has subscribed, emits all subsequently observed items to the
- * subscriber.
+ * A Subject that emits (multicasts) items to currently subscribed {@link Observer}s and terminal events to current
+ * or late {@code Observer}s.
  * <p>
  * <img width="640" height="405" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/S.PublishSubject.png" alt="">
  * <p>
+ * This subject does not have a public constructor by design; a new empty instance of this
+ * {@code PublishSubject} can be created via the {@link #create()} method.
+ * <p>
+ * Since a {@code Subject} is conceptionally derived from the {@code Processor} type in the Reactive Streams specification,
+ * {@code null}s are not allowed (<a href="https://github.com/reactive-streams/reactive-streams-jvm#2.13">Rule 2.13</a>) as
+ * parameters to {@link #onNext(Object)} and {@link #onError(Throwable)}. Such calls will result in a
+ * {@link NullPointerException} being thrown and the subject's state is not changed.
+ * <p>
+ * Since a {@code PublishSubject} is an {@link io.reactivex.Observable}, it does not support backpressure.
+ * <p>
+ * When this {@code PublishSubject} is terminated via {@link #onError(Throwable)} or {@link #onComplete()},
+ * late {@link io.reactivex.Observer}s only receive the respective terminal event.
+ * <p>
+ * Unlike a {@link BehaviorSubject}, a {@code PublishSubject} doesn't retain/cache items, therefore, a new
+ * {@code Observer} won't receive any past items.
+ * <p>
+ * Even though {@code PublishSubject} implements the {@code Observer} interface, calling
+ * {@code onSubscribe} is not required (<a href="https://github.com/reactive-streams/reactive-streams-jvm#2.12">Rule 2.12</a>)
+ * if the subject is used as a standalone source. However, calling {@code onSubscribe}
+ * after the {@code PublishSubject} reached its terminal state will result in the
+ * given {@code Disposable} being disposed immediately.
+ * <p>
+ * Calling {@link #onNext(Object)}, {@link #onError(Throwable)} and {@link #onComplete()}
+ * is required to be serialized (called from the same thread or called non-overlappingly from different threads
+ * through external means of serialization). The {@link #toSerialized()} method available to all {@code Subject}s
+ * provides such serialization and also protects against reentrance (i.e., when a downstream {@code Observer}
+ * consuming this subject also wants to call {@link #onNext(Object)} on this subject recursively).
+ * <p>
+ * This {@code PublishSubject} supports the standard state-peeking methods {@link #hasComplete()}, {@link #hasThrowable()},
+ * {@link #getThrowable()} and {@link #hasObservers()}.
+ * <dl>
+ *  <dt><b>Scheduler:</b></dt>
+ *  <dd>{@code PublishSubject} does not operate by default on a particular {@link io.reactivex.Scheduler} and
+ *  the {@code Observer}s get notified on the thread the respective {@code onXXX} methods were invoked.</dd>
+ *  <dt><b>Error handling:</b></dt>
+ *  <dd>When the {@link #onError(Throwable)} is called, the {@code PublishSubject} enters into a terminal state
+ *  and emits the same {@code Throwable} instance to the last set of {@code Observer}s. During this emission,
+ *  if one or more {@code Observer}s dispose their respective {@code Disposable}s, the
+ *  {@code Throwable} is delivered to the global error handler via
+ *  {@link io.reactivex.plugins.RxJavaPlugins#onError(Throwable)} (multiple times if multiple {@code Observer}s
+ *  cancel at once).
+ *  If there were no {@code Observer}s subscribed to this {@code PublishSubject} when the {@code onError()}
+ *  was called, the global error handler is not invoked.
+ *  </dd>
+ * </dl>
+ * <p>
  * Example usage:
  * <pre> {@code
 
@@ -40,6 +86,8 @@
   subject.onNext("three");
   subject.onComplete();
 
+  // late Observers only receive the terminal event
+  subject.test().assertEmpty();
   } </pre>
  *
  * @param <T>