Mlbileschi update partial function documentation

To include the fact that the caller is responsible for checking 'isDefinedAt', except when using partial functions defined using {} and case statements.
I see.  The scaladoc could benefit from a simple example after the first line; maybe an inversion 1/x where !isDefinedAt(0), with an additional example of applyOrElse.  Then, "even if isDefinedAt is true, it may throw" makes sense as further clarification.  The sentence "The main distinction" could be hoisted in front of the simple(r) example, with different words to introduce orElse.