Add initial unit test for Catch and augment documentation

 - Add unit test for andFinally
 - Reduce code duplication in andFinally
 - Extend documentation

Author: janekdb

src/library/scala/util/control/Exception.scala

@@ -83,6 +83,10 @@ object Exception {
    *  Pass a different value for rethrow if you want to probably
    *  unwisely allow catching control exceptions and other throwables
    *  which the rest of the world may expect to get through.
+   *  @tparam T result type of bodies used in try and catch blocks
+   *  @param pf Partial function used when applying catch logic to determine result value
+   *  @param fin Finally logic which if defined will be invoked after catch logic
+   *  @param rethrow Predicate on throwables determining when to rethrow a caught [[Throwable]]
    */
   class Catch[+T](
     val pf: Catcher[T],
@@ -105,10 +109,12 @@ object Exception {
       }
       finally fin foreach (_.invoke())
 
-    /* Create an empty Try container with this Catch and the supplied `Finally`. */
-    def andFinally(body: => Unit): Catch[T] = fin match {
-      case None     => new Catch(pf, Some(new Finally(body)), rethrow)
-      case Some(f)  => new Catch(pf, Some(f and body), rethrow)
+    /** Create a new Catch container from this object and the supplied finally body.
+     *  @param body The additional logic to apply after all existing finally bodies
+     */
+    def andFinally(body: => Unit): Catch[T] = {
+      val appendedFin = fin map(_ and body) getOrElse new Finally(body)
+      new Catch(pf, Some(appendedFin), rethrow)
     }
 
     /** Apply this catch logic to the supplied body, mapping the result
@@ -117,13 +123,13 @@ object Exception {
     def opt[U >: T](body: => U): Option[U] = toOption(Some(body))
 
     /** Apply this catch logic to the supplied body, mapping the result
-     *  into Either[Throwable, T] - Left(exception) if an exception was caught,
-     *  Right(T) otherwise.
+     *  into `Either[Throwable, T]` - `Left(exception)` if an exception was caught,
+     *  `Right(T)` otherwise.
      */
     def either[U >: T](body: => U): Either[Throwable, U] = toEither(Right(body))
 
     /** Apply this catch logic to the supplied body, mapping the result
-     * into Try[T] - Failure if an exception was caught, Success(T) otherwise.
+     * into `Try[T]` - `Failure` if an exception was caught, `Success(T)` otherwise.
      */
     def withTry[U >: T](body: => U): scala.util.Try[U] = toTry(Success(body))
 

test/junit/scala/util/control/ExceptionTest.scala

@@ -0,0 +1,42 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2016-2016, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+package scala.util
+
+import org.junit.runner.RunWith
+import org.junit.runners.JUnit4
+import org.junit.Test
+import org.junit.Assert._
+
+import scala.collection.mutable.ListBuffer
+
+import scala.util.control.Exception._
+
+@RunWith(classOf[JUnit4])
+class ExceptionTest {
+
+  @Test
+  def andFinally(): Unit = {
+
+    locally {
+      val audit = ListBuffer[Int]()
+      val katch = nonFatalCatch[Unit].andFinally(audit append 1)
+      val result = katch(10)
+      assertEquals(result, 10)
+      assertEquals(audit.toList, 1 :: Nil)
+    }
+
+    locally {
+      val audit = ListBuffer[Int]()
+      val katch = nonFatalCatch[Unit].andFinally(audit append 1).andFinally(audit append 2)
+      val result = katch(20)
+      assertEquals(result, 20)
+      assertEquals(audit.toList, 1 :: 2 :: Nil)
+    }
+  }
+}