Javadoc changes:

* flesh out and update @throws sections
* add @warn nags to missing javadocs
* standardize formatting
* fix dead links to images

Author: DavidMGross

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

@@ -4146,8 +4146,8 @@ public final Observable<T> finallyDo(Action0 action) {
     }
 
     /**
-     * Returns an Observable that emits only the very first item emitted by the source Observable, or raises an
-     * {@code NoSuchElementException} if the source Observable is empty.
+     * Returns an Observable that emits only the very first item emitted by the source Observable, or notifies
+     * of an {@code NoSuchElementException} if the source Observable is empty.
      * <p>
      * <img width="640" height="310" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/first.png">
      * <p>
@@ -4164,7 +4164,7 @@ public final Observable<T> first() {
 
     /**
      * Returns an Observable that emits only the very first item emitted by the source Observable that satisfies
-     * a specified condition, or raises an {@code NoSuchElementException} if no such items are emitted.
+     * a specified condition, or notifies of an {@code NoSuchElementException} if no such items are emitted.
      * <p>
      * <img width="640" height="310" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/firstN.png">
      * <p>
@@ -4486,7 +4486,7 @@ public final <TRight, TLeftDuration, TRightDuration, R> Observable<R> join(Obser
 
     /**
      * Returns an Observable that emits the last item emitted by the source Observable or notifies observers of
-     * an {@code NoSuchElementException} if the source Observable is empty.
+     * a {@code NoSuchElementException} if the source Observable is empty.
      * <p>
      * <img width="640" height="305" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/last.png">
      * <p>
@@ -4503,7 +4503,7 @@ public final Observable<T> last() {
 
     /**
      * Returns an Observable that emits only the last item emitted by the source Observable that satisfies a
-     * given condition, or an {@code NoSuchElementException} if no such items are emitted.
+     * given condition, or notifies of a {@code NoSuchElementException} if no such items are emitted.
      * <p>
      * <img width="640" height="305" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/last.p.png">
      * <p>
@@ -5964,8 +5964,8 @@ public final Observable<T> share() {
 
     /**
      * Returns an Observable that emits the single item emitted by the source Observable, if that Observable
-     * emits only a single item. If the source Observable emits more than one item or no items, throw an
-     * {@code NoSuchElementException}.
+     * emits only a single item. If the source Observable emits more than one item or no items, notify of an
+     * {@code IllegalArgumentException} or {@code NoSuchElementException} respectively.
      * <p>
      * <img width="640" height="315" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/single.png">
      * <p>
@@ -5986,7 +5986,8 @@ public final Observable<T> single() {
     /**
      * Returns an Observable that emits the single item emitted by the source Observable that matches a
      * specified predicate, if that Observable emits one such item. If the source Observable emits more than one
-     * such item or no such items, throw an {@code NoSuchElementException}.
+     * such item or no such items, notify of an {@code IllegalArgumentException} or
+     * {@code NoSuchElementException} respectively.
      * <p>
      * <img width="640" height="315" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/single.p.png">
      * <p>
@@ -6987,6 +6988,8 @@ public final Observable<T> takeFirst(Func1<? super T, Boolean> predicate) {
      *            the number of items to emit from the end of the sequence of items emitted by the source
      *            Observable
      * @return an Observable that emits only the last {@code count} items emitted by the source Observable
+     * @throws IndexOutOfBoundsException
+     *             if {@code count} is less than zero
      * @see <a href="https://github.com/Netflix/RxJava/wiki/Filtering-Observables#wiki-takelast">RxJava Uncyclo: takeLast()</a>
      */
     public final Observable<T> takeLast(final int count) {
@@ -7032,7 +7035,7 @@ public final Observable<T> takeLast(int count, long time, TimeUnit unit) {
      * @return an Observable that emits at most {@code count} items from the source Observable that were emitted
      *         in a specified window of time before the Observable completed, where the timing information is
      *         provided by the given {@code scheduler}
-     * @throws IllegalArgumentException
+     * @throws IndexOutOfBoundsException
      *             if {@code count} is less than zero
      */
     public final Observable<T> takeLast(int count, long time, TimeUnit unit, Scheduler scheduler) {

rxjava-core/src/main/java/rx/internal/operators/BlockingOperatorLatest.java

@@ -26,16 +26,20 @@
 import rx.exceptions.Exceptions;
 
 /**
- * Wait for and iterate over the latest values of the source observable.
- * If the source works faster than the iterator, values may be skipped, but
- * not the onError or onCompleted events.
+ * Wait for and iterate over the latest values of the source observable. If the source works faster than the
+ * iterator, values may be skipped, but not the {@code onError} or {@code onCompleted} events.
  */
 public final class BlockingOperatorLatest {
     /** Utility class. */
     private BlockingOperatorLatest() {
         throw new IllegalStateException("No instances!");
     }
 
+    /**
+     * @warn latest() missing javadoc
+     * @param source
+     * @return
+     */
     public static <T> Iterable<T> latest(final Observable<? extends T> source) {
         return new Iterable<T>() {
             @Override

rxjava-core/src/main/java/rx/internal/operators/BlockingOperatorMostRecent.java

@@ -29,6 +29,12 @@
  */
 public final class BlockingOperatorMostRecent {
 
+    /**
+     * @warn mostRecent() missing javadocs
+     * @param source
+     * @param initialValue
+     * @return
+     */
     public static <T> Iterable<T> mostRecent(final Observable<? extends T> source, final T initialValue) {
 
         return new Iterable<T>() {

rxjava-core/src/main/java/rx/internal/operators/BlockingOperatorNext.java

@@ -33,6 +33,11 @@
  */
 public final class BlockingOperatorNext {
 
+    /**
+     * @warn next() missing javadocs
+     * @param items
+     * @return
+     */
     public static <T> Iterable<T> next(final Observable<? extends T> items) {
         return new Iterable<T>() {
             @Override

rxjava-core/src/main/java/rx/internal/operators/BufferUntilSubscriber.java

@@ -27,25 +27,33 @@
 import rx.subscriptions.Subscriptions;
 
 /**
- * A solution to the "time gap" problem that occurs with `groupBy` and `pivot` => https://github.com/Netflix/RxJava/issues/844
- * 
+ * A solution to the "time gap" problem that occurs with {@code groupBy} and {@code pivot}.
+ * <p>
  * This currently has temporary unbounded buffers. It needs to become bounded and then do one of two things:
- * 
- * 1) blow up and make the user do something about it
- * 2) work with the backpressure solution ... still to be implemented (such as co-routines)
- * 
- * Generally the buffer should be very short lived (milliseconds) and then stops being involved.
- * It can become a memory leak though if a GroupedObservable backed by this class is emitted but never subscribed to (such as filtered out).
- * In that case, either a time-bomb to throw away the buffer, or just blowing up and making the user do something about it is needed.
- * 
- * For example, to filter out GroupedObservables, perhaps they need a silent `subscribe()` on them to just blackhole the data.
- * 
- * This is an initial start at solving this problem and solves the immediate problem of `groupBy` and `pivot` and trades off the possibility of memory leak for deterministic functionality.
+ * <ol>
+ * <li>blow up and make the user do something about it</li>
+ * <li>work with the backpressure solution ... still to be implemented (such as co-routines)</li>
+ * </ol><p>
+ * Generally the buffer should be very short lived (milliseconds) and then stops being involved. It can become a
+ * memory leak though if a {@code GroupedObservable} backed by this class is emitted but never subscribed to
+ * (such as filtered out). In that case, either a time-bomb to throw away the buffer, or just blowing up and
+ * making the user do something about it is needed.
+ * <p>
+ * For example, to filter out {@code GroupedObservable}s, perhaps they need a silent {@code subscribe()} on them
+ * to just blackhole the data.
+ * <p>
+ * This is an initial start at solving this problem and solves the immediate problem of {@code groupBy} and
+ * {@code pivot} and trades off the possibility of memory leak for deterministic functionality.
  *
+ * @see <a href="https://github.com/Netflix/RxJava/issues/844">the Github issue describing the time gap problem</a>
+ * @warn type param "T" undescribed
  * @param <T>
  */
 public class BufferUntilSubscriber<T> extends Subject<T, T> {
 
+    /**
+     * @warn create() undescribed
+     */
     public static <T> BufferUntilSubscriber<T> create() {
         State<T> state = new State<T>();
         return new BufferUntilSubscriber<T>(state);
@@ -136,8 +144,8 @@ public void onNext(T t) {
      * from the producer and will drain the queue of any items received during the race of the initial drain and
      * switching this.
      * 
-     * It will then immediately swap itself out for the actual (after a single notification), but since this is now
-     * being done on the same producer thread no further buffering will occur.
+     * It will then immediately swap itself out for the actual (after a single notification), but since this is
+     * now being done on the same producer thread no further buffering will occur.
      */
     private static final class PassThruObserver<T> extends Subscriber<T> {
 

rxjava-core/src/main/java/rx/internal/operators/NotificationLite.java

@@ -21,17 +21,17 @@
 import rx.Observer;
 
 /**
- * For use in internal operators that need something like materialize and dematerialize wholly
- * within the implementation of the operator but don't want to incur the allocation cost of actually
- * creating {@link rx.Notification} objects for every onNext and onComplete.
+ * For use in internal operators that need something like materialize and dematerialize wholly within the
+ * implementation of the operator but don't want to incur the allocation cost of actually creating
+ * {@link rx.Notification} objects for every {@code onNext} and {@code onComplete}.
  * 
- * An object is allocated inside {@link #error(Throwable)} to wrap the {@link Throwable} but this
- * shouldn't effect performance because exceptions should be exceptionally rare.
+ * An object is allocated inside {@link #error(Throwable)} to wrap the {@link Throwable} but this shouldn't
+ * affect performance because exceptions should be exceptionally rare.
  * 
- * It's implemented as a singleton to maintain some semblance of type safety that is completely
- * non-existent.
+ * It's implemented as a singleton to maintain some semblance of type safety that is completely non-existent.
  * 
  * @param <T>
+ * @warn type param <T> undescribed
  */
 public final class NotificationLite<T> {
     private NotificationLite() {
@@ -40,6 +40,9 @@ private NotificationLite() {
     @SuppressWarnings("rawtypes")
     private static final NotificationLite INSTANCE = new NotificationLite();
 
+    /**
+     * @warn instance() undocumented
+     */
     @SuppressWarnings("unchecked")
     public static <T> NotificationLite<T> instance() {
         return INSTANCE;
@@ -63,10 +66,11 @@ public OnErrorSentinel(Throwable e) {
     }
 
     /**
-     * Creates a lite onNext notification for the value passed in without doing any allocation. Can
+     * Creates a lite {@code onNext} notification for the value passed in without doing any allocation. Can
      * be unwrapped and sent with the {@link #accept} method.
      * 
      * @param t
+     * @warn parameter "t" undescribed
      * @return the value or a null token
      */
     public Object next(T t) {
@@ -77,7 +81,7 @@ public Object next(T t) {
     }
 
     /**
-     * Creates a lite onComplete notification without doing any allocation. Can be unwrapped and
+     * Creates a lite {@code onComplete} notification without doing any allocation. Can be unwrapped and
      * sent with the {@link #accept} method.
      * 
      * @return the completion token
@@ -87,10 +91,13 @@ public Object completed() {
     }
 
     /**
-     * Create a lite onError notification. This call does new up an object to wrap the {@link Throwable} but since there should only be one of these the performance impact should
-     * be small. Can be unwrapped and sent with the {@link #accept} method.
+     * Create a lite {@code onError} notification. This call does new up an object to wrap the {@link Throwable}
+     * but since there should only be one of these the performance impact should be small. Can be unwrapped and
+     * sent with the {@link #accept} method.
      * 
+     * @warn description doesn't parse in English ("This call does new up an object...")
      * @param e
+     * @warn parameter "e" undescribed
      * @return an object encapsulating the exception
      */
     public Object error(Throwable e) {
@@ -101,9 +108,10 @@ public Object error(Throwable e) {
      * Unwraps the lite notification and calls the appropriate method on the {@link Observer}.
      * 
      * @param o
-     *            the {@link Observer} to call onNext, onCompleted or onError.
+     *            the {@link Observer} to call onNext, onCompleted, or onError.
+     * @warn parameter "n" undescribed
      * @param n
-     * @return true if the n was a termination event
+     * @return true if {@code n} was a termination event
      * @throws IllegalArgumentException
      *             if the notification is null.
      * @throws NullPointerException
@@ -129,18 +137,28 @@ public boolean accept(Observer<? super T> o, Object n) {
         }
     }
 
+    /**
+     * @warn isCompleted() undocumented
+     */
     public boolean isCompleted(Object n) {
         return n == ON_COMPLETED_SENTINEL;
     }
 
+    /**
+     * @warn isError() undocumented
+     */
     public boolean isError(Object n) {
         return n instanceof OnErrorSentinel;
     }
 
     /**
-     * If there is custom logic that isn't as simple as call the right method on an {@link Observer} then this method can be used to get the {@link rx.Notification.Kind}
+     * If there is custom logic that isn't as simple as call the right method on an {@link Observer} then this
+     * method can be used to get the {@link rx.Notification.Kind}.
      * 
      * @param n
+     * @warn parameter "n" undescribed
+     * @throws IllegalArgumentException
+     *             if the notification is null.
      * @return the kind of the raw object
      */
     public Kind kind(Object n) {
@@ -156,11 +174,12 @@ else if (n instanceof OnErrorSentinel)
     }
 
     /**
-     * returns value passed in {@link #next(Object)} method call. Bad things happen if you call this
-     * the onComplete or onError notification type. For performance you are expected to use this
+     * Returns the value passed in {@link #next(Object)} method call. Bad things happen if you call this
+     * the {@code onComplete} or {@code onError} notification type. For performance you are expected to use this
      * when it is appropriate.
      * 
      * @param n
+     * @warn parameter "n" undescribed
      * @return the unwrapped value, which can be null
      */
     @SuppressWarnings("unchecked")
@@ -169,13 +188,13 @@ public T getValue(Object n) {
     }
 
     /**
-     * returns {@link Throwable} passed in {@link #error(Throwable)} method call. Bad things happen
-     * if you
-     * call this the onComplete or onNext notification type. For performance you are expected to use
-     * this when it is appropriate.
+     * Returns the {@link Throwable} passed to the {@link #error(Throwable)} method call. Bad things happen if
+     * you call this on the {@code onComplete} or {@code onNext} notification type. For performance you are
+     * expected to use this when it is appropriate.
      * 
      * @param n
-     * @return The {@link Throwable} wrapped inside n
+     * @warn parameter "n" undescribed
+     * @return the {@link Throwable} wrapped inside n
      */
     public Throwable getError(Object n) {
         return ((OnErrorSentinel) n).e;