javadocs for Subscriber variants: take care of Observer/Subscriber distinction (#1848)

Author: DavidMGross

src/main/java/rx/observers/SafeSubscriber.java

@@ -25,16 +25,17 @@
 import rx.plugins.RxJavaPlugins;
 
 /**
- * Wrapper around {@code Observer} that ensures compliance with the Rx contract.
+ * {@code SafeSubscriber} is a wrapper around {@code Subscriber} that ensures that the {@code Subscriber}
+ * complies with the Rx contract.
  * <p>
  * The following is taken from <a href="http://go.microsoft.com/fwlink/?LinkID=205219">the Rx Design Guidelines
  * document</a>:
  * <blockquote><p>
  * Messages sent to instances of the {@code IObserver} interface follow the following grammar:
  * </p><blockquote><p> {@code OnNext* (OnCompleted | OnError)?} </p></blockquote><p>
  * This grammar allows observable sequences to send any amount (0 or more) of {@code OnNext} messages to the
- * subscribed observer instance, optionally followed by a single success ({@code OnCompleted}) or failure
- * ({@code OnError}) message.
+ * subscriber, optionally followed by a single success ({@code OnCompleted}) or failure ({@code OnError})
+ * message.
  * </p><p>
  * The single message indicating that an observable sequence has finished ensures that consumers of the
  * observable sequence can deterministically establish that it is safe to perform cleanup operations.
@@ -47,10 +48,10 @@
  * <ul>
  * <li>Allows only single execution of either {@code onError} or {@code onCompleted}.</li>
  * <li>Ensures that once an {@code onCompleted} or {@code onError} is performed, no further calls can be executed</li>
- * <li>If {@code unsubscribe} is called, calls {@code completed} and forbids any further {@code onNext} calls.</li>
- * <li>When {@code onError} or {@code onComplete} occur, unsubscribes from the {@code Observable} (if executing asynchronously).</li>
+ * <li>If {@code unsubscribe} is called, calls {@code onCompleted} and forbids any further {@code onNext} calls.</li>
+ * <li>When {@code onError} or {@code onCompleted} occur, unsubscribes from the {@code Observable} (if executing asynchronously).</li>
  * </ul>
- * <p> {@code SafeSubscriber} will not synchronize {@code onNext} execution. Use {@link SerializedSubscriber} to do
+ * {@code SafeSubscriber} will not synchronize {@code onNext} execution. Use {@link SerializedSubscriber} to do
  * that.
  * 
  * @param <T>

src/main/java/rx/observers/TestSubscriber.java

@@ -24,8 +24,8 @@
 import rx.Subscriber;
 
 /**
- * Subscriber usable for unit testing to perform assertions, inspect received events, or wrap a mocked
- * Subscriber.
+ * A {@code TestSubscriber} is a variety of {@link Subscriber} that you can use for unit testing, to perform
+ * assertions, inspect received events, or wrap a mocked {@code Subscriber}.
  */
 public class TestSubscriber<T> extends Subscriber<T> {
 
@@ -73,8 +73,8 @@ public void onCompleted() {
     }
 
     /**
-     * Get the {@link Notification}s representing each time this Subscriber was notified of sequence completion
-     * via {@link #onCompleted}, as a {@link List}.
+     * Get the {@link Notification}s representing each time this {@link Subscriber} was notified of sequence
+     * completion via {@link #onCompleted}, as a {@link List}.
      *
      * @return a list of Notifications representing calls to this Subscriber's {@link #onCompleted} method
      */
@@ -93,7 +93,8 @@ public void onError(Throwable e) {
     }
 
     /**
-     * Get the {@link Throwable}s this Subscriber was notified of via {@link #onError} as a {@link List}.
+     * Get the {@link Throwable}s this {@link Subscriber} was notified of via {@link #onError} as a
+     * {@link List}.
      *
      * @return a list of the Throwables that were passed to this Subscriber's {@link #onError} method
      */
@@ -109,14 +110,16 @@ public void onNext(T t) {
 
     /**
      * Allow calling the protected {@link #request(long)} from unit tests.
+     *
      * @param n
+     * @warn parameter "n" not described
      */
     public void requestMore(long n) {
         request(n);
     }
 
     /**
-     * Get the sequence of items observed by this Subscriber, as an ordered {@link List}.
+     * Get the sequence of items observed by this {@link Subscriber}, as an ordered {@link List}.
      *
      * @return a list of items observed by this Subscriber, in the order in which they were observed
      */
@@ -125,7 +128,7 @@ public List<T> getOnNextEvents() {
     }
 
     /**
-     * Assert that a particular sequence of items was received by this Subscriber in order.
+     * Assert that a particular sequence of items was received by this {@link Subscriber} in order.
      *
      * @param items
      *          the sequence of items expected to have been observed
@@ -174,8 +177,8 @@ public void assertNoErrors() {
 
 
     /**
-     * Blocks until this Subscriber receives a notification that the Observable is complete (either an
-     * {@code onCompleted} or {@code onError} notification).
+     * Blocks until this {@link Subscriber} receives a notification that the {@code Observable} is complete
+     * (either an {@code onCompleted} or {@code onError} notification).
      *
      * @throws RuntimeException
      *          if the Subscriber is interrupted before the Observable is able to complete
@@ -189,8 +192,8 @@ public void awaitTerminalEvent() {
     }
 
     /**
-     * Blocks until this Subscriber receives a notification that the Observable is complete (either an
-     * {@code onCompleted} or {@code onError} notification), or until a timeout expires.
+     * Blocks until this {@link Subscriber} receives a notification that the {@code Observable} is complete
+     * (either an {@code onCompleted} or {@code onError} notification), or until a timeout expires.
      *
      * @param timeout
      *          the duration of the timeout
@@ -208,10 +211,10 @@ public void awaitTerminalEvent(long timeout, TimeUnit unit) {
     }
 
     /**
-     * Blocks until this Subscriber receives a notification that the Observable is complete (either an
-     * {@code onCompleted} or {@code onError} notification), or until a timeout expires; if the Subscriber
-     * is interrupted before either of these events take place, this method unsubscribes the Subscriber from the
-     * Observable).
+     * Blocks until this {@link Subscriber} receives a notification that the {@code Observable} is complete
+     * (either an {@code onCompleted} or {@code onError} notification), or until a timeout expires; if the
+     * Subscriber is interrupted before either of these events take place, this method unsubscribes the
+     * Subscriber from the Observable).
      *
      * @param timeout
      *          the duration of the timeout
@@ -227,7 +230,8 @@ public void awaitTerminalEventAndUnsubscribeOnTimeout(long timeout, TimeUnit uni
     }
 
     /**
-     * Returns the last thread that was in use when an item or notification was received by this Subscriber.
+     * Returns the last thread that was in use when an item or notification was received by this
+     * {@link Subscriber}.
      *
      * @return the {@code Thread} on which this Subscriber last received an item or notification from the
      *         Observable it is subscribed to