Add javadoc comments to individual OperationFoo files

Author: DavidMGross

rxjava-core/src/main/java/rx/operators/OperationAll.java

@@ -12,6 +12,12 @@
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.verifyNoMoreInteractions;
 
+/**
+ * Returns an Observable that emits a Boolean that indicates whether all items emitted by an
+ * Observable satisfy a condition.
+ * <p>
+ * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/all.png">
+ */
 public class OperationAll {
 
     public static <T> Func1<Observer<Boolean>, Subscription> all(Observable<T> sequence, Func1<T, Boolean> predicate) {

rxjava-core/src/main/java/rx/operators/OperationCache.java

@@ -33,15 +33,17 @@
 import rx.util.functions.Func1;
 
 /**
- * Similar to {@link Observable#replay()} except that this auto-subscribes to the source sequence.
+ * This method has similar behavior to {@link Observable#replay()} except that this auto-subscribes
+ * to the source Observable rather than returning a connectable Observable.
  * <p>
- * This is useful when returning an Observable that you wish to cache responses but can't control the
+ * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/cache.png">
+ * <p>
+ * This is useful with an Observable that you want to cache responses when you can't control the
  * subscribe/unsubscribe behavior of all the Observers.
  * <p>
- * NOTE: You sacrifice the ability to unsubscribe from the origin with this operator so be careful to not
- * use this on infinite or very large sequences that will use up memory. This is similar to
- * the {@link Observable#toList()} operator in this caution.
- * 
+ * NOTE: You sacrifice the ability to unsubscribe from the origin when you use this operator, so be
+ * careful not to use this operator on Observables that emit infinite or very large numbers of
+ * items, as this will use up memory.
  */
 public class OperationCache {
 

rxjava-core/src/main/java/rx/operators/OperationConcat.java

@@ -40,6 +40,12 @@
 import rx.util.Exceptions;
 import rx.util.functions.Func1;
 
+/**
+ * Returns an Observable that emits the items emitted by two or more Observables, one after the
+ * other.
+ * <p>
+ * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/concat.png">
+ */
 public final class OperationConcat {
 
     /**
@@ -690,4 +696,4 @@ public void run() {
         }
 
     }
-}
+}

rxjava-core/src/main/java/rx/operators/OperationDematerialize.java

@@ -27,8 +27,13 @@
 import rx.util.functions.Func1;
 
 /**
- * Dematerializes the explicit notification values of an observable sequence as implicit notifications.
- * See <a href="http://msdn.microsoft.com/en-us/library/hh229047(v=vs.103).aspx">here</a> for the Microsoft Rx equivalent.
+ * Reverses the effect of {@link OperationMaterialize} by transforming the Notification objects
+ * emitted by a source Observable into the items or notifications they represent.
+ * <p>
+ * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/dematerialize.png">
+ * <p>
+ * See <a href="http://msdn.microsoft.com/en-us/library/hh229047(v=vs.103).aspx">here</a> for the
+ * Microsoft Rx equivalent.
  */
 public final class OperationDematerialize {
 

rxjava-core/src/main/java/rx/operators/OperationFilter.java

@@ -26,6 +26,11 @@
 import rx.Subscription;
 import rx.util.functions.Func1;
 
+/**
+ * Filters an Observable by discarding any items it emits that do not meet some test.
+ * <p>
+ * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/filter.png">
+ */
 public final class OperationFilter<T> {
 
     public static <T> Func1<Observer<T>, Subscription> filter(Observable<T> that, Func1<T, Boolean> predicate) {
@@ -92,4 +97,4 @@ public Boolean call(String t1) {
             verify(aObserver, times(1)).onCompleted();
         }
     }
-}
+}

rxjava-core/src/main/java/rx/operators/OperationFinally.java

@@ -26,6 +26,14 @@
 import rx.util.functions.Action0;
 import rx.util.functions.Func1;
 
+/**
+ * Registers an action to be called when an Observable invokes onComplete or onError.
+ * <p>
+ * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/finallyDo.png">
+ * <p>
+ * See also the <a href="http://msdn.microsoft.com/en-us/library/hh212133(v=vs.103).aspx">MSDN
+ * Observable.Finally method</a>
+ */
 public final class OperationFinally {
 
     /**

rxjava-core/src/main/java/rx/operators/OperationGroupBy.java

@@ -40,6 +40,12 @@
 import rx.util.functions.Func1;
 import rx.util.functions.Functions;
 
+/**
+ * Groups the items emitted by an Observable according to a specified criterion, and emits these
+ * grouped items as Observables, one Observable per group.
+ * <p>
+ * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/groupBy.png">
+ */
 public final class OperationGroupBy {
 
     public static <K, T, R> Func1<Observer<GroupedObservable<K, R>>, Subscription> groupBy(Observable<T> source, final Func1<T, K> keySelector, final Func1<T, R> elementSelector) {

rxjava-core/src/main/java/rx/operators/OperationMap.java

@@ -31,6 +31,12 @@
 import rx.Subscription;
 import rx.util.functions.Func1;
 
+/**
+ * Applies a function of your choosing to every item emitted by an Observable, and returns this
+ * transformation as a new Observable.
+ * <p>
+ * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/map.png">
+ */
 public final class OperationMap {
 
     /**

rxjava-core/src/main/java/rx/operators/OperationMaterialize.java

@@ -29,11 +29,13 @@
 import rx.util.functions.Func1;
 
 /**
- * Materializes the implicit notifications of an observable sequence as explicit notification values.
+ * Turns all of the notifications from an Observable into <code>onNext</code> emissions, and marks
+ * them with their original notification types within {@link Notification} objects.
  * <p>
- * In other words, converts a sequence of OnNext, OnError and OnCompleted events into a sequence of ObservableNotifications containing the OnNext, OnError and OnCompleted values.
+ * <img width="640" src="https://github.com/Netflix/RxJava/wiki/images/rx-operators/materialize.png">
  * <p>
- * See <a href="http://msdn.microsoft.com/en-us/library/hh229453(v=VS.103).aspx">here</a> for the Microsoft Rx equivalent.
+ * See <a href="http://msdn.microsoft.com/en-us/library/hh229453(v=VS.103).aspx">here</a> for the
+ * Microsoft Rx equivalent.
  */
 public final class OperationMaterialize {
 

rxjava-core/src/main/java/rx/operators/OperationMerge.java

@@ -37,6 +37,14 @@
 import rx.Subscription;
 import rx.util.functions.Func1;
 
+/**
+ * Flattens a list of Observables into one Observable sequence, without any transformation.
+ * <p>
+ * <img width="640" src="https://github.com/Netflix/RxJava/wiki/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.
+ */
 public final class OperationMerge {
 
     /**