5 files changed, 77 insertions, 3 deletions
diff --git a/src/library/scala/Function1.scala b/src/library/scala/Function1.scala
index dc8e67bbb0..7517e6604b 100644
--- a/src/library/scala/Function1.scala
+++ b/src/library/scala/Function1.scala
@@ -24,10 +24,18 @@ package scala
  *    assert(succ(0) == anonfun1(0))
  *  }
  *  }}}
+ *
+ *  Note that `Function1` does not define a total function, as might
+ *  be suggested by the existence of [[scala.PartialFunction]]. The only
+ *  distinction between `Function1` and `PartialFunction` is that the
+ *  latter can specify inputs which it will not handle.
+ *
  */
 @annotation.implicitNotFound(msg = "No implicit view available from ${T1} => ${R}.")
 trait Function1[@specialized(scala.Int, scala.Long, scala.Float, scala.Double) -T1, @specialized(scala.Unit, scala.Boolean, scala.Int, scala.Float, scala.Long, scala.Double) +R] extends AnyRef { self =>
-  /** Apply the body of this function to the argument.
+  /** Apply the body of this function to the argument. It may throw an
+   *  exception.
+   *
    *  @return   the result of function application.
    */
   def apply(v1: T1): R
diff --git a/src/library/scala/PartialFunction.scala b/src/library/scala/PartialFunction.scala
index b2910c2278..70caff0221 100644
--- a/src/library/scala/PartialFunction.scala
+++ b/src/library/scala/PartialFunction.scala
@@ -13,6 +13,36 @@ package scala
  *  The function `isDefinedAt` allows to test dynamically if a value is in
  *  the domain of the function.
  *
+ *  Even if `isDefinedAt` returns true for an `a: A`, calling `apply(a)` may
+ *  still throw an exception, so the following code is legal:
+ *
+ *  {{{
+ *  val f: PartialFunction[Int, Any] = { case _ => 1/0 }
+ *  }}}
+ *
+ *  The main distinction between `PartialFunction` and [[scala.Function1]] is
+ *  that the user of a `PartialFunction` may choose to do something different
+ *  with input that is declared to be outside its domain. For example:
+ *
+ *  {{{
+ *  val sample = 1 to 10
+ *  val isEven: PartialFunction[Int, String] = { 
+ *    case x if x % 2 == 0 => x+" is even" 
+ *  }
+ *
+ *  // the method collect can use isDefinedAt to select which members to collect
+ *  val evenNumbers = sample collect isEven
+ *
+ *  val isOdd: PartialFunction[Int, String] = { 
+ *    case x if x % 2 == 1 => x+" is odd" 
+ *  }
+ *
+ *  // the method orElse allows chaining another partial function to handle 
+ *  // input outside the declared domain
+ *  val numbers = sample map (isEven orElse isOdd)
+ *  }}}
+ *
+ *
  *  @author  Martin Odersky
  *  @version 1.0, 16/07/2003
  */
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