Correct documentation for Observable.merge

Fixes #158

Author: lukestephenson

src/main/scala/rx/lang/scala/Observable.scala

@@ -34,7 +34,7 @@ import scala.reflect.ClassTag
  * The Observable interface that implements the Reactive Pattern.
  *
  * @define subscribeObserverMain
- * Call this method to subscribe an [[rx.lang.scala.Observer]] for receiving 
+ * Call this method to subscribe an [[rx.lang.scala.Observer]] for receiving
  * items and notifications from the Observable.
  *
  * A typical implementation of `subscribe` does the following:
@@ -50,9 +50,9 @@ import scala.reflect.ClassTag
  * `Observable[T]` implementation indicates otherwise, Observers should make no
  * assumptions about the order in which multiple Observers will receive their notifications.
  *
- * @define subscribeObserverParamObserver 
+ * @define subscribeObserverParamObserver
  *         the observer
- * @define subscribeObserverParamScheduler 
+ * @define subscribeObserverParamScheduler
  *         the [[rx.lang.scala.Scheduler]] on which Observers subscribe to the Observable
  *
  * @define subscribeSubscriberMain
@@ -76,7 +76,7 @@ import scala.reflect.ClassTag
  * @define subscribeSubscriberParamScheduler
  *         the [[rx.lang.scala.Scheduler]] on which [[Subscriber]]s subscribe to the Observable
  *
- * @define subscribeAllReturn 
+ * @define subscribeAllReturn
  *         a [[rx.lang.scala.Subscription]] reference whose `unsubscribe` method can be called to  stop receiving items
  *         before the Observable has finished sending them
  *
@@ -86,7 +86,7 @@ import scala.reflect.ClassTag
  * @define subscribeCallbacksMainNoNotifications
  * Call this method to receive items from this observable.
  *
- * @define subscribeCallbacksParamOnNext 
+ * @define subscribeCallbacksParamOnNext
  *         this function will be called whenever the Observable emits an item
  * @define subscribeCallbacksParamOnError
  *         this function will be called if an error occurs
@@ -244,7 +244,7 @@ trait Observable[+T]
   def subscribe(onNext: T => Unit, onError: Throwable => Unit, onCompleted: () => Unit): Subscription = {
     asJavaObservable.subscribe(
       scalaFunction1ProducingUnitToAction1(onNext),
-      scalaFunction1ProducingUnitToAction1(onError), 
+      scalaFunction1ProducingUnitToAction1(onError),
       scalaFunction0ProducingUnitToAction0(onCompleted)
     )
   }
@@ -359,7 +359,7 @@ trait Observable[+T]
    * with timestamps provided by the given Scheduler.
    * <p>
    * <img width="640" height="310" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/timestamp.s.png" alt="" />
-   * 
+   *
    * @param scheduler [[rx.lang.scala.Scheduler]] to use as a time source.
    * @return an Observable that emits timestamped items from the source
    *         Observable with timestamps provided by the given Scheduler
