comments, docs and names improvement

Author: zsxwing

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

@@ -895,8 +895,8 @@ class RxScalaDemo extends JUnitSuite {
     val keySelector = (s: String) => s.head
     val valueSelector = (s: String) => s.tail
     val mapFactory = () => mutable.Map('d' -> mutable.ListBuffer("oug"))
-    val valueFactory = (k: Char) => mutable.ListBuffer[String]()
-    val m = o.toMultimap(keySelector, valueSelector, mapFactory, valueFactory)
+    val bufferFactory = (k: Char) => mutable.ListBuffer[String]()
+    val m = o.toMultimap(keySelector, valueSelector, mapFactory, bufferFactory)
     println(m.toBlocking.single)
   }
 

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

@@ -3915,7 +3915,7 @@ trait Observable[+T]
   /**
    * Returns an Observable that emits a single `mutable.Map[K, mutable.Buffer[V]]`, returned by a specified `mapFactory` function, that
    * contains values, extracted by a specified `valueSelector` function from items emitted by the source Observable and
-   * keyed by the `keySelector` function.
+   * keyed by the `keySelector` function. `mutable.Map[K, B]` is the same instance create by `mapFactory`.
    *
    * <img width="640" height="305" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/toMultiMap.png">
    *
@@ -3932,17 +3932,17 @@ trait Observable[+T]
   /**
    * Returns an Observable that emits a single `mutable.Map[K, B]`, returned by a specified `mapFactory` function, that
    * contains values extracted by a specified `valueSelector` function from items emitted by the source Observable, and
-   * keyed by the `keySelector` function.
+   * keyed by the `keySelector` function. `mutable.Map[K, B]` is the same instance create by `mapFactory`.
    *
    * <img width="640" height="305" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/toMultiMap.png">
    *
    * @param keySelector the function that extracts a key from the source items to be used as the key in the Map
    * @param valueSelector the function that extracts a value from the source items to be used as the value in the Map
    * @param mapFactory the function that returns a Map instance to be used
-   * @param collectionFactory the function that returns a `mutable.Buffer[V]` instance for a particular key to be used in the Map
-   * @return an Observable that emits a single item: a `mutable.Map[K, B]` that contains mapped items from the source Observable
+   * @param bufferFactory the function that returns a `mutable.Buffer[V]` instance for a particular key to be used in the Map
+   * @return an Observable that emits a single item: a `mutable.Map[K, B]` that contains mapped items from the source Observable.
    */
-  def toMultimap[K, V, B <: mutable.Buffer[V], M <: mutable.Map[K, B]](keySelector: T => K, valueSelector: T => V, mapFactory: () => M, collectionFactory: K => B): Observable[M] = {
+  def toMultimap[K, V, B <: mutable.Buffer[V], M <: mutable.Map[K, B]](keySelector: T => K, valueSelector: T => V, mapFactory: () => M, bufferFactory: K => B): Observable[M] = {
     // It's complicated to convert `mutable.Map[K, mutable.Buffer[V]]` to `java.util.Map[K, java.util.Collection[V]]`,
     // so RxScala implements `toMultimap` directly.
     // Choosing `mutable.Buffer/Map` is because `append/update` is necessary to implement an efficient `toMultimap`.
@@ -3955,7 +3955,7 @@ trait Observable[+T]
             val key = keySelector(t)
             val values = map.get(key) match {
               case Some(v) => v
-              case None => collectionFactory(key)
+              case None => bufferFactory(key)
             }
             values += valueSelector(t)
             map += key -> values: Unit

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

@@ -250,20 +250,24 @@ class ObservableTests extends JUnitSuite {
     val o = Observable.items("a", "b", "cc", "dd").toMultimap(_.length, s => s, () => m)
     val expected = Map(1 -> List("a", "b"), 2 -> List("cc", "dd"))
     val r = o.toBlocking.single
-    assertTrue(m eq r) // check same instance
+    // r should be the same instance created by the `mapFactory`
+    assertTrue(m eq r)
     assertEquals(expected, r)
   }
 
   @Test
-  def testToMultimapWithCollectionFactory() {
+  def testToMultimapWithBufferFactory() {
     val m = mutable.Map[Int, mutable.Buffer[String]]()
     val ls = List(mutable.Buffer[String](), mutable.Buffer[String]())
     val o = Observable.items("a", "b", "cc", "dd").toMultimap(_.length, s => s, () => m, (i: Int) => ls(i - 1))
     val expected = Map(1 -> List("a", "b"), 2 -> List("cc", "dd"))
     val r = o.toBlocking.single
-    assertTrue(m eq r) // check same instance
-    assertTrue(ls(0) eq r(1)) // check same instance
-    assertTrue(ls(1) eq r(2)) // check same instance
+    // r should be the same instance created by the `mapFactory`
+    assertTrue(m eq r)
+    // r(1) should be the same instance created by the first calling `bufferFactory`
+    assertTrue(ls(0) eq r(1))
+    // r(2) should be the same instance created by the second calling `bufferFactory`
+    assertTrue(ls(1) eq r(2))
     assertEquals(expected, r)
   }