Improve description of flatten, flatMap

Add examples and better explain the expected return type of the
methods flatMap and flatten.

Closes SI-5371.

3 files changed, 38 insertions, 2 deletions

diff --git a/src/library/scala/collection/GenTraversableLike.scala b/src/library/scala/collection/GenTraversableLike.scala
index 122eec2d90..c837775cf9 100644
--- a/src/library/scala/collection/GenTraversableLike.scala
+++ b/src/library/scala/collection/GenTraversableLike.scala
@@ -177,7 +177,28 @@ trait GenTraversableLike[+A, +Repr] extends GenTraversableOnce[A] with Paralleli
   def collect[B, That](pf: PartialFunction[A, B])(implicit bf: CanBuildFrom[Repr, B, That]): That
 
   /** Builds a new collection by applying a function to all elements of this $coll
-   *  and concatenating the results.
+   *  and using the elements of the resulting collections. For example:
+   *
+   *  {{{
+   *  def getWords(lines: Seq[String]): Seq[String] = lines flatMap (line => line split "\\W+")
+   *  }}}
+   *
+   *  The type of the resulting collection is guided by the static type of $coll. This might
+   *  cause unexpected results sometimes. For example:
+   *
+   *  {{{
+   *  // lettersOf will return a Seq[Char] of likely repeated letters, instead of a Set
+   *  def lettersOf(words: Seq[String]) = words flatMap (word => word.toSet)
+   *
+   *  // lettersOf will return a Set[Char], not a Seq
+   *  def lettersOf(words: Seq[String]) = words.toSet flatMap (word => word.toSeq)
+   *
+   *  // xs will be a an Iterable[Int]
+   *  val xs = Map("a" -> List(11,111), "b" -> List(22,222)).flatMap(_._2)
+   *
+   *  // ys will be a Map[Int, Int]
+   *  val ys = Map("a" -> List(1 -> 11,1 -> 111), "b" -> List(2 -> 22,2 -> 222)).flatMap(_._2)
+   *  }}}
    *
    *  @param f      the function to apply to each element.
    *  @tparam B     the element type of the returned collection.
diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index e2acc0b3e0..b4813e6341 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -709,6 +709,9 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr]
      *  outer $coll containing this `WithFilter` instance that satisfy
      *  predicate `p` and concatenating the results.
      *
+     *  The type of the resulting collection will be guided by the static type
+     *  of the outer $coll.
+     *
      *  @param f      the function to apply to each element.
      *  @tparam B     the element type of the returned collection.
      *  @tparam That  $thatinfo
diff --git a/src/library/scala/collection/generic/GenericTraversableTemplate.scala b/src/library/scala/collection/generic/GenericTraversableTemplate.scala
index 12c1a75c7a..7333074778 100644
--- a/src/library/scala/collection/generic/GenericTraversableTemplate.scala
+++ b/src/library/scala/collection/generic/GenericTraversableTemplate.scala
@@ -116,7 +116,19 @@ trait GenericTraversableTemplate[+A, +CC[X] <: GenTraversable[X]] extends HasNew
   }
 
   /** Converts this $coll of traversable collections into
-   *  a $coll in which all element collections are concatenated.
+   *  a $coll formed by the elements of these traversable
+   *  collections.
+   *
+   *  The resulting collection's type will be guided by the
+   *  static type of $coll. For example:
+   *
+   *  {{{
+   *  val xs = List(Set(1, 2, 3), Set(1, 2, 3))
+   *  // xs == List(1, 2, 3, 1, 2, 3)
+   *
+   *  val ys = Set(List(1, 2, 3), List(3, 2, 1))
+   *  // ys == Set(1, 2, 3)
+   *  }}}
    *
    *  @tparam B the type of the elements of each traversable collection.
    *  @param asTraversable an implicit conversion which asserts that the element