Javadoc overhaul: 1) standardize formatting, phrasing, terminology; 2) fill in gaps where javadocs (or parts of them) were missing; 3) add spurious @warn tags to cause build warnings for as-yet-unfilled gaps

Author: DavidMGross

rxjava-core/src/main/java/rx/Notification.java

@@ -18,7 +18,7 @@
 /**
  * An object representing a notification sent to an {@link Observable}.
  * 
- * For the Microsoft Rx equivalent see: http://msdn.microsoft.com/en-us/library/hh229462(v=vs.103).aspx
+ * @see <a href="http://github.com/%3C/span%3Ehttp://msdn.microsoft.com/en-us/library/hh229462%3Cspan%20class="x x-first x-last">.aspx">the Microsoft Rx equivalent</a>
  */
 public class Notification<T> {
 
@@ -28,19 +28,42 @@ public class Notification<T> {
 
     private static final Notification<Void> ON_COMPLETED = new Notification<Void>(Kind.OnCompleted, null, null);
 
+    /**
+     * Creates and returns a {@code Notification} of variety {@code Kind.OnNext}, and assigns it a value.
+     *
+     * @param t
+     *          the item to assign to the notification as its value
+     * @return an {@code OnNext} variety of {@code Notification}
+     */
     public static <T> Notification<T> createOnNext(T t) {
         return new Notification<T>(Kind.OnNext, t, null);
     }
 
+    /**
+     * Creates and returns a {@code Notification} of variety {@code Kind.OnError}, and assigns it an exception.
+     *
+     * @param e
+     *          the exception to assign to the notification
+     * @return an {@code OnError} variety of {@code Notification}
+     */
     public static <T> Notification<T> createOnError(Throwable e) {
         return new Notification<T>(Kind.OnError, null, e);
     }
 
+    /**
+     * Creates and returns a {@code Notification} of variety {@code Kind.OnCompleted}.
+     *
+     * @return an {@code OnCompleted} variety of {@code Notification}
+     */
     @SuppressWarnings("unchecked")
     public static <T> Notification<T> createOnCompleted() {
         return (Notification<T>) ON_COMPLETED;
     }
 
+    /**
+     * @warn javadoc missing
+     * @return
+     */
     @SuppressWarnings("unchecked")
     public static <T> Notification<T> createOnCompleted(Class<T> type) {
         return (Notification<T>) ON_COMPLETED;
@@ -53,62 +76,81 @@ private Notification(Kind kind, T value, Throwable e) {
     }
 
     /**
-     * Retrieves the exception associated with an onError notification.
+     * Retrieves the exception associated with this (onError) notification.
      * 
-     * @return Throwable associated with an onError notification.
+     * @return the Throwable associated with this (onError) notification
      */
     public Throwable getThrowable() {
         return throwable;
     }
 
     /**
-     * Retrieves the data associated with an onNext notification.
+     * Retrieves the item associated with this (onNext) notification.
      * 
-     * @return The data associated with an onNext notification.
+     * @return the item associated with this (onNext) notification
      */
     public T getValue() {
         return value;
     }
 
     /**
-     * Retrieves a value indicating whether this notification has a value.
+     * Indicates whether this notification has an item associated with it.
      * 
-     * @return a value indicating whether this notification has a value.
+     * @return a boolean indicating whether or not this notification has an item associated with it
      */
     public boolean hasValue() {
         return isOnNext() && value != null;
+// isn't "null" a valid item?
     }
 
     /**
-     * Retrieves a value indicating whether this notification has an exception.
+     * Indicates whether this notification has an exception associated with it.
      * 
-     * @return a value indicating whether this notification has an exception.
+     * @return a boolean indicating whether this notification has an exception associated with it
      */
     public boolean hasThrowable() {
         return isOnError() && throwable != null;
     }
 
     /**
-     * Retrieves the kind of the notification: OnNext, OnError, OnCompleted
+     * Retrieves the kind of this notification: {@code OnNext}, {@code OnError}, or {@code OnCompleted}
      * 
-     * @return the kind of the notification: OnNext, OnError, OnCompleted
+     * @return the kind of the notification: {@code OnNext}, {@code OnError}, or {@code OnCompleted}
      */
     public Kind getKind() {
         return kind;
     }
 
+    /**
+     * Indicates whether this notification represents an {@code onError} event.
+     * 
+     * @return a boolean indicating whether this notification represents an {@code onError} event
+     */
     public boolean isOnError() {
         return getKind() == Kind.OnError;
     }
 
+    /**
+     * Indicates whether this notification represents an {@code onCompleted} event.
+     * 
+     * @return a boolean indicating whether this notification represents an {@code onCompleted} event
+     */
     public boolean isOnCompleted() {
         return getKind() == Kind.OnCompleted;
     }
 
+    /**
+     * Indicates whether this notification represents an {@code onNext} event.
+     * 
+     * @return a boolean indicating whether this notification represents an {@code onNext} event
+     */
     public boolean isOnNext() {
         return getKind() == Kind.OnNext;
     }
 
+    /**
+     * @warn javadoc missing
+     */
     public void accept(Observer<? super T> observer) {
         if (isOnNext()) {
             observer.onNext(getValue());

rxjava-core/src/main/java/rx/Observable.java

@@ -2892,19 +2892,16 @@ public final Observable<T> asObservable() {
     /**
      * Returns an Observable that emits buffers of items it collects from the source Observable. The resulting
      * Observable emits connected, non-overlapping buffers. It emits the current buffer and replaces it with a
-     * new buffer when the Observable produced by the specified {@code bufferClosingSelector} emits an item. It
-     * then uses the {@code bufferClosingSelector} to create a new Observable to observe to indicate the end of
-     * the next buffer.
+     * new buffer whenever the Observable produced by the specified {@code bufferClosingSelector} emits an item.
      * <p>
      * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/buffer1.png">
      * 
      * @param bufferClosingSelector
-     *            a {@link Func0} that produces an Observable for each buffer created. When this
-     *            {@code Observable} emits an item, {@code buffer} emits the associated buffer and replaces it
-     *            with a new one
+     *            a {@link Func0} that produces an Observable that governs the boundary between buffers.
+     *            Whenever this {@code Observable} emits an item, {@code buffer} emits the current buffer and
+     *            begins to fill a new one
      * @return an Observable that emits a connected, non-overlapping buffer of items from the source Observable
-     *         each time the current Observable created with the {@code bufferClosingSelector} argument emits an
-     *         item
+     *         each time the Observable created with the {@code bufferClosingSelector} argument emits an item
      * @see <a href="https://github.com/Netflix/RxJava/wiki/Transforming-Observables#wiki-buffer">RxJava Wiki: buffer()</a>
      */
     public final <TClosing> Observable<List<T>> buffer(Func0<? extends Observable<? extends TClosing>> bufferClosingSelector) {
@@ -5495,16 +5492,19 @@ public final <R> Observable<R> scan(R initialValue, Func2<R, ? super T, R> accum
     }
 
     /*
-     * Forces an Observable to make synchronous calls and to be well-behaved.
+     * Forces an Observable's emissions and notifications to be serialized and for it to obey the Rx contract
+     * in other ways.
      * <p>
-     * It is possible for an Observable to invoke its Subscribers' methods asynchronously, perhaps in different
-     * threads. This could make an Observable poorly-behaved, in that it might invoke {@code onCompleted} or
-     * {@code onError} before one of its {@code onNext} invocations. You can force such an Observable to be
-     * well-behaved and synchronous by applying the {@code serialize} method to it.
+     * It is possible for an Observable to invoke its Subscribers' methods asynchronously, perhaps from
+     * different threads. This could make such an Observable poorly-behaved, in that it might try to invoke
+     * {@code onCompleted} or {@code onError} before one of its {@code onNext} invocations, or it might call
+     * {@code onNext} from two different threads simultaneously. You can force such an Observable to be
+     * well-behaved and sequential by applying the {@code serialize} method to it.
      * <p>
      * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/synchronize.png">
      *
-     * @return a {@link Observable} that is guaranteed to be well-behaved and synchronous
+     * @return an {@link Observable} that is guaranteed to be well-behaved and to make only serialized calls to
+     *         its observers
      * @see <a href="https://github.com/Netflix/RxJava/wiki/Observable-Utility-Operators#serialize">RxJava Wiki: serialize()</a>
      * @since 0.17
      */
@@ -7379,17 +7379,17 @@ public final Observable<T> unsubscribeOn(Scheduler scheduler) {
 
     /**
      * Returns an Observable that emits windows of items it collects from the source Observable. The resulting
-     * Observable emits connected, non-overlapping windows. It emits the current window and opens a new one when
-     * the Observable produced by the specified {@code closingSelector} emits an item. The
-     * {@code closingSelector} then creates a new Observable to generate the closer of the next window.
+     * Observable emits connected, non-overlapping windows. It emits the current window and opens a new one
+     * whenever the Observable produced by the specified {@code closingSelector} emits an item.
      * <p>
      * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/window1.png">
      * 
      * @param closingSelector
-     *            a {@link Func0} that produces an Observable for every window created. When this Observable
-     *            emits an item, {@code window} emits the associated window and begins a new one.
+     *            a {@link Func0} that returns an {@code Observable} that governs the boundary between windows.
+     *            When this {@code Observable} emits an item, {@code window} emits the current window and begins
+     *            a new one.
      * @return an Observable that emits connected, non-overlapping windows of items from the source Observable
-     *         when {@code closingSelector} emits an item
+     *         whenever {@code closingSelector} emits an item
      * @see <a href="https://github.com/Netflix/RxJava/wiki/Transforming-Observables#wiki-window">RxJava Wiki: window()</a>
      */
     public final <TClosing> Observable<Observable<T>> window(Func0<? extends Observable<? extends TClosing>> closingSelector) {

rxjava-core/src/main/java/rx/Observer.java

@@ -18,44 +18,45 @@
 /**
  * Provides a mechanism for receiving push-based notifications.
  * <p>
- * After an Observer calls an {@link Observable}'s <code>Observable.subscribe</code> method, the
- * {@link Observable} calls the Observer's <code>onNext</code> method to provide notifications. A well-behaved
- * {@link Observable} will call an Observer's <code>onCompleted</code> closure exactly once or the Observer's
- * <code>onError</code> closure exactly once.
- * <p>
- * For more information see the <a href="https://github.com/Netflix/RxJava/wiki/Observable">RxJava Wiki</a>
+ * After an Observer calls an {@link Observable}'s {@link Observable#subscribe subscribe} method, the
+ * {@code Observable} calls the Observer's {@link #onNext} method to provide notifications. A well-behaved
+ * {@code Observable} will call an Observer's {@link #onCompleted} method exactly once or the Observer's
+ * {@link #onError} method exactly once.
  * 
+ * @see <a href="https://github.com/Netflix/RxJava/wiki/Observable">RxJava Wiki: Observable</a>
  * @param <T>
+ *          the type of item the Observer expects to observe
  */
 public interface Observer<T> {
 
     /**
      * Notifies the Observer that the {@link Observable} has finished sending push-based notifications.
      * <p>
-     * The {@link Observable} will not call this closure if it calls <code>onError</code>.
+     * The {@link Observable} will not call this method if it calls {@link #onError}.
      */
     public abstract void onCompleted();
 
     /**
      * Notifies the Observer that the {@link Observable} has experienced an error condition.
      * <p>
-     * If the {@link Observable} calls this closure, it will not thereafter call <code>onNext</code> or
-     * <code>onCompleted</code>.
+     * If the {@link Observable} calls this method, it will not thereafter call {@link #onNext} or
+     * {@link #onCompleted}.
      * 
      * @param e
+     *          the exception encountered by the Observable
      */
     public abstract void onError(Throwable e);
 
     /**
-     * Provides the Observer with new data.
+     * Provides the Observer with a new item to observe.
      * <p>
-     * The {@link Observable} calls this closure 1 or more times, unless it calls <code>onError</code> in which
-     * case this closure may never be called.
+     * The {@link Observable} may call this closure 0 or more times.
      * <p>
-     * The {@link Observable} will not call this closure again after it calls either <code>onCompleted</code> or
-     * <code>onError</code>.
+     * The {@code Observable} will not call this closure again after it calls either {@link #onCompleted} or
+     * {@link #onError}.
      * 
      * @param t
+     *          the item emitted by the Observable
      */
     public abstract void onNext(T t);
 

rxjava-core/src/main/java/rx/Scheduler.java

@@ -26,7 +26,6 @@
  * Common implementations can be found in {@link Schedulers}.
  * <p>
  * Why is this an abstract class instead of an interface?
- * <p>
  * <ol>
  * <li>Java doesn't support extension methods and there are many overload methods needing default
  * implementations.</li>
@@ -42,13 +41,13 @@
 public abstract class Scheduler {
 
     /**
-     * Retrieve or create a new {@link Scheduler.Worker} that represents serial execution of actions.
+     * Retrieves or creates a new {@link Scheduler.Worker} that represents serial execution of actions.
      * <p>
      * When work is completed it should be unsubscribed using {@link Scheduler.Worker#unsubscribe()}.
      * <p>
      * Work on a {@link Scheduler.Worker} is guaranteed to be sequential.
      * 
-     * @return Worker representing a serial queue of actions to be executed
+     * @return a Worker representing a serial queue of actions to be executed
      */
     public abstract Worker createWorker();
 
@@ -66,19 +65,21 @@ public abstract static class Worker implements Subscription {
          *            Action to schedule
          * @return a subscription to be able to unsubscribe the action (unschedule it if not executed)
          */
-
         public abstract Subscription schedule(Action0 action);
 
         /**
          * Schedules an Action for execution at some point in the future.
-         * <p>Note to implementors: non-positive {@code delayTime} should be regarded as
-         * undelayed schedule, i.e., as if the {@link #schedule(rx.functions.Action0)} was called.
+         * <p>
+         * Note to implementors: non-positive {@code delayTime} should be regarded as undelayed schedule, i.e.,
+         * as if the {@link #schedule(rx.functions.Action0)} was called.
+         *
          * @param action
          *            the Action to schedule
          * @param delayTime
-         *            time to wait before executing the action, non-positive values indicate an undelayed schedule
+         *            time to wait before executing the action; non-positive values indicate an undelayed
+         *            schedule
          * @param unit
-         *            the time unit the delay time is given in
+         *            the time unit of {@code delayTime}
          * @return a subscription to be able to unsubscribe the action (unschedule it if not executed)
          */
         public abstract Subscription schedule(final Action0 action, final long delayTime, final TimeUnit unit);
@@ -87,19 +88,20 @@ public abstract static class Worker implements Subscription {
          * Schedules a cancelable action to be executed periodically. This default implementation schedules
          * recursively and waits for actions to complete (instead of potentially executing long-running actions
          * concurrently). Each scheduler that can do periodic scheduling in a better way should override this.
-         * <p>Note to implementors: non-positive {@code initialTime} and {@code period} should be regarded as
+         * <p>
+         * Note to implementors: non-positive {@code initialTime} and {@code period} should be regarded as
          * undelayed scheduling of the first and any subsequent executions.
          * 
          * @param action
          *            the Action to execute periodically
          * @param initialDelay
-         *            time to wait before executing the action for the first time, 
-         *            non-positive values indicate an undelayed schedule
+         *            time to wait before executing the action for the first time; non-positive values indicate
+         *            an undelayed schedule
          * @param period
-         *            the time interval to wait each time in between executing the action,
-         *            non-positive values indicate no delay between repeated schedules
+         *            the time interval to wait each time in between executing the action; non-positive values
+         *            indicate no delay between repeated schedules
          * @param unit
-         *            the time unit the interval above is given in
+         *            the time unit of {@code period}
          * @return a subscription to be able to unsubscribe the action (unschedule it if not executed)
          */
         public Subscription schedulePeriodically(final Action0 action, long initialDelay, long period, TimeUnit unit) {
@@ -121,15 +123,17 @@ public void call() {
         }
 
         /**
-         * @return the scheduler's notion of current absolute time in milliseconds.
+         * Gets the current time, in milliseconds, according to this Scheduler.
+         *
+         * @return the scheduler's notion of current absolute time in milliseconds
          */
         public long now() {
             return System.currentTimeMillis();
         }
     }
 
     /**
-     * Parallelism available to a Scheduler.
+     * Indicates the parallelism available to this Scheduler.
      * <p>
      * This defaults to {@code Runtime.getRuntime().availableProcessors()} but can be overridden for use cases
      * such as scheduling work on a computer cluster.
@@ -141,7 +145,9 @@ public int parallelism() {
     }
 
     /**
-     * @return the scheduler's notion of current absolute time in milliseconds.
+     * Gets the current time, in milliseconds, according to this Scheduler.
+     *
+     * @return the scheduler's notion of current absolute time in milliseconds
      */
     public long now() {
         return System.currentTimeMillis();