Explain Function1 vs PartialFunction

Add an explanation in PartialFunction as to how it differs from Function1,
with examples of what it can do that Function1 cannot.

Make it explicit that calling apply may throw exceptions in both of them,
even in the case where isDefinedAt returns true.

Closes SI-5370.

2 files changed, 35 insertions, 1 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..ae2c343e0b 100644
--- a/src/library/scala/PartialFunction.scala
+++ b/src/library/scala/PartialFunction.scala
@@ -13,6 +13,32 @@ 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
+ *  an alternative behavior can be applied to those elements that are 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
  */