1 files changed, 30 insertions, 0 deletions
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
  */