Merge pull request #1165 from zsxwing/review-issue1159

Update according to review in issue #1159

language-adaptors/rxjava-scala/src/examples/scala/rx/lang/scala/examples/RxScalaDemo.scala

@@ -779,26 +779,15 @@ class RxScalaDemo extends JUnitSuite {
     }
   }
 
-  @Test def startWithExample1(): Unit = {
+  @Test def startWithExample(): Unit = {
     val o1 = List(3, 4).toObservable
-    val o2 = 1 :: 2 :: o1
+    val o2 = 1 +: 2 +: o1
     assertEquals(List(1, 2, 3, 4), o2.toBlockingObservable.toList)
   }
 
-  @Test def startWithExample2(): Unit = {
-    val prepended = List(2, 4).toObservable
-    val o = List(5, 6, 7, 8).toObservable.filter(_ % 2 == 0).startWith(prepended)
-    assertEquals(List(2, 4, 6, 8), o.toBlockingObservable.toList)
-  }
-
-  @Test def startWithExample3(): Unit = {
-    val o = List(5, 6, 7, 8).toObservable.filter(_ % 2 == 0).startWith(List(2, 4))
-    assertEquals(List(2, 4, 6, 8), o.toBlockingObservable.toList)
-  }
-
-  @Test def startWithExample4(): Unit = {
-    val o = List(5, 6, 7, 8).toObservable.filter(_ % 2 == 0).startWith(Array(2, 4))
-    assertEquals(List(2, 4, 6, 8), o.toBlockingObservable.toList)
+  @Test def appendExample(): Unit = {
+    val o = List(1, 2).toObservable :+ 3 :+ 4
+    assertEquals(List(1, 2, 3, 4), o.toBlockingObservable.toList)
   }
 
 }

language-adaptors/rxjava-scala/src/main/scala/rx/lang/scala/Observable.scala

@@ -222,6 +222,16 @@ trait Observable[+T]
     (() => javaCO.connect(), toScalaObservable(javaCO))
   }
 
+  /**
+   * Returns an Observable that first emits the items emitted by `this`, and then `elem`.
+   *
+   * @param elem the item to be appended
+   * @return  an Observable that first emits the items emitted by `this`, and then `elem`.
+   */
+  def :+[U >: T](elem: U): Observable[U] = {
+    this ++ Observable.items(elem)
+  }
+
   /**
    * Returns an Observable that first emits the items emitted by `this`, and then the items emitted
    * by `that`.
@@ -247,57 +257,11 @@ trait Observable[+T]
    * @param elem the item to emit
    * @return an Observable that emits the specified item before it begins to emit items emitted by the source Observable
    */