@@ -370,8 +370,8 @@ trait Observable[+T]
   }
 
   /**
-   * Returns an Observable formed from this Observable and another Observable by combining 
-   * corresponding elements in pairs. 
+   * Returns an Observable formed from this Observable and another Observable by combining
+   * corresponding elements in pairs.
    * The number of `onNext` invocations of the resulting `Observable[(T, U)]`
    * is the minumum of the number of `onNext` invocations of `this` and `that`.
    *
@@ -434,7 +434,7 @@ trait Observable[+T]
   /**
    * Zips this Observable with its indices.
    *
-   * @return An Observable emitting pairs consisting of all elements of this Observable paired with 
+   * @return An Observable emitting pairs consisting of all elements of this Observable paired with
    *         their index. Indices start at 0.
    */
   def zipWithIndex: Observable[(T, Int)] = {
@@ -1111,7 +1111,7 @@ trait Observable[+T]
    * transforming the [[rx.lang.scala.Notification]] objects emitted by the source Observable into the items
    * or notifications they represent.
    *
-   * This operation is only available if `this` is of type `Observable[Notification[U]]` for some `U`, 
+   * This operation is only available if `this` is of type `Observable[Notification[U]]` for some `U`,
    * otherwise you will get a compilation error.
    *
    * <img width="640" height="335" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/dematerialize.png" alt="" />
@@ -1142,7 +1142,7 @@ trait Observable[+T]
    * function that returns an Observable (`resumeFunction`) to
    * `onErrorResumeNext`, if the original Observable encounters an error, instead of
    * invoking its Observer's `onError` method, it will instead relinquish control to
-   * the Observable returned from `resumeFunction`, which will invoke the Observer's 
+   * the Observable returned from `resumeFunction`, which will invoke the Observer's
    * [[rx.lang.scala.Observer.onNext onNext]] method if it is able to do so. In such a case, because no
    * Observable necessarily invokes `onError`, the Observer may never know that an
    * error happened.
@@ -1546,7 +1546,7 @@ trait Observable[+T]
    * When you call `cache`, it does not yet subscribe to the
    * source Observable. This only happens when `subscribe` is called
    * the first time on the Observable returned by `cache`.
-   * 
+   *
    * Note: You sacrifice the ability to unsubscribe from the origin when you use the
    * `cache()` operator so be careful not to use this operator on Observables that
    * emit an infinite or very large number of items that will use up memory.
@@ -1930,7 +1930,7 @@ trait Observable[+T]
    *
    * <img width="640" height="305" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/take.png" alt="" />
    *
-   * This method returns an Observable that will invoke a subscribing [[rx.lang.scala.Observer]]'s 
+   * This method returns an Observable that will invoke a subscribing [[rx.lang.scala.Observer]]'s
    * [[rx.lang.scala.Observer.onNext onNext]] function a maximum of `num` times before invoking
    * [[rx.lang.scala.Observer.onCompleted onCompleted]].
    *
@@ -2091,7 +2091,7 @@ trait Observable[+T]
    *
    * <img width="640" height="305" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/toList.png" alt="" />
    *
-   * Normally, an Observable that returns multiple items will do so by invoking its [[rx.lang.scala.Observer]]'s 
+   * Normally, an Observable that returns multiple items will do so by invoking its [[rx.lang.scala.Observer]]'s
    * [[rx.lang.scala.Observer.onNext onNext]] method for each such item. You can change
    * this behavior, instructing the Observable to compose a list of all of these items and then to
    * invoke the Observer's `onNext` function once, passing it the entire list, by
@@ -2278,8 +2278,8 @@ trait Observable[+T]
    *
    * @param that
    *            an Observable to be merged
-   * @return an Observable that emits items from `this` and `that` until 
-   *            `this` or `that` emits `onError` or `onComplete`.
+   * @return an Observable that emits items from `this` and `that` until
+   *            `this` or `that` emits `onError` or both Observables emit `onCompleted`.
    */
   def merge[U >: T](that: Observable[U]): Observable[U] = {
     val thisJava: rx.Observable[_ <: U] = this.asJavaObservable
@@ -2675,7 +2675,7 @@ trait Observable[+T]
    * <img width="640" height="400" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout4.png" alt="" />
    * </p>
    * Note: The arrival of the first source item is never timed out.
-   * 
+   *
    * @param timeoutSelector
    *            a function that returns an observable for each item emitted by the source
    *            Observable and that determines the timeout window for the subsequent item
@@ -2822,7 +2822,7 @@ trait Observable[+T]
    * `NoSuchElementException` if the source Observable is empty.
    * <p>
    * <img width="640" height="310" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/first.png" alt="" />
-   * 
+   *
    * @return an Observable that emits only the very first item emitted by the source Observable, or raises an
    *         `NoSuchElementException` if the source Observable is empty
    * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Filtering-Observables#wiki-first">RxJava Wiki: first()</a>
@@ -2837,7 +2837,7 @@ trait Observable[+T]
    * `NoSuchElementException` if the source Observable is empty.
    * <p>
    * <img width="640" height="310" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/first.png" alt="" />
-   * 
+   *
    * @return an Observable that emits only the very first item emitted by the source Observable, or raises an
    *         `NoSuchElementException` if the source Observable is empty
    * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Filtering-Observables#wiki-first">RxJava Wiki: first()</a>
@@ -2886,9 +2886,9 @@ trait Observable[+T]
   /**
    * Returns an Observable that emits the last item emitted by the source Observable or notifies observers of
    * an `NoSuchElementException` if the source Observable is empty.
-   * 
+   *
    * <img width="640" height="305" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/last.png" alt="" />
-   * 
+   *
    * @return an Observable that emits the last item from the source Observable or notifies observers of an
    *         error
    * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Filtering-Observable-Operators#wiki-last">RxJava Wiki: last()</a>
@@ -2930,9 +2930,9 @@ trait Observable[+T]
    * If the source Observable completes after emitting a single item, return an Observable that emits that
    * item. If the source Observable emits more than one item or no items, notify of an `IllegalArgumentException`
    * or `NoSuchElementException` respectively.
-   * 
+   *
    * <img width="640" height="315" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/single.png" alt="" />
-   * 
+   *
    * @return an Observable that emits the single item emitted by the source Observable
    * @throws IllegalArgumentException if the source emits more than one item
    * @throws NoSuchElementException if the source emits no items
@@ -3571,7 +3571,7 @@ trait Observable[+T]
    * specified delay. Error notifications from the source Observable are not delayed.
    *
    * <img width="640" height="310" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.png" alt="" />
-   * 
+   *
    * @param delay the delay to shift the source by
    * @return the source Observable shifted in time by the specified delay
    */
@@ -3584,7 +3584,7 @@ trait Observable[+T]
    * specified delay. Error notifications from the source Observable are not delayed.
    *
    * <img width="640" height="310" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.s.png" alt="" />
-   * 
+   *
    * @param delay the delay to shift the source by
    * @param scheduler the Scheduler to use for delaying
    * @return the source Observable shifted in time by the specified delay
@@ -3648,7 +3648,7 @@ trait Observable[+T]
    * Return an Observable that delays the subscription to the source Observable by a given amount of time.
    *
    * <img width="640" height="310" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/delaySubscription.png" alt="" />
-   * 
+   *
    * @param delay the time to delay the subscription
    * @return an Observable that delays the subscription to the source Observable by the given amount
    */
@@ -3661,7 +3661,7 @@ trait Observable[+T]
    * both waiting and subscribing on a given Scheduler.
    *
    * <img width="640" height="310" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/delaySubscription.s.png" alt="" />
-   * 
+   *
    * @param delay the time to delay the subscription
    * @param scheduler the Scheduler on which the waiting and subscription will happen
    * @return an Observable that delays the subscription to the source Observable by a given
@@ -3700,9 +3700,9 @@ trait Observable[+T]
   /**
    * Returns an Observable that emits the single item at a specified index in a sequence of emissions from a
    * source Observbable.
-   * 
+   *
    * <img width="640" height="310" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/elementAt.png" alt="" />
-   * 
+   *
    * @param index
    *            the zero-based index of the item to retrieve
    * @return an Observable that emits a single item: the item at the specified position in the sequence of
@@ -3718,9 +3718,9 @@ trait Observable[+T]
   /**
    * Returns an Observable that emits the item found at a specified index in a sequence of emissions from a
    * source Observable, or a default item if that index is out of range.
-   * 
+   *
    * <img width="640" height="310" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/elementAtOrDefault.png" alt="" />
-   * 
+   *
    * @param index
    *            the zero-based index of the item to retrieve
    * @param default
@@ -4365,7 +4365,7 @@ object Observable {
   `o => Subscription{}` have both of these types.
   So we call the old create method "create", and the new create method "apply".
   Try it out yourself here:
-  def foo[T]: Unit = { 
+  def foo[T]: Unit = {
     val fMeant: Observer[T] => Subscription = o => Subscription{}
     val fWrong: Subscriber[T] => Unit = o => Subscription{}
   }
@@ -4402,7 +4402,7 @@ object Observable {
   def apply[T](f: Subscriber[T] => Unit): Observable[T] = {
     toScalaObservable(rx.Observable.create(f))
   }
-  
+
   /**
    * Returns an Observable that invokes an [[rx.lang.scala.Observer]]'s [[rx.lang.scala.Observer.onError onError]]
    * method when the Observer subscribes to it.