Filling in more gaps in the javadocs.

DavidMGross · DavidMGross · commit ea2249afecbf · 2014-05-28T16:37:28.000-07:00
diff --git a/rxjava-core/src/main/java/rx/Notification.java b/rxjava-core/src/main/java/rx/Notification.java
@@ -61,8 +61,11 @@ public static <T> Notification<T> createOnCompleted() {
     }
 
     /**
-     * @warn javadoc missing
-     * @return
+     * Creates and returns a {@code Notification} of variety {@code Kind.OnCompleted}.
+     *
+     * @warn param "type" undescribed
+     * @param type
+     * @return an {@code OnCompleted} variety of {@code Notification}
      */
     @SuppressWarnings("unchecked")
     public static <T> Notification<T> createOnCompleted(Class<T> type) {
@@ -149,7 +152,7 @@ public boolean isOnNext() {
     }
 
     /**
-     * @warn javadoc missing
+     * Forwards this notification on to a specified {@link Observer}.
      */
     public void accept(Observer<? super T> observer) {
         if (isOnNext()) {
diff --git a/rxjava-core/src/main/java/rx/Observable.java b/rxjava-core/src/main/java/rx/Observable.java
@@ -3214,16 +3214,18 @@ public final <R> Observable<R> cast(final Class<R> klass) {
     }
 
     /**
-     * Collects values emitted by the source Observable into a single mutable data structure and returns an
+     * Collects items emitted by the source Observable into a single mutable data structure and returns an
      * Observable that emits this structure.
      * <p>
+     * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/collect.png">
+     * <p>
      * This is a simplified version of {@code reduce} that does not need to return the state on each pass.
      * 
-     * @warn javadocs incomplete; no marble diagram for this operator
      * @param state
-     * @warn javadocs incomplete; "state" parameter not described
+     *           the mutable data structure that will collect the items
      * @param collector
-     * @warn javadocs incomplete; "collector" parameter not described
+     *           a function that accepts the {@code state} and an emitted item, and modifies {@code state}
+     *           accordingly
      * @return an Observable that emits the result of collecting the values emitted by the source Observable
      *         into a single mutable data structure
      */
@@ -5502,7 +5504,7 @@ public final <R> Observable<R> scan(R initialValue, Func2<R, ? super T, R> accum
      * 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
+     * {@code onNext} from two different threads concurrently. 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">
diff --git a/rxjava-core/src/main/java/rx/Subscriber.java b/rxjava-core/src/main/java/rx/Subscriber.java
@@ -63,8 +63,9 @@ public final void unsubscribe() {
     }
 
     /**
-     * @warn javadoc missing
-     * @return
+     * Indicates whether this Subscriber has unsubscribed from its Observable.
+     * 
+     * @return {@code true} if this Subscriber has unsubscribed from its Observable, {@code false} otherwise
      */
     public final boolean isUnsubscribed() {
         return cs.isUnsubscribed();
diff --git a/rxjava-core/src/main/java/rx/exceptions/CompositeException.java b/rxjava-core/src/main/java/rx/exceptions/CompositeException.java
@@ -54,25 +54,20 @@ public CompositeException(Collection<Throwable> errors) {
     }
 
     /**
-     * @warn javadoc missing
+     * Retrieves the list of exceptions that make up the {@code CompositeException}
+     *
+     * @return the exceptions that make up the {@code CompositeException}, as a {@link List} of
+     *         {@link Throwable}s
      */
     public List<Throwable> getExceptions() {
         return exceptions;
     }
 
-    /**
-     * Returns a concatenation of the composite exceptions.
-     *
-     * @warn return value undocumented (e.g. how are multiple exceptions delimited?)
-     */
     @Override
     public String getMessage() {
         return message;
     }
 
-    /**
-     * @warn javadoc missing
-     */
     @Override
     public synchronized Throwable getCause() {
         return cause;
diff --git a/rxjava-core/src/main/java/rx/exceptions/OnErrorFailedException.java b/rxjava-core/src/main/java/rx/exceptions/OnErrorFailedException.java
@@ -26,14 +26,23 @@ public class OnErrorFailedException extends RuntimeException {
     private static final long serialVersionUID = -419289748403337611L;
 
     /**
-     * @warn javadoc missing
+     * Customizes the {@code Throwable} with a custom message and wraps it before it is to be re-thrown as an
+     * {@code OnErrorFailedException}.
+     *
+     * @param message
+     *          the message to assign to the {@code Throwable} to re-throw
+     * @param e
+     *          the {@code Throwable} to re-throw
      */
     public OnErrorFailedException(String message, Throwable e) {
         super(message, e);
     }
 
     /**
-     * @warn javadoc missing
+     * Wraps the {@code Throwable} before it is to be re-thrown as an {@code OnErrorFailedException}.
+     *
+     * @param e
+     *          the {@code Throwable} to re-throw
      */
     public OnErrorFailedException(Throwable e) {
         super(e.getMessage(), e);
diff --git a/rxjava-core/src/main/java/rx/exceptions/OnErrorNotImplementedException.java b/rxjava-core/src/main/java/rx/exceptions/OnErrorNotImplementedException.java
@@ -33,14 +33,23 @@ public class OnErrorNotImplementedException extends RuntimeException {
     private static final long serialVersionUID = -6298857009889503852L;
 
     /**
-     * @warn javadoc missing
+     * Customizes the {@code Throwable} with a custom message and wraps it before it is to be re-thrown as an
+     * {@code OnErrorNotImplementedException}.
+     *
+     * @param message
+     *          the message to assign to the {@code Throwable} to re-throw
+     * @param e
+     *          the {@code Throwable} to re-throw
      */
     public OnErrorNotImplementedException(String message, Throwable e) {
         super(message, e);
     }
 
     /**
-     * @warn javadoc missing
+     * Wraps the {@code Throwable} before it is to be re-thrown as an {@code OnErrorNotImplementedException}.
+     *
+     * @param e
+     *          the {@code Throwable} to re-throw
      */
     public OnErrorNotImplementedException(Throwable e) {
         super(e.getMessage(), e);
diff --git a/rxjava-core/src/main/java/rx/exceptions/OnErrorThrowable.java b/rxjava-core/src/main/java/rx/exceptions/OnErrorThrowable.java
@@ -46,8 +46,10 @@ public Object getValue() {
     }
 
     /**
-     * @warn javadoc missing
-     * @return
+     * Indicates whether or not there is a value associated with this {@code OnErrorThrowable}
+     *
+     * @return {@code true} if there is a value associated with this {@code OnErrorThrowable}, otherwise
+     *         {@code false}
      */
     public boolean isValueNull() {
         return hasValue;
diff --git a/rxjava-core/src/main/java/rx/plugins/RxJavaPlugins.java b/rxjava-core/src/main/java/rx/plugins/RxJavaPlugins.java
@@ -34,8 +34,9 @@ public class RxJavaPlugins {
     private final AtomicReference<RxJavaDefaultSchedulers> schedulerOverrides = new AtomicReference<RxJavaDefaultSchedulers>();
 
     /**
-     * @warn javadoc missing
-     * @return
+     * Retrieves the single {@code RxJavaPlugins} instance.
+     *
+     * @return the single {@code RxJavaPlugins} instance
      */
     public static RxJavaPlugins getInstance() {
         return INSTANCE;
diff --git a/rxjava-core/src/main/java/rx/schedulers/Schedulers.java b/rxjava-core/src/main/java/rx/schedulers/Schedulers.java
@@ -111,8 +111,10 @@ public static Scheduler io() {
     }
 
     /**
-     * @warn javadoc missing
-     * @return
+     * Creates and returns a {@code TestScheduler}, which is useful for debugging. It allows you to test
+     * schedules of events by manually advancing the clock at whatever pace you choose.
+     *
+     * @return a {@code TestScheduler} meant for debugging
      */
     public static TestScheduler test() {
         return new TestScheduler();
diff --git a/rxjava-core/src/main/java/rx/schedulers/TestScheduler.java b/rxjava-core/src/main/java/rx/schedulers/TestScheduler.java
@@ -27,7 +27,8 @@
 import rx.subscriptions.Subscriptions;
 
 /**
- * @warn javadoc class description missing
+ * The {@code TestScheduler} is useful for debugging. It allows you to test schedules of events by manually
+ * advancing the clock at whatever pace you choose.
  */
 public class TestScheduler extends Scheduler {
     private final Queue<TimedAction> queue = new PriorityQueue<TimedAction>(11, new CompareActionsByTime());
@@ -72,22 +73,33 @@ public long now() {
     }
 
     /**
-     * @warn javadoc missing
+     * Moves the Scheduler's clock forward by a specified amount of time.
+     *
+     * @param delayTime
+     *          the amount of time to move the Scheduler's clock forward
+     * @param unit
+     *          the units of time that {@code delayTime} is expressed in
      */
     public void advanceTimeBy(long delayTime, TimeUnit unit) {
         advanceTimeTo(time + unit.toNanos(delayTime), TimeUnit.NANOSECONDS);
     }
 
     /**
-     * @warn javadoc missing
+     * Moves the Scheduler's clock to a particular moment in time.
+     *
+     * @param delayTime
+     *          the point in time to move the Scheduler's clock to
+     * @param unit
+     *          the units of time that {@code delayTime} is expressed in
      */
     public void advanceTimeTo(long delayTime, TimeUnit unit) {
         long targetTime = unit.toNanos(delayTime);
         triggerActions(targetTime);
     }
 
     /**
-     * @warn javadoc missing
+     * Triggers any actions that have not yet been triggered and that are scheduled to be triggered at or
+     * before this Scheduler's present time.
      */
     public void triggerActions() {
         triggerActions(time);
diff --git a/rxjava-core/src/main/java/rx/schedulers/TimeInterval.java b/rxjava-core/src/main/java/rx/schedulers/TimeInterval.java
@@ -16,29 +16,42 @@
 package rx.schedulers;
 
 /**
- * @warn javadoc class description missing
+ * A {@code TimeInterval} represents an item emitted by an {@code Observable} along with the amount of time that
+ * elapsed either since the emission of the previous item or (if there was no previous item) since the
+ * {@code Observable} was first subscribed to.
  */
 public class TimeInterval<T> {
     private final long intervalInMilliseconds;
     private final T value;
 
+    /**
+     * Creates a {@code TimeInterval} object.
+     *
+     * @param intervalInMilliseconds
+     *          the number of milliseconds between the time when {@code value} was emitted and the item that
+     *          was emitted immediately prior to {@code value}, or, if there was no such prior item, since the
+     *          initial subscription to the {@code Observable}
+     * @param value
+     *          the item emitted by the Observable
+     */
     public TimeInterval(long intervalInMilliseconds, T value) {
         this.value = value;
         this.intervalInMilliseconds = intervalInMilliseconds;
     }
 
     /**
-     * Returns the interval, expressed in milliseconds.
+     * Returns the time interval, expressed in milliseconds.
      * 
-     * @return the interval in milliseconds
+     * @return the time interval in milliseconds
      */
     public long getIntervalInMilliseconds() {
         return intervalInMilliseconds;
     }
 
     /**
-     * @warn javadoc missing
-     * @return
+     * Returns the item that was emitted by the Observable after this time interval.
+     *
+     * @return the item that was emitted by the Observable
      */
     public T getValue() {
         return value;
diff --git a/rxjava-core/src/main/java/rx/subjects/AsyncSubject.java b/rxjava-core/src/main/java/rx/subjects/AsyncSubject.java
@@ -53,8 +53,9 @@
 public final class AsyncSubject<T> extends Subject<T, T> {
 
     /**
-     * @warn javadoc missing
-     * @return
+     * Creates and returns a new {@code AsyncSubject}.
+     *
+     * @return the new {@code AsyncSubject}
      */
     public static <T> AsyncSubject<T> create() {
         final SubjectSubscriptionManager<T> state = new SubjectSubscriptionManager<T>();
diff --git a/rxjava-core/src/main/java/rx/subjects/PublishSubject.java b/rxjava-core/src/main/java/rx/subjects/PublishSubject.java
@@ -48,8 +48,9 @@
 public final class PublishSubject<T> extends Subject<T, T> {
 
     /**
-     * @warn javadoc missing
-     * @return
+     * Creates and returns a new {@code PublishSubject}.
+     *
+     * @return the new {@code PublishSubject}
      */
     public static <T> PublishSubject<T> create() {
         final SubjectSubscriptionManager<T> state = new SubjectSubscriptionManager<T>();
diff --git a/rxjava-core/src/main/java/rx/subjects/TestSubject.java b/rxjava-core/src/main/java/rx/subjects/TestSubject.java
@@ -48,6 +48,7 @@
  * 
  * @param <T>
  *          the type of item observed by and emitted by the subject
+ * @warn javadoc seems misleading
  */
 public final class TestSubject<T> extends Subject<T, T> {
 
diff --git a/rxjava-core/src/main/java/rx/subscriptions/BooleanSubscription.java b/rxjava-core/src/main/java/rx/subscriptions/BooleanSubscription.java
@@ -43,16 +43,20 @@ private BooleanSubscription(Action0 action) {
     }
 
     /**
-     * @warn javadoc missing
-     * @return
+     * Creates a {@code BooleanSubscription} without unsubscribe behavior.
+     *
+     * @return the created {@code BooleanSubscription}
      */
     public static BooleanSubscription create() {
         return new BooleanSubscription();
     }
 
     /**
-     * @warn javadoc missing
-     * @return
+     * Creates a {@code BooleanSubscription} with a specified function to invoke upon unsubscribe.
+     *
+     * @param onUnsubscribe
+     *          an {@link Action0} to invoke upon unsubscribe
+     * @return the created {@code BooleanSubscription}
      */
     public static BooleanSubscription create(Action0 onUnsubscribe) {
         return new BooleanSubscription(onUnsubscribe);
diff --git a/rxjava-core/src/main/java/rx/subscriptions/CompositeSubscription.java b/rxjava-core/src/main/java/rx/subscriptions/CompositeSubscription.java
@@ -114,7 +114,13 @@ public boolean isUnsubscribed() {
     }
 
     /**
-     * @warn javadoc missing
+     * Adds a new {@link Subscription} to this {@code CompositeSubscription} if the
+     * {@code CompositeSubscription} is not yet unsubscribed. If the {@code CompositeSubscription} <em>is</em>
+     * unsubscribed, {@code add} will indicate this by explicitly unsubscribing the new {@code Subscription} as
+     * well.
+     *
+     * @param s
+     *          the {@link Subscription} to add
      */
     public void add(final Subscription s) {
         State oldState;
@@ -131,7 +137,11 @@ public void add(final Subscription s) {
     }
 
     /**
-     * @warn javadoc missing
+     * Removes a {@link Subscription} from this {@code CompositeSubscription}, and unsubscribes the
+     * {@link Subscription}.
+     *
+     * @param s
+     *          the {@link Subscription} to remove
      */
     public void remove(final Subscription s) {
         State oldState;
@@ -149,7 +159,9 @@ public void remove(final Subscription s) {
     }
 
     /**
-     * @warn javadoc missing
+     * Unsubscribes any subscriptions that are currently part of this {@code CompositeSubscription} and remove
+     * them from the {@code CompositeSubscription} so that the {@code CompositeSubscription} is empty and in
+     * an unoperative state.
      */
     public void clear() {
         State oldState;
diff --git a/rxjava-core/src/main/java/rx/subscriptions/MultipleAssignmentSubscription.java b/rxjava-core/src/main/java/rx/subscriptions/MultipleAssignmentSubscription.java
@@ -73,6 +73,8 @@ public void unsubscribe() {
 
     /**
      * @warn javadoc missing
+     * @param s
+     * @throws IllegalArgumentException
      */
     public void set(Subscription s) {
         if (s == null) {
diff --git a/rxjava-core/src/main/java/rx/subscriptions/SerialSubscription.java b/rxjava-core/src/main/java/rx/subscriptions/SerialSubscription.java