-  def ::[U >: T](elem: U): Observable[U] = {
+  def +:[U >: T](elem: U): Observable[U] = {
     val thisJava = this.asJavaObservable.asInstanceOf[rx.Observable[U]]
     toScalaObservable(thisJava.startWith(elem))
   }
 
-  /**
-   * Returns an Observable that emits the items in a specified `Observable` before it begins to emit
-   * items emitted by the source Observable.
-   * <p>
-   * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/startWith.o.png">
-   *
-   * @param that an Observable that contains the items you want the modified Observable to emit first
-   * @return an Observable that emits the items in the specified `Observable` and then emits the items
-   *         emitted by the source Observable
-   */
-  def startWith[U >: T](that: Observable[U]): Observable[U] = {
-    val thisJava = this.asJavaObservable.asInstanceOf[rx.Observable[U]]
-    val thatJava = that.asJavaObservable.asInstanceOf[rx.Observable[U]]
-    toScalaObservable(thisJava.startWith(thatJava))
-  }
-
-  /**
-   * Returns an Observable that emits the items in a specified `Iterable` before it begins to emit items
-   * emitted by the source Observable.
-   * <p>
-   * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/startWith.png">
-   *
-   * @param iterable an Iterable that contains the items you want the modified Observable to emit first
-   * @return an Observable that emits the items in the specified `Iterable` and then emits the items
-   *         emitted by the source Observable
-   */
-  def startWith[U >: T](iterable: Iterable[U]): Observable[U] = {
-    val thisJava = this.asJavaObservable.asInstanceOf[rx.Observable[U]]
-    toScalaObservable(thisJava.startWith(iterable.asJava))
-  }
-
-  /**
-   * Returns an Observable that emits the items in a specified `Iterable`, on a specified `Scheduler`, before it begins to emit items emitted by the source Observable.
-   * <p>
-   * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/startWith.s.png">
-   *
-   * @param iterable an Iterable that contains the items you want the modified Observable to emit first
-   * @param scheduler the Scheduler to emit the prepended values on
-   * @return an Observable that emits the items in the specified `Iterable`, on a specified `Scheduler`, and then emits the items
-   *         emitted by the source Observable
-   */
-  def startWith[U >: T](iterable: Iterable[U], scheduler: Scheduler): Observable[U] = {
-    val thisJava = this.asJavaObservable.asInstanceOf[rx.Observable[U]]
-    toScalaObservable(thisJava.startWith(iterable.asJava, scalaSchedulerToJavaScheduler(scheduler)))
-  }
-
   /**
    * Returns an Observable that emits the items emitted by several Observables, one after the
    * other.
@@ -1133,7 +1097,7 @@ trait Observable[+T]
    * @return an Observable that emits `true` if the specified item is emitted by the source Observable,
    *         or `false` if the source Observable completes without emitting that item
    */
-  def contains(elem: Any): Observable[Boolean] = {
+  def contains[U >: T](elem: U): Observable[Boolean] = {
     exists(_ == elem)
   }
 
@@ -2580,7 +2544,7 @@ trait Observable[+T]
    * <p>
    * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/doOnTerminate.png">
    * <p>
-   * This differs from `finallyDo` in that this happens BEFORE onCompleted/onError are emitted.
+   * This differs from `finallyDo` in that this happens **before** `onCompleted/onError` are emitted.
    *
    * @param onTerminate the action to invoke when the source Observable calls `onCompleted` or `onError`
    * @return the source Observable with the side-effecting behavior applied

language-adaptors/rxjava-scala/src/test/scala/rx/lang/scala/CompletenessTest.scala

@@ -104,11 +104,12 @@ class CompletenessTest extends JUnitSuite {
       "skipWhile(Func1[_ >: T, Boolean])" -> "dropWhile(T => Boolean)",
       "skipWhileWithIndex(Func2[_ >: T, Integer, Boolean])" -> unnecessary,
       "skipUntil(Observable[U])" -> "dropUntil(Observable[E])",
-      "startWith(Array[T])" -> "startWith(Iterable[U])",
-      "startWith(Array[T], Scheduler)" -> "startWith(Iterable[U], Scheduler)",
-      "startWith(Iterable[T])" -> "startWith(Iterable[U])",
-      "startWith(Iterable[T], Scheduler)" -> "startWith(Iterable[U], Scheduler)",
-      "startWith(Observable[T])" -> "startWith(Observable[U])",
+      "startWith(T)" -> "[use `item +: o`]",
+      "startWith(Array[T])" -> "[use `Observable.items(items) ++ o`]",
+      "startWith(Array[T], Scheduler)" -> "[use `Observable.items(items).subscribeOn(scheduler) ++ o`]",
+      "startWith(Iterable[T])" -> "[use `Observable.from(iterable) ++ o`]",
+      "startWith(Iterable[T], Scheduler)" -> "[use `Observable.from(iterable).subscribeOn(scheduler) ++ o`]",
+      "startWith(Observable[T])" -> "[use `++`]",
       "skipLast(Int)" -> "dropRight(Int)",
       "skipLast(Long, TimeUnit)" -> "dropRight(Duration)",
       "skipLast(Long, TimeUnit, Scheduler)" -> "dropRight(Duration, Scheduler)",
@@ -165,9 +166,9 @@ class CompletenessTest extends JUnitSuite {
       "zip(Observable[_ <: T1], Observable[_ <: T2], Func2[_ >: T1, _ >: T2, _ <: R])" -> "[use instance method `zip` and `map`]",
       "zip(Observable[_ <: Observable[_]], FuncN[_ <: R])" -> "[use `zip` in companion object and `map`]",
       "zip(Iterable[_ <: Observable[_]], FuncN[_ <: R])" -> "[use `zip` in companion object and `map`]"
-  ) ++ List.iterate("T", 9)(s => s + ", T").map(
+  ) ++ List.iterate("T, T", 8)(s => s + ", T").map(
       // all 9 overloads of startWith:
-      "startWith(" + _ + ")" -> "[unnecessary because we can just use `::` instead]"
+      "startWith(" + _ + ")" -> "[use `Observable.items(...) ++ o`]"
   ).toMap ++ List.iterate("Observable[_ <: T]", 9)(s => s + ", Observable[_ <: T]").map(
       // concat 2-9
       "concat(" + _ + ")" -> "[unnecessary because we can use `++` instead or `Observable(o1, o2, ...).concat`]"