diff --git a/rxjava-core/src/main/java/rx/internal/operators/BlockingOperatorLatest.java b/rxjava-core/src/main/java/rx/internal/operators/BlockingOperatorLatest.java
index 69b8608eca..9daa398e31 100644
--- a/rxjava-core/src/main/java/rx/internal/operators/BlockingOperatorLatest.java
+++ b/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>() {
diff --git a/rxjava-core/src/main/java/rx/internal/operators/BlockingOperatorMostRecent.java b/rxjava-core/src/main/java/rx/internal/operators/BlockingOperatorMostRecent.java
index debc9afd28..c1628d3d9f 100644
--- a/rxjava-core/src/main/java/rx/internal/operators/BlockingOperatorMostRecent.java
+++ b/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) {
 
diff --git a/rxjava-core/src/main/java/rx/internal/operators/BlockingOperatorNext.java b/rxjava-core/src/main/java/rx/internal/operators/BlockingOperatorNext.java
index 7c6c3ffd1c..5343b3a711 100644
--- a/rxjava-core/src/main/java/rx/internal/operators/BlockingOperatorNext.java
+++ b/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>() {
diff --git a/rxjava-core/src/main/java/rx/internal/operators/BufferUntilSubscriber.java b/rxjava-core/src/main/java/rx/internal/operators/BufferUntilSubscriber.java
index 39ea385e18..4a2a6b66e7 100644
--- a/rxjava-core/src/main/java/rx/internal/operators/BufferUntilSubscriber.java
+++ b/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>();
diff --git a/rxjava-core/src/main/java/rx/internal/operators/NotificationLite.java b/rxjava-core/src/main/java/rx/internal/operators/NotificationLite.java
index ffe822b6e0..140073a284 100644
--- a/rxjava-core/src/main/java/rx/internal/operators/NotificationLite.java
+++ b/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;
diff --git a/rxjava-core/src/main/java/rx/internal/operators/OnSubscribeAmb.java b/rxjava-core/src/main/java/rx/internal/operators/OnSubscribeAmb.java
index 50a8f67c17..2d52ff9af0 100644
--- a/rxjava-core/src/main/java/rx/internal/operators/OnSubscribeAmb.java
+++ b/rxjava-core/src/main/java/rx/internal/operators/OnSubscribeAmb.java
@@ -24,15 +24,19 @@
 import rx.Subscriber;
 
 /**
- * Propagates the observable sequence that reacts first.
+ * Given multiple {@link Observable}s, propagates the one that first emits an item.
  */
 public final class OnSubscribeAmb<T> implements OnSubscribe<T>{
 
     /**
-     * @warn javadoc missing
+     * Given two {@link Observable}s, propagates the one that first emits an item.
+     *
      * @param o1
+     *          the first {@code Observable}
      * @param o2
-     * @return
+     *          the second {@code Observable}
+     * @return an {@code Observable} that mirrors the one of the source {@code Observable}s that was first to
+     *         emit an item
      */
     public static <T> OnSubscribe<T> amb(Observable<? extends T> o1, Observable<? extends T> o2) {
         List<Observable<? extends T>> sources = new ArrayList<Observable<? extends T>>();
@@ -42,11 +46,16 @@ public static <T> OnSubscribe<T> amb(Observable<? extends T> o1, Observable<? ex
     }
 
     /**
-     * @warn javadoc missing
+     * Given three {@link Observable}s, propagates the one that first emits an item.
+     *
      * @param o1
+     *          the first {@code Observable}
      * @param o2
+     *          the second {@code Observable}
      * @param o3
-     * @return
+     *          the third {@code Observable}
+     * @return an {@code Observable} that mirrors the one of the source {@code Observable}s that was first to
+     *         emit an item
      */
     public static <T> OnSubscribe<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3) {
         List<Observable<? extends T>> sources = new ArrayList<Observable<? extends T>>();
@@ -57,12 +66,18 @@ public static <T> OnSubscribe<T> amb(Observable<? extends T> o1, Observable<? ex
     }
 
     /**
-     * @warn javadoc missing
+     * Given four {@link Observable}s, propagates the one that first emits an item.
+     *
      * @param o1
+     *          the first {@code Observable}
      * @param o2
+     *          the second {@code Observable}
      * @param o3
+     *          the third {@code Observable}
      * @param o4
-     * @return
+     *          the fourth {@code Observable}
+     * @return an {@code Observable} that mirrors the one of the source {@code Observable}s that was first to
+     *         emit an item
      */
     public static <T> OnSubscribe<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3, Observable<? extends T> o4) {
         List<Observable<? extends T>> sources = new ArrayList<Observable<? extends T>>();
@@ -74,13 +89,20 @@ public static <T> OnSubscribe<T> amb(Observable<? extends T> o1, Observable<? ex
     }
 
     /**
-     * @warn javadoc missing
+     * Given five {@link Observable}s, propagates the one that first emits an item.
+     *
      * @param o1
+     *          the first {@code Observable}
      * @param o2
+     *          the second {@code Observable}
      * @param o3
+     *          the third {@code Observable}
      * @param o4
+     *          the fourth {@code Observable}
      * @param o5
-     * @return
+     *          the fifth {@code Observable}
+     * @return an {@code Observable} that mirrors the one of the source {@code Observable}s that was first to
+     *         emit an item
      */
     public static <T> OnSubscribe<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3, Observable<? extends T> o4, Observable<? extends T> o5) {
         List<Observable<? extends T>> sources = new ArrayList<Observable<? extends T>>();
@@ -93,14 +115,22 @@ public static <T> OnSubscribe<T> amb(Observable<? extends T> o1, Observable<? ex
     }
 
     /**
-     * @warn javadoc missing
+     * Given six {@link Observable}s, propagates the one that first emits an item.
+     *
      * @param o1
+     *          the first {@code Observable}
      * @param o2
+     *          the second {@code Observable}
      * @param o3
+     *          the third {@code Observable}
      * @param o4
+     *          the fourth {@code Observable}
      * @param o5
+     *          the fifth {@code Observable}
      * @param o6
-     * @return
+     *          the sixth {@code Observable}
+     * @return an {@code Observable} that mirrors the one of the source {@code Observable}s that was first to
+     *         emit an item
      */
     public static <T> OnSubscribe<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3, Observable<? extends T> o4, Observable<? extends T> o5, Observable<? extends T> o6) {
         List<Observable<? extends T>> sources = new ArrayList<Observable<? extends T>>();
@@ -114,15 +144,24 @@ public static <T> OnSubscribe<T> amb(Observable<? extends T> o1, Observable<? ex
     }
 
     /**
-     * @warn javadoc missing
+     * Given seven {@link Observable}s, propagates the one that first emits an item.
+     *
      * @param o1
+     *          the first {@code Observable}
      * @param o2
+     *          the second {@code Observable}
      * @param o3
+     *          the third {@code Observable}
      * @param o4
+     *          the fourth {@code Observable}
      * @param o5
+     *          the fifth {@code Observable}
      * @param o6
+     *          the sixth {@code Observable}
      * @param o7
-     * @return
+     *          the seventh {@code Observable}
+     * @return an {@code Observable} that mirrors the one of the source {@code Observable}s that was first to
+     *         emit an item
      */
     public static <T> OnSubscribe<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3, Observable<? extends T> o4, Observable<? extends T> o5, Observable<? extends T> o6, Observable<? extends T> o7) {
         List<Observable<? extends T>> sources = new ArrayList<Observable<? extends T>>();
@@ -137,16 +176,26 @@ public static <T> OnSubscribe<T> amb(Observable<? extends T> o1, Observable<? ex
     }
 
     /**
-     * @warn javadoc missing
+     * Given eight {@link Observable}s, propagates the one that first emits an item.
+     *
      * @param o1
+     *          the first {@code Observable}
      * @param o2
+     *          the second {@code Observable}
      * @param o3
+     *          the third {@code Observable}
      * @param o4
+     *          the fourth {@code Observable}
      * @param o5
+     *          the fifth {@code Observable}
      * @param o6
+     *          the sixth {@code Observable}
      * @param o7
+     *          the seventh {@code Observable}
      * @param o8
-     * @return
+     *          the eighth {@code Observable}
+     * @return an {@code Observable} that mirrors the one of the source {@code Observable}s that was first to
+     *         emit an item
      */
     public static <T> OnSubscribe<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3, Observable<? extends T> o4, Observable<? extends T> o5, Observable<? extends T> o6, Observable<? extends T> o7, Observable<? extends T> o8) {
         List<Observable<? extends T>> sources = new ArrayList<Observable<? extends T>>();
@@ -162,17 +211,28 @@ public static <T> OnSubscribe<T> amb(Observable<? extends T> o1, Observable<? ex
     }
 
     /**
-     * @warn javadoc missing
+     * Given nine {@link Observable}s, propagates the one that first emits an item.
+     *
      * @param o1
+     *          the first {@code Observable}
      * @param o2
+     *          the second {@code Observable}
      * @param o3
+     *          the third {@code Observable}
      * @param o4
+     *          the fourth {@code Observable}
      * @param o5
+     *          the fifth {@code Observable}
      * @param o6
+     *          the sixth {@code Observable}
      * @param o7
+     *          the seventh {@code Observable}
      * @param o8
+     *          the eighth {@code Observable}
      * @param o9
-     * @return
+     *          the ninth {@code Observable}
+     * @return an {@code Observable} that mirrors the one of the source {@code Observable}s that was first to
+     *         emit an item
      */
     public static <T> OnSubscribe<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3, Observable<? extends T> o4, Observable<? extends T> o5, Observable<? extends T> o6, Observable<? extends T> o7, Observable<? extends T> o8, Observable<? extends T> o9) {
         List<Observable<? extends T>> sources = new ArrayList<Observable<? extends T>>();
@@ -189,9 +249,12 @@ public static <T> OnSubscribe<T> amb(Observable<? extends T> o1, Observable<? ex
     }
 
     /**
-     * @warn javadoc missing
+     * Given a set of {@link Observable}s, propagates the one that first emits an item.
+     *
      * @param sources
-     * @return
+     *          an {@code Iterable} of {@code Observable}s
+     * @return an {@code Observable} that mirrors the one of the {@code Observable}s in {@code sources} that was
+     *         the first to emit an item
      */
     public static <T> OnSubscribe<T> amb(final Iterable<? extends Observable<? extends T>> sources) {
         return new OnSubscribeAmb<T>(sources);
diff --git a/rxjava-core/src/main/java/rx/internal/operators/OnSubscribeToObservableFuture.java b/rxjava-core/src/main/java/rx/internal/operators/OnSubscribeToObservableFuture.java
index e080d0e618..1c21a1b534 100644
--- a/rxjava-core/src/main/java/rx/internal/operators/OnSubscribeToObservableFuture.java
+++ b/rxjava-core/src/main/java/rx/internal/operators/OnSubscribeToObservableFuture.java
@@ -24,15 +24,15 @@
 import rx.subscriptions.Subscriptions;
 
 /**
- * Converts a Future into an Observable.
+ * Converts a {@code Future} into an {@code Observable}.
  * <p>
  * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/from.Future.png">
  * <p>
- * You can convert any object that supports the Future interface into an Observable that emits the
- * return value of the get() method of that object, by using the from operation.
+ * You can convert any object that supports the {@code Future} interface into an {@code Observable} that emits
+ * the return value of the {@code get} method of that object, by using this operator.
  * <p>
- * This is blocking so the Subscription returned when calling
- * <code>Observable.unsafeSubscribe(Observer)</code> does nothing.
+ * This is blocking so the {@code Subscription} returned when calling
+ * {@code Observable.unsafeSubscribe(Observer)} does nothing.
  */
 public class OnSubscribeToObservableFuture {
     /* package accessible for unit tests */static class ToObservableFuture<T> implements OnSubscribe<T> {
@@ -40,24 +40,12 @@ public class OnSubscribeToObservableFuture {
         private final long time;
         private final TimeUnit unit;
 
-        /**
-         * @warn javadoc missing
-         * @param that
-         * @return
-         */
         public ToObservableFuture(Future<? extends T> that) {
             this.that = that;
             this.time = 0;
             this.unit = null;
         }
 
-        /**
-         * @warn javadoc missing
-         * @param that
-         * @param time
-         * @param unit
-         * @return
-         */
         public ToObservableFuture(Future<? extends T> that, long time, TimeUnit unit) {
             this.that = that;
             this.time = time;
diff --git a/rxjava-core/src/main/java/rx/internal/operators/OperatorMap.java b/rxjava-core/src/main/java/rx/internal/operators/OperatorMap.java
index ec90f3bdec..5327ef47f4 100644
--- a/rxjava-core/src/main/java/rx/internal/operators/OperatorMap.java
+++ b/rxjava-core/src/main/java/rx/internal/operators/OperatorMap.java
@@ -21,8 +21,8 @@
 import rx.functions.Func1;
 
 /**
- * Applies a function of your choosing to every item emitted by an Observable, and returns this
- * transformation as a new Observable.
+ * Applies a function of your choosing to every item emitted by an {@code Observable}, and emits the results of
+ * this transformation as a new {@code Observable}.
  * <p>
  * <img width="640" height="305" src="https://raw.githubusercontent.com/wiki/Netflix/RxJava/images/rx-operators/map.png">
  */
diff --git a/rxjava-core/src/main/java/rx/internal/operators/OperatorMerge.java b/rxjava-core/src/main/java/rx/internal/operators/OperatorMerge.java
index 3c9eaa0f58..b1d150be46 100644
--- a/rxjava-core/src/main/java/rx/internal/operators/OperatorMerge.java
+++ b/rxjava-core/src/main/java/rx/internal/operators/OperatorMerge.java
@@ -24,14 +24,14 @@
 import rx.subscriptions.CompositeSubscription;
 
 /**
- * Flattens a list of Observables into one Observable sequence, without any transformation.
+ * Flattens a list of {@link Observable}s into one {@code Observable}, without any transformation.
  * <p>
  * <img width="640" height="380" src="https://raw.githubusercontent.com/wiki/Netflix/RxJava/images/rx-operators/merge.png">
  * <p>
- * You can combine the items emitted by multiple Observables so that they act like a single
- * Observable, by using the merge operation.
+ * You can combine the items emitted by multiple {@code Observable}s so that they act like a single
+ * {@code Observable}, by using the merge operation.
  * 
- * @param <T> the source and merged value type
+ * @param <T> the type of the items emitted by both the source and merged {@code Observable}s
  */
 public final class OperatorMerge<T> implements Operator<T, Observable<? extends T>> {
 
diff --git a/rxjava-core/src/main/java/rx/internal/operators/OperatorMergeMapPair.java b/rxjava-core/src/main/java/rx/internal/operators/OperatorMergeMapPair.java
index 59b57fd672..47b39dddc6 100644
--- a/rxjava-core/src/main/java/rx/internal/operators/OperatorMergeMapPair.java
+++ b/rxjava-core/src/main/java/rx/internal/operators/OperatorMergeMapPair.java
@@ -25,19 +25,24 @@
 import rx.subscriptions.CompositeSubscription;
 
 /**
- * Observable that pairs up the source values and all the derived collection values and projects them via the
- * selector.
+ * An {@link Operator} that pairs up items emitted by a source {@link Observable} with the sequence of items
+ * emitted by the {@code Observable} that is derived from each item by means of a selector, and emits the
+ * results of this pairing.
  *
- * @param <T> the input value type
- * @param <U> the derived collection value type
- * @param <R> the result type
+ * @param <T> the type of items emitted by the source {@code Observable}
+ * @param <U> the type of items emitted by the derived {@code Observable}s
+ * @param <R> the type of items to be emitted by this {@code Operator}
  */
 public final class OperatorMergeMapPair<T, U, R> implements Operator<R, T> {
 
     /**
-     * @warn javadoc missing
+     * Creates the function that generates a {@code Observable} based on an item emitted by another
+     * {@code Observable}.
+     * 
      * @param selector
-     * @return
+     *          a function that accepts an item and returns an {@code Iterable} of corresponding items
+     * @return a function that converts an item emitted by the source {@code Observable} into an
+     *         {@code Observable} that emits the items generated by {@code selector} operating on that item
      */
     public static <T, U> Func1<T, Observable<U>> convertSelector(final Func1<? super T, ? extends Iterable<? extends U>> selector) {
         return new Func1<T, Observable<U>>() {
@@ -50,7 +55,7 @@ public Observable<U> call(T t1) {
     
     final Func1<? super T, ? extends Observable<? extends U>> collectionSelector;
     final Func2<? super T, ? super U, ? extends R> resultSelector;
-    
+
     public OperatorMergeMapPair(Func1<? super T, ? extends Observable<? extends U>> collectionSelector,
             Func2<? super T, ? super U, ? extends R> resultSelector) {
         this.collectionSelector = collectionSelector;
@@ -65,6 +70,7 @@ public Subscriber<? super T> call(Subscriber<? super R> child) {
      
         return new SourceSubscriber<T, U, R>(s, csub, collectionSelector, resultSelector);
     }
+
     static final class SourceSubscriber<T, U, R> extends Subscriber<T> {
         final Subscriber<R> s;
         final CompositeSubscription csub;
diff --git a/rxjava-core/src/main/java/rx/internal/operators/OperatorParallelMerge.java b/rxjava-core/src/main/java/rx/internal/operators/OperatorParallelMerge.java
index 7adc4d5108..618c3658d1 100644
--- a/rxjava-core/src/main/java/rx/internal/operators/OperatorParallelMerge.java
+++ b/rxjava-core/src/main/java/rx/internal/operators/OperatorParallelMerge.java
@@ -23,25 +23,44 @@
 import rx.observables.GroupedObservable;
 import rx.schedulers.Schedulers;
 
+/**
+ * Combines multiple {@link Observable}s into a smaller number of {@code Observable}s, to facilitate
+ * parallelism.
+ */
 public final class OperatorParallelMerge {
     private OperatorParallelMerge() { throw new IllegalStateException("No instances!"); }
 
     /**
-     * @warn javadoc missing
+     * Recombines multiple {@link Observable}s into a smaller number of {@code Observable}s, to facilitate
+     * parallelism.
+     *
      * @param source
+     *          the source {@code Observable} that emits the {@code Observable}s to recombine
      * @param parallelObservables
-     * @return
+     *          the number of {@code Observable}s you want the source sequence of {@code Observables} to be
+     *          recombined into
+     * @return an {@code Observable} that emits no more than {@code parallelObservables} {@code Observable}s,
+     *         the set of which emits the same set of items emitted by the sequence of {@code Observable}s
+     *         emitted by {@code source}
      */
     public static <T> Observable<Observable<T>> parallelMerge(final Observable<Observable<T>> source, final int parallelObservables) {
         return parallelMerge(source, parallelObservables, Schedulers.immediate());
     }
 
     /**
-     * @warn javadoc missing
+     * Recombines multiple {@link Observable}s into a smaller number of {@code Observable}s on a particular
+     * {@code Scheduler}, to facilitate parallelism.
+     *
      * @param source
+     *          the source {@code Observable} that emits the {@code Observable}s to recombine
      * @param parallelObservables
+     *          the number of {@code Observable}s you want the source sequence of {@code Observables} to be
+     *          recombined into
      * @param scheduler
-     * @return
+     *          the {@link Scheduler} to do the work on
+     * @return an {@code Observable} that emits no more than {@code parallelObservables} {@code Observable}s,
+     *         the set of which emits the same set of items emitted by the sequence of {@code Observable}s
+     *         emitted by {@code source}
      */
     public static <T> Observable<Observable<T>> parallelMerge(final Observable<Observable<T>> source, final int parallelObservables, final Scheduler scheduler) {
 
@@ -55,6 +74,7 @@ public Observable<T> call(GroupedObservable<Integer, Observable<T>> o) {
 
         });
     }
+
     /** Maps source observables in a round-robin fashion to streaming groups. */
     static final class StrideMapper<T> implements Func1<Observable<T>, Integer> {
         final int parallelObservables;
diff --git a/rxjava-core/src/main/java/rx/internal/operators/OperatorSequenceEqual.java b/rxjava-core/src/main/java/rx/internal/operators/OperatorSequenceEqual.java
index a26a21024c..8165d4c2b8 100644
--- a/rxjava-core/src/main/java/rx/internal/operators/OperatorSequenceEqual.java
+++ b/rxjava-core/src/main/java/rx/internal/operators/OperatorSequenceEqual.java
@@ -24,11 +24,14 @@
 import rx.functions.Functions;
 
 /**
- * Returns an Observable that emits a Boolean value that indicate whether two sequences are equal by comparing
- * the elements pairwise.
+ * Returns an {@link Observable} that emits a single {@code Boolean} value that indicates whether two source
+ * {@code Observable}s emit sequences of items that are equivalent to each other.
  */
 public final class OperatorSequenceEqual {
-    private OperatorSequenceEqual() { throw new IllegalStateException("No instances!"); }
+    private OperatorSequenceEqual() {
+        throw new IllegalStateException("No instances!");
+    }
+
     /** NotificationLite doesn't work as zip uses it. */
     private static final Object LOCAL_ONCOMPLETED = new Object();
     static <T> Observable<Object> materializeLite(Observable<T> source) {
@@ -44,11 +47,18 @@ public Object call(T t1) {
     }
 
     /**
-     * @warn javadoc missing
+     * Tests whether two {@code Observable} sequences are identical, emitting {@code true} if both sequences
+     * complete without differing, and {@code false} if the two sequences diverge at any point.
+     *
      * @param first
+     *      the first of the two {@code Observable}s to compare
      * @param second
+     *      the second of the two {@code Observable}s to compare
      * @param equality
-     * @return
+     *      a function that tests emissions from each {@code Observable} for equality
+     * @return an {@code Observable} that emits {@code true} if {@code first} and {@code second} complete
+     *         after emitting equal sequences of items, {@code false} if at any point in their sequences the
+     *         two {@code Observable}s emit a non-equal item.
      */
     public static <T> Observable<Boolean> sequenceEqual(
             Observable<? extends T> first, Observable<? extends T> second,
diff --git a/rxjava-core/src/main/java/rx/internal/operators/OperatorTake.java b/rxjava-core/src/main/java/rx/internal/operators/OperatorTake.java
index f68d3cd523..450d8bd002 100644
--- a/rxjava-core/src/main/java/rx/internal/operators/OperatorTake.java
+++ b/rxjava-core/src/main/java/rx/internal/operators/OperatorTake.java
@@ -19,13 +19,14 @@
 import rx.Subscriber;
 
 /**
- * Returns an Observable that emits the first <code>num</code> items emitted by the source Observable.
+ * An {@code Observable} that emits the first {@code num} items emitted by the source {@code Observable}.
  * <p>
  * <img width="640" height="305" src="https://raw.githubusercontent.com/wiki/Netflix/RxJava/images/rx-operators/take.png" />
  * <p>
- * You can choose to pay attention only to the first <code>num</code> items emitted by an Observable by using
- * the {@code take} operation. This operation returns an Observable that will invoke a subscribing Observer's
- * {@code onNext} function a maximum of {@code num} times before invoking {@code onCompleted}.
+ * You can choose to pay attention only to the first {@code num} items emitted by an {@code Observable} by using
+ * the {@code take} operator. This operator returns an {@code Observable} that will invoke a subscriber's
+ * {@link Subscriber#onNext onNext} function a maximum of {@code num} times before invoking
+ * {@link Subscriber#onCompleted onCompleted}.
  */
 public final class OperatorTake<T> implements Operator<T, T> {
 
diff --git a/rxjava-core/src/main/java/rx/internal/operators/OperatorTimestamp.java b/rxjava-core/src/main/java/rx/internal/operators/OperatorTimestamp.java
index 12d6634652..153e2b5fbf 100644
--- a/rxjava-core/src/main/java/rx/internal/operators/OperatorTimestamp.java
+++ b/rxjava-core/src/main/java/rx/internal/operators/OperatorTimestamp.java
@@ -21,7 +21,7 @@
 import rx.schedulers.Timestamped;
 
 /**
- * Wraps each item emitted by a source Observable in a {@link Timestamped} object.
+ * Wraps each item emitted by a source {@code Observable} in a {@link Timestamped} object.
  * <p>
  * <img width="640" height="310" src="https://raw.githubusercontent.com/wiki/Netflix/RxJava/images/rx-operators/timestamp.png">
  */
diff --git a/rxjava-core/src/main/java/rx/internal/operators/OperatorToObservableList.java b/rxjava-core/src/main/java/rx/internal/operators/OperatorToObservableList.java
index 7c2e4bb1b9..4fb9e30bd4 100644
--- a/rxjava-core/src/main/java/rx/internal/operators/OperatorToObservableList.java
+++ b/rxjava-core/src/main/java/rx/internal/operators/OperatorToObservableList.java
@@ -23,18 +23,18 @@
 import java.util.List;
 
 /**
- * Returns an Observable that emits a single item, a list composed of all the items emitted by the source
- * Observable.
+ * Returns an {@code Observable} that emits a single item, a list composed of all the items emitted by the
+ * source {@code Observable}.
  * <p>
  * <img width="640" height="305" src="https://raw.githubusercontent.com/wiki/Netflix/RxJava/images/rx-operators/toList.png">
  * <p>
- * Normally, an Observable that returns multiple items will do so by invoking its Observer's {@code onNext}
- * method for each such item. You can change this behavior, instructing the Observable to compose a list of all
- * of these multiple items and then to invoke the Observer's {@code onNext} method once, passing it the entire
- * list, by using the toList Observer.
+ * Normally, an {@code Observable} that returns multiple items will do so by invoking its subscriber's
+ * {@link Subscriber#onNext onNext} method for each such item. You can change this behavior, instructing the
+ * {@code Observable} to compose a list of all of these multiple items and then to invoke the subscriber's
+ * {@code onNext} method once, passing it the entire list, by using this operator.
  * <p>
- * Be careful not to use this Observer on Observables that emit infinite or very large numbers of items, as you
- * do not have the option to unsubscribe.
+ * Be careful not to use this operator on {@code Observable}s that emit infinite or very large numbers of items,
+ * as you do not have the option to unsubscribe.
  */
 public final class OperatorToObservableList<T> implements Operator<List<T>, T> {
 
diff --git a/rxjava-core/src/main/java/rx/internal/operators/OperatorToObservableSortedList.java b/rxjava-core/src/main/java/rx/internal/operators/OperatorToObservableSortedList.java
index 81fe6cd832..7b2625dea3 100644
--- a/rxjava-core/src/main/java/rx/internal/operators/OperatorToObservableSortedList.java
+++ b/rxjava-core/src/main/java/rx/internal/operators/OperatorToObservableSortedList.java
@@ -25,14 +25,14 @@
 import rx.functions.Func2;
 
 /**
- * Return an Observable that emits the items emitted by the source Observable, in a sorted order (each item
- * emitted by the Observable must implement Comparable with respect to all other items in the sequence, or you
- * must pass in a sort function).
+ * Return an {@code Observable} that emits the items emitted by the source {@code Observable}, in a sorted order
+ * (each item emitted by the {@code Observable} must implement {@link Comparable} with respect to all other
+ * items in the sequence, or you must pass in a sort function).
  * <p>
  * <img width="640" height="310" src="https://raw.githubusercontent.com/wiki/Netflix/RxJava/images/rx-operators/toSortedList.png">
  * 
- * @warn type param not described
  * @param <T>
+ *          the type of the items emitted by the source and the resulting {@code Observable}s
  */
 public final class OperatorToObservableSortedList<T> implements Operator<List<T>, T> {
     private final Func2<? super T, ? super T, Integer> sortFunction;
diff --git a/rxjava-core/src/main/java/rx/internal/schedulers/ScheduledAction.java b/rxjava-core/src/main/java/rx/internal/schedulers/ScheduledAction.java
index 9469a5f4b5..f9fe694400 100644
--- a/rxjava-core/src/main/java/rx/internal/schedulers/ScheduledAction.java
+++ b/rxjava-core/src/main/java/rx/internal/schedulers/ScheduledAction.java
@@ -60,18 +60,20 @@ public void unsubscribe() {
 
     /**
      * @warn javadoc missing
+     *
      * @param s
+     * @warn param "s" undescribed
      */
     public void add(Subscription s) {
         cancel.add(s);
     }
 
     /**
-     * Adds a parent to this ScheduledAction so when it is cancelled or terminates, it can remove itself from
-     * this parent.
+     * Adds a parent {@link CompositeSubscription} to this {@code ScheduledAction} so when the action is
+     * cancelled or terminates, it can remove itself from this parent.
      *
-     * @warn param "parent" undescribed
      * @param parent
+     *            the parent {@code CompositeSubscription} to add
      */
     public void addParent(CompositeSubscription parent) {
         cancel.add(new Remover(this, parent));