Correcting javadocs for the amb/ambWith operators

Author: DavidMGross

src/main/java/rx/Observable.java

@@ -205,7 +205,8 @@ public static interface Transformer<T, R> extends Func1<Observable<T>, Observabl
      */
 
     /**
-     * Mirrors the one Observable in an Iterable of several Observables that first emits an item.
+     * Mirrors the one Observable in an Iterable of several Observables that first either emits an item or sends
+     * a termination notification.
      * <p>
      * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
      * <dl>
@@ -215,16 +216,17 @@ public static interface Transformer<T, R> extends Func1<Observable<T>, Observabl
      * 
      * @param sources
      *            an Iterable of Observable sources competing to react first
-     * @return an Observable that emits the same sequence of items as whichever of the source Observables first
-     *         emitted an item
+     * @return an Observable that emits the same sequence as whichever of the source Observables first
+     *         emitted an item or sent a termination notification
      * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
      */
     public final static <T> Observable<T> amb(Iterable<? extends Observable<? extends T>> sources) {
         return create(OnSubscribeAmb.amb(sources));
     }
 
     /**
-     * Given two Observables, mirrors the one that first emits an item.
+     * Given two Observables, mirrors the one that first either emits an item or sends a termination
+     * notification.
      * <p>
      * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
      * <dl>
@@ -236,16 +238,17 @@ public final static <T> Observable<T> amb(Iterable<? extends Observable<? extend
      *            an Observable competing to react first
      * @param o2
      *            an Observable competing to react first
-     * @return an Observable that emits the same sequence of items as whichever of the source Observables first
-     *         emitted an item
+     * @return an Observable that emits the same sequence as whichever of the source Observables first
+     *         emitted an item or sent a termination notification
      * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
      */
     public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable<? extends T> o2) {
         return create(OnSubscribeAmb.amb(o1, o2));
     }
 
     /**
-     * Given three Observables, mirrors the one that first emits an item.
+     * Given three Observables, mirrors the one that first either emits an item or sends a termination
+     * notification.
      * <p>
      * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
      * <dl>
@@ -259,16 +262,17 @@ public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable
      *            an Observable competing to react first
      * @param o3
      *            an Observable competing to react first
-     * @return an Observable that emits the same sequence of items as whichever of the source Observables first
-     *         emitted an item
+     * @return an Observable that emits the same sequence as whichever of the source Observables first
+     *         emitted an item or sent a termination notification
      * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
      */
     public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3) {
         return create(OnSubscribeAmb.amb(o1, o2, o3));
     }
 
     /**
-     * Given four Observables, mirrors the one that first emits an item.
+     * Given four Observables, mirrors the one that first either emits an item or sends a termination
+     * notification.
      * <p>
      * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
      * <dl>
@@ -284,16 +288,17 @@ public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable
      *            an Observable competing to react first
      * @param o4
      *            an Observable competing to react first
-     * @return an Observable that emits the same sequence of items as whichever of the source Observables first
-     *         emitted an item
+     * @return an Observable that emits the same sequence as whichever of the source Observables first
+     *         emitted an item or sent a termination notification
      * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
      */
     public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3, Observable<? extends T> o4) {
         return create(OnSubscribeAmb.amb(o1, o2, o3, o4));
     }
 
     /**
-     * Given five Observables, mirrors the one that first emits an item.
+     * Given five Observables, mirrors the one that first either emits an item or sends a termination
+     * notification.
      * <p>
      * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
      * <dl>
@@ -311,16 +316,17 @@ public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable
      *            an Observable competing to react first
      * @param o5
      *            an Observable competing to react first
-     * @return an Observable that emits the same sequence of items as whichever of the source Observables first
-     *         emitted an item
+     * @return an Observable that emits the same sequence as whichever of the source Observables first
+     *         emitted an item or sent a termination notification
      * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
      */
     public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable<? extends T> o2, Observable<? extends T> o3, Observable<? extends T> o4, Observable<? extends T> o5) {
         return create(OnSubscribeAmb.amb(o1, o2, o3, o4, o5));
     }
 
     /**
-     * Given six Observables, mirrors the one that first emits an item.
+     * Given six Observables, mirrors the one that first either emits an item or sends a termination
+     * notification.
      * <p>
      * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
      * <dl>
@@ -340,16 +346,17 @@ public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable
      *            an Observable competing to react first
      * @param o6
      *            an Observable competing to react first
-     * @return an Observable that emits the same sequence of items as whichever of the source Observables first
-     *         emitted an item
+     * @return an Observable that emits the same sequence as whichever of the source Observables first
+     *         emitted an item or sent a termination notification
      * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
      */
     public final static <T> Observable<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) {
         return create(OnSubscribeAmb.amb(o1, o2, o3, o4, o5, o6));
     }
 
     /**
-     * Given seven Observables, mirrors the one that first emits an item.
+     * Given seven Observables, mirrors the one that first either emits an item or sends a termination
+     * notification.
      * <p>
      * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
      * <dl>
@@ -371,16 +378,17 @@ public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable
      *            an Observable competing to react first
      * @param o7
      *            an Observable competing to react first
-     * @return an Observable that emits the same sequence of items as whichever of the source Observables first
-     *         emitted an item
+     * @return an Observable that emits the same sequence as whichever of the source Observables first
+     *         emitted an item or sent a termination notification
      * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
      */
     public final static <T> Observable<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) {
         return create(OnSubscribeAmb.amb(o1, o2, o3, o4, o5, o6, o7));
     }
 
     /**
-     * Given eight Observables, mirrors the one that first emits an item.
+     * Given eight Observables, mirrors the one that first either emits an item or sends a termination
+     * notification.
      * <p>
      * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
      * <dl>
@@ -404,16 +412,17 @@ public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable
      *            an Observable competing to react first
      * @param o8
      *            an observable competing to react first
-     * @return an Observable that emits the same sequence of items as whichever of the source Observables first
-     *         emitted an item
+     * @return an Observable that emits the same sequence as whichever of the source Observables first
+     *         emitted an item or sent a termination notification
      * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
      */
     public final static <T> Observable<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) {
         return create(OnSubscribeAmb.amb(o1, o2, o3, o4, o5, o6, o7, o8));
     }
 
     /**
-     * Given nine Observables, mirrors the one that first emits an item.
+     * Given nine Observables, mirrors the one that first either emits an item or sends a termination
+     * notification.
      * <p>
      * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
      * <dl>
@@ -439,8 +448,8 @@ public final static <T> Observable<T> amb(Observable<? extends T> o1, Observable
      *            an Observable competing to react first
      * @param o9
      *            an Observable competing to react first
-     * @return an Observable that emits the same sequence of items as whichever of the source Observables first
-     *         emitted an item
+     * @return an Observable that emits the same sequence as whichever of the source Observables first
+     *         emitted an item or sent a termination notification
      * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
      */
     public final static <T> Observable<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) {
@@ -2974,7 +2983,8 @@ public final Observable<Boolean> all(Func1<? super T, Boolean> predicate) {
     }
 
     /**
-     * Mirrors the first Observable (current or provided) that emits an item.
+     * Mirrors the Observable (current or provided) that first either emits an item or sends a termination
+     * notification.
      * <p>
      * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/amb.png" alt="">
      * <dl>
@@ -2984,8 +2994,8 @@ public final Observable<Boolean> all(Func1<? super T, Boolean> predicate) {
      * 
      * @param t1
      *            an Observable competing to react first
-     * @return an Observable that emits the same sequence of items as whichever of the source Observables first
-     *         emitted an item
+     * @return an Observable that emits the same sequence as whichever of the source Observables first
+     *         emitted an item or sent a termination notification
      * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
      */
     public final Observable<T> ambWith(Observable<? extends T> t1) {