Filling in javadoc gaps where I feel confident enough to do so...

Author: DavidMGross

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

@@ -36,9 +36,13 @@ private BlockingOperatorLatest() {
     }
 
     /**
-     * @warn latest() missing javadoc
+     * Returns an {@code Iterable} that blocks until or unless the {@code Observable} emits an item that has not
+     * been returned by the {@code Iterable}, then returns that item
+     *
      * @param source
-     * @return
+     *            the source {@code Observable}
+     * @return an {@code Iterable} that blocks until or unless the {@code Observable} emits an item that has not
+     *         been returned by the {@code Iterable}, then returns that item
      */
     public static <T> Iterable<T> latest(final Observable<? extends T> source) {
         return new Iterable<T>() {

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

@@ -30,10 +30,15 @@
 public final class BlockingOperatorMostRecent {
 
     /**
-     * @warn mostRecent() missing javadocs
+     * Returns an {@code Iterable} that always returns the item most recently emitted by the {@code Observable}.
+     *
      * @param source
+     *            the source {@code Observable}
      * @param initialValue
-     * @return
+     *            a default item to return from the {@code Iterable} if {@code source} has not yet emitted any
+     *            items
+     * @return an {@code Iterable} that always returns the item most recently emitted by {@code source}, or
+     *         {@code initialValue} if {@code source} has not yet emitted any items
      */
     public static <T> Iterable<T> mostRecent(final Observable<? extends T> source, final T initialValue) {
 

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

@@ -34,9 +34,12 @@
 public final class BlockingOperatorNext {
 
     /**
-     * @warn next() missing javadocs
+     * Returns an {@code Iterable} that blocks until the {@code Observable} emits another item, then returns
+     * that item.
+     *
      * @param items
-     * @return
+     *            the {@code Observable} to observe
+     * @return an {@code Iterable} that behaves like a blocking version of {@code items}
      */
     public static <T> Iterable<T> next(final Observable<? extends T> items) {
         return new Iterable<T>() {

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

@@ -46,13 +46,14 @@
  * {@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>
+ *            the type of the items to be buffered
  */
 public class BufferUntilSubscriber<T> extends Subject<T, T> {
 
     /**
      * @warn create() undescribed
+     * @return
      */
     public static <T> BufferUntilSubscriber<T> create() {
         State<T> state = new State<T>();

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

@@ -23,15 +23,16 @@
 /**
  * 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}.
- * 
+ * {@link rx.Notification} objects for every {@link Observer#onNext onNext} and
+ * {@link Observer#onCompleted onCompleted}.
+ * <p>
  * 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.
- * 
+ * <p>
  * 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
+ * @warn type param undescribed
  */
 public final class NotificationLite<T> {
     private NotificationLite() {
@@ -41,7 +42,9 @@ private NotificationLite() {
     private static final NotificationLite INSTANCE = new NotificationLite();
 
     /**
-     * @warn instance() undocumented
+     * Gets the {@code NotificationLite} singleton.
+     *
+     * @return the sole {@code NotificationLite} object
      */
     @SuppressWarnings("unchecked")
     public static <T> NotificationLite<T> instance() {
@@ -70,8 +73,8 @@ public OnErrorSentinel(Throwable e) {
      * be unwrapped and sent with the {@link #accept} method.
      * 
      * @param t
-     * @warn parameter "t" undescribed
-     * @return the value or a null token
+     *          the item emitted to {@code onNext}
+     * @return the item, or a null token representing the item if the item is {@code null}
      */
     public Object next(T t) {
         if (t == null)
@@ -81,23 +84,22 @@ public Object next(T t) {
     }
 
     /**
-     * Creates a lite {@code onComplete} notification without doing any allocation. Can be unwrapped and
+     * Creates a lite {@code onCompleted} notification without doing any allocation. Can be unwrapped and
      * sent with the {@link #accept} method.
      * 
-     * @return the completion token
+     * @return a completion token
      */
     public Object completed() {
         return ON_COMPLETED_SENTINEL;
     }
 
     /**
-     * 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
+     * Create a lite {@code onError} notification. This call creates 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
+     *           the {@code Throwable} in the {@code onError} notification
      * @return an object encapsulating the exception
      */
     public Object error(Throwable e) {
@@ -108,10 +110,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.
-     * @warn parameter "n" undescribed
+     *            the {@link Observer} to call {@code onNext}, {@code onCompleted}, or {@code onError}.
      * @param n
-     * @return true if {@code n} was a termination event
+     *            the lite notification
+     * @return {@code true} if {@code n} represents a termination event; {@code false} otherwise
      * @throws IllegalArgumentException
      *             if the notification is null.
      * @throws NullPointerException
@@ -138,28 +140,38 @@ public boolean accept(Observer<? super T> o, Object n) {
     }
 
     /**
-     * @warn isCompleted() undocumented
+     * Indicates whether or not the lite notification represents an {@code onCompleted} event.
+     *
+     * @param n
+     *            the lite notification
+     * @return {@code true} if {@code n} represents an {@code onCompleted} event; {@code false} otherwise
      */
     public boolean isCompleted(Object n) {
         return n == ON_COMPLETED_SENTINEL;
     }
 
     /**
-     * @warn isError() undocumented
+     * Indicates whether or not the lite notification represents an {@code onError} event.
+     *
+     * @param n
+     *            the lite notification
+     * @return {@code true} if {@code n} represents an {@code onError} event; {@code false} otherwise
      */
     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}.
+     * Indicates which variety a particular lite notification is. If you need something more complex than
+     * simply calling the right method on an {@link Observer} then you can use this method to get the
+     * {@link rx.Notification.Kind}.
      * 
      * @param n
-     * @warn parameter "n" undescribed
+     *            the lite notification
      * @throws IllegalArgumentException
      *             if the notification is null.
-     * @return the kind of the raw object
+     * @return the {@link Kind} of lite notification {@code n} is: either {@code Kind.OnCompleted},
+     *         {@code Kind.OnError}, or {@code Kind.OnNext}
      */
     public Kind kind(Object n) {
         if (n == null)
@@ -174,12 +186,12 @@ else if (n instanceof OnErrorSentinel)
     }
 
     /**
-     * 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.
+     * Returns the item corresponding to this {@code OnNext} lite notification. Bad things happen if you pass
+     * this an {@code OnComplete} or {@code OnError} notification type. For performance reasons, this method
+     * does not check for this, so you are expected to prevent such a mishap.
      * 
      * @param n
-     * @warn parameter "n" undescribed
+     *            the lite notification (of type {@code Kind.OnNext})
      * @return the unwrapped value, which can be null
      */
     @SuppressWarnings("unchecked")
@@ -188,13 +200,13 @@ public T getValue(Object n) {
     }
 
     /**
-     * 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.
+     * Returns the {@link Throwable} corresponding to this {@code OnError} lite notification. Bad things happen
+     * if you pass this an {@code OnComplete} or {@code OnNext} notification type. For performance reasons, this
+     * method does not check for this, so you are expected to prevent such a mishap.
      * 
      * @param n
-     * @warn parameter "n" undescribed
-     * @return the {@link Throwable} wrapped inside n
+     *            the lite notification (of type {@code Kind.OnError})
+     * @return the {@link Throwable} wrapped inside {@code n}
      */
     public Throwable getError(Object n) {
         return ((OnErrorSentinel) n).e;