2nd round of clean ups (see r25285)

4 files changed, 96 insertions, 88 deletions

diff --git a/src/library/scala/util/control/Breaks.scala b/src/library/scala/util/control/Breaks.scala
index 80df8cc0bd..9b1abefe00 100644
--- a/src/library/scala/util/control/Breaks.scala
+++ b/src/library/scala/util/control/Breaks.scala
@@ -6,31 +6,28 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.util.control
 
 /** A class that can be instantiated for the break control abstraction.
  *  Example usage:
- *
- *  <pre>
+ *  {{{
  *  val mybreaks = new Breaks
- *  import</b> mybreaks.{break, breakable}
+ *  import mybreaks.{break, breakable}
  *
  *  breakable {
- *    <b>for</b> (...) {
- *      <b>if</b> (...) break
+ *    for (...) {
+ *      if (...) break
  *    }
- *  }</pre>
- *
+ *  }
+ *  }}}
  *  Calls to break from one instantiation of `Breaks` will never
- *  target breakable objects of some other instantion.
+ *  target breakable objects of some other instantiation.
  */
 class Breaks {
 
   private val breakException = new BreakControl
 
-  /** A block from which one can exit with a `break`'. */
+  /** A block from which one can exit with a `break`. */
   def breakable(op: => Unit) {
     try {
       op
@@ -54,26 +51,25 @@ class Breaks {
     }
   }
 
-  /* Break from dynamically closest enclosing breakable block.
+  /** Break from dynamically closest enclosing breakable block.
    *
-   * @note This might be different than the statically closest enclosing block!
+   *  @note This might be different than the statically closest enclosing block!
    */
   def break() { throw breakException }
 }
 
 /** An object that can be used for the break control abstraction.
- *  Example usage:<pre>
- *
- *  <b>import</b> Breaks.{break, breakable}
+ *  Example usage:
+ *  {{{
+ *  import Breaks.{break, breakable}
  *
  *  breakable {
- *    <b>for</b> (...) {
- *      <b>if</b> (...) break
+ *    for (...) {
+ *      if (...) break
  *    }
- *  }</pre>
- *
+ *  }
+ *  }}}
  */
 object Breaks extends Breaks
 
 private class BreakControl extends ControlThrowable
-
diff --git a/src/library/scala/util/control/ControlThrowable.scala b/src/library/scala/util/control/ControlThrowable.scala
index 4d1116ba6f..8cbe3064ef 100644
--- a/src/library/scala/util/control/ControlThrowable.scala
+++ b/src/library/scala/util/control/ControlThrowable.scala
@@ -6,32 +6,28 @@
 **                          |/                                          **
 \*                                                                      */
 
-
 package scala.util.control
 
-/**
- * A marker trait indicating that the `Throwable` it is mixed
- * into is intended for flow control.
- *
- * Note that `Throwable` subclasses which extend this trait
- * may extend any other `Throwable` subclass (eg.
- * `RuntimeException`) and are not required to extend
- * `Throwable` directly.
+/** A marker trait indicating that the `Throwable` it is mixed into is
+ *  intended for flow control.
  *
- * Instances of `Throwable` subclasses marked in this way should
- * not normally be caught. Where catch-all behaviour is required
- * `ControlThrowable`s should be propagated, for example:
+ *  Note that `Throwable` subclasses which extend this trait may extend any
+ *  other `Throwable` subclass (eg. `RuntimeException`) and are not required
+ *  to extend `Throwable` directly.
  *
- * <pre>
+ *  Instances of `Throwable` subclasses marked in this way should not normally
+ *  be caught. Where catch-all behaviour is required `ControlThrowable`
+ *  should be propagated, for example:
+ *  {{{
  *  import scala.util.control.ControlThrowable
  *
  *  try {
  *    // Body might throw arbitrarily
- * } catch {
- *   case ce : ControlThrowable => throw ce // propagate
- *   case t : Exception => log(t)           // log and suppress
- * </pre>
+ *  } catch {
+ *    case ce : ControlThrowable => throw ce // propagate
+ *    case t : Exception => log(t)           // log and suppress
+ *  }}}
  *
- * @author Miles Sabin
+ *  @author Miles Sabin
  */
 trait ControlThrowable extends Throwable with NoStackTrace
diff --git a/src/library/scala/util/control/Exception.scala b/src/library/scala/util/control/Exception.scala
index ad90b222c2..c8470d2504 100644
--- a/src/library/scala/util/control/Exception.scala
+++ b/src/library/scala/util/control/Exception.scala
@@ -1,3 +1,11 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
 package scala.util.control
 
 import collection.immutable.List
@@ -5,17 +13,14 @@ import java.lang.reflect.InvocationTargetException
 
 /** Classes representing the components of exception handling.
  *  Each class is independently composable.  Some example usages:
+ *  {{{
+ *  import scala.util.control.Exception._
+ *  import java.net._
  *
- *
- *
- *  <pre>
- *  <b>import</b> scala.util.control.Exception._
- *  <b>import</b> java.net._
- *
- *  <b>val</b> s = "http://www.scala-lang.org/"
- *  <b>val</b> x1 = catching(classOf[MalformedURLException]) opt new URL(s)
- *  <b>val</b> x2 = catching(classOf[MalformedURLException], classOf[NullPointerException]) either new URL(s)
- *  </pre>
+ *  val s = "http://www.scala-lang.org/"
+ *  val x1 = catching(classOf[MalformedURLException]) opt new URL(s)
+ *  val x2 = catching(classOf[MalformedURLException], classOf[NullPointerException]) either new URL(s)
+ *  }}}
  *
  *  @author Paul Phillips
  */
@@ -31,6 +36,7 @@ object Exception {
     def isDefinedAt(x: Throwable) = downcast(x) exists isDef
     def apply(x: Throwable): T = f(downcast(x).get)
   }
+
   def mkThrowableCatcher[T](isDef: Throwable => Boolean, f: Throwable => T) = mkCatcher(isDef, f)
 
   implicit def throwableSubtypeToCatcher[Ex <: Throwable: ClassManifest, T](pf: PartialFunction[Ex, T]) =
@@ -62,7 +68,7 @@ object Exception {
     protected val name = "Finally"
 
     def and(other: => Unit): Finally = new Finally({ body ; other })
-    def invoke(): Unit = { body }
+    def invoke() { body }
   }
 
   /** A container class for catch/finally logic.
@@ -92,14 +98,14 @@ object Exception {
       }
       finally fin map (_.invoke())
 
-    /* Create an empty Try container with this Catch and the supplied Finally */
+    /* 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)
     }
 
     /** Apply this catch logic to the supplied body, mapping the result
-     *  into Option[T] - None if any exception was caught, Some(T) otherwise.
+     *  into `Option[T]` - `None` if any exception was caught, `Some(T)` otherwise.
      */
     def opt[U >: T](body: => U): Option[U] = toOption(Some(body))
 
@@ -109,8 +115,8 @@ object Exception {
      */
     def either[U >: T](body: => U): Either[Throwable, U] = toEither(Right(body))
 
-    /** Create a new Catch with the same isDefinedAt logic as this one,
-      * but with the supplied apply method replacing the current one. */
+    /** Create a `Catch` object with the same `isDefinedAt` logic as this one,
+      * but with the supplied `apply` method replacing the current one. */
     def withApply[U](f: Throwable => U): Catch[U] = {
       val pf2 = new Catcher[U] {
         def isDefinedAt(x: Throwable) = pf isDefinedAt x
@@ -130,21 +136,21 @@ object Exception {
     def apply(): T                    = catcher(body)
     def apply[U >: T](other: => U): U = catcher(other)
 
-    /** As apply, but map caught exceptions to None and success to Some(T) */
+    /** As apply, but map caught exceptions to `None` and success to `Some(T)`. */
     def opt(): Option[T]                      = catcher opt body
     def opt[U >: T](other: => U): Option[U]   = catcher opt other
 
-    /** As apply, but map caught exceptions to Left(ex) and success to Right(x) */
+    /** As apply, but map caught exceptions to `Left(ex)` and success to Right(x) */
     def either(): Either[Throwable, T]                    = catcher either body
     def either[U >: T](other: => U): Either[Throwable, U] = catcher either other
 
-    /** Create a new Try with the supplied body replacing the current body */
+    /** Create a `Try` object with the supplied body replacing the current body. */
     def tryInstead[U >: T](other: => U) = new Try(other, catcher)
 
-    /** Create a new Try with the supplied logic appended to the existing Catch logic. */
+    /** Create a `Try` object with the supplied logic appended to the existing Catch logic. */
     def or[U >: T](pf: Catcher[U]) = new Try(body, catcher or pf)
 
-    /** Create a new Try with the supplied code appended to the existing Finally. */
+    /** Create a `Try`object with the supplied code appended to the existing `Finally`. */
     def andFinally(fin: => Unit) = new Try(body, catcher andFinally fin)
 
     override def toString() = List("Try(<body>)", catcher.toString) mkString " "
@@ -153,49 +159,51 @@ object Exception {
   final val nothingCatcher: Catcher[Nothing]  = mkThrowableCatcher(_ => false, throw _)
   final def allCatcher[T]: Catcher[T]         = mkThrowableCatcher(_ => true, throw _)
 
-  /** The empty Catch object. */
+  /** The empty `Catch` object. */
   final val noCatch: Catch[Nothing] = new Catch(nothingCatcher) withDesc "<nothing>"
 
-  /** A Catch object which catches everything. */
+  /** A `Catch` object which catches everything. */
   final def allCatch[T]: Catch[T] = new Catch(allCatcher[T]) withDesc "<everything>"
 
-  /** Creates a Catch object which will catch any of the supplied exceptions.
-   *  Since the returned Catch object has no specific logic defined and will simply
-   *  rethrow the exceptions it catches, you will typically want to call "opt" or
-   *  "either" on the return value, or assign custom logic by calling "withApply".
+  /** Creates a `Catch` object which will catch any of the supplied exceptions.
+   *  Since the returned `Catch` object has no specific logic defined and will simply
+   *  rethrow the exceptions it catches, you will typically want to call `opt` or
+   *  `either` on the return value, or assign custom logic by calling "withApply".
    *
-   *  Note that Catch objects automatically rethrow ControlExceptions and others
+   *  Note that `Catch` objects automatically rethrow `ControlExceptions` and others
    *  which should only be caught in exceptional circumstances.  If you really want
-   *  to catch exactly what you specify, use "catchingPromiscuously" instead.
+   *  to catch exactly what you specify, use `catchingPromiscuously` instead.
    */
   def catching[T](exceptions: Class[_]*): Catch[T] =
     new Catch(pfFromExceptions(exceptions : _*)) withDesc (exceptions map (_.getName) mkString ", ")
 
   def catching[T](c: Catcher[T]): Catch[T] = new Catch(c)
 
-  /** Creates a Catch object which will catch any of the supplied exceptions.
+  /** Creates a `Catch` object which will catch any of the supplied exceptions.
    *  Unlike "catching" which filters out those in shouldRethrow, this one will
-   *  catch whatever you ask of it: ControlThrowable, InterruptedException,
-   *  OutOfMemoryError, you name it.
+   *  catch whatever you ask of it: `ControlThrowable`, `InterruptedException`,
+   *  `OutOfMemoryError`, you name it.
    */
   def catchingPromiscuously[T](exceptions: Class[_]*): Catch[T] = catchingPromiscuously(pfFromExceptions(exceptions : _*))
   def catchingPromiscuously[T](c: Catcher[T]): Catch[T]         = new Catch(c, None, _ => false)
 
-  /** Creates a Catch object which catches and ignores any of the supplied exceptions. */
+  /** Creates a `Catch` object which catches and ignores any of the supplied exceptions. */
   def ignoring(exceptions: Class[_]*): Catch[Unit] =
     catching(exceptions: _*) withApply (_ => ())
 
-  /** Creates a Catch object which maps all the supplied exceptions to 'None'. */
+  /** Creates a `Catch` object which maps all the supplied exceptions to `None`. */
   def failing[T](exceptions: Class[_]*): Catch[Option[T]] =
     catching(exceptions: _*) withApply (_ => None)
 
-  /** Creates a Catch object which maps all the supplied exceptions to the given value. */
+  /** Creates a `Catch` object which maps all the supplied exceptions to the given value. */
   def failAsValue[T](exceptions: Class[_]*)(value: => T): Catch[T] =
     catching(exceptions: _*) withApply (_ => value)
 
-  /** Returns a partially constructed Catch object, which you must give
-    * an exception handler function as an argument to "by".  Example:
-    * handling(ex1, ex2) by (_.printStackTrace)
+  /** Returns a partially constructed `Catch` object, which you must give
+    * an exception handler function as an argument to `by`.  Example:
+    * {{{
+    *   handling(ex1, ex2) by (_.printStackTrace)
+    * }}}
     */
   class By[T,R](f: T => R) {
     def by(x: T): R = f(x)
@@ -205,10 +213,10 @@ object Exception {
     new By[Throwable => T, Catch[T]](fun _)
   }
 
-  /** Returns a Catch object with no catch logic and the argument as Finally. */
+  /** Returns a `Catch` object with no catch logic and the argument as `Finally`. */
   def ultimately[T](body: => Unit): Catch[T] = noCatch andFinally body
 
-  /** Creates a Catch object which unwraps any of the supplied exceptions. */
+  /** Creates a `Catch` object which unwraps any of the supplied exceptions. */
   def unwrapping[T](exceptions: Class[_]*): Catch[T] = {
     def unwrap(x: Throwable): Throwable =
       if (wouldMatch(x, exceptions) && x.getCause != null) unwrap(x.getCause)
diff --git a/src/library/scala/util/control/TailCalls.scala b/src/library/scala/util/control/TailCalls.scala
index 59e9618028..ca5442046c 100644
--- a/src/library/scala/util/control/TailCalls.scala
+++ b/src/library/scala/util/control/TailCalls.scala
@@ -1,10 +1,18 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
 package scala.util.control
 
 /** Methods exported by this object implement tail calls via trampolining.
- *  Tail calling methods have to return their result using `done` or call the next
- *  method using `tailcall`. Both return a `TailRec` object. The result of evaluating
- *  a tailcalling function can be retrieved from a `Tailrec` value using method result`.
- *  Here's a usage example:
+ *  Tail calling methods have to return their result using `done` or call the
+ *  next method using `tailcall`. Both return a `TailRec` object. The result
+ *  of evaluating a tailcalling function can be retrieved from a `Tailrec`
+ *  value using method `result`. Here's a usage example:
  *  {{{
  *  import scala.util.control.TailCalls._
  *
@@ -19,10 +27,10 @@ package scala.util.control
  */
 object TailCalls {
 
-  /** This class represents a tailcalling computation.
+  /** This class represents a tailcalling computation
    */
   abstract class TailRec[+A] {
-    /** Returns the result of the tailcalling computation
+    /** Returns the result of the tailcalling computation.
      */
     def result: A = {
       def loop(body: TailRec[A]): A = body match {
@@ -36,7 +44,8 @@ object TailCalls {
   /** Internal class representing a tailcall */
   protected case class Call[A](rest: () => TailRec[A]) extends TailRec[A]
 
-  /** Internal class representing the final result return from a tailcalling computation */
+  /** Internal class representing the final result returned from a tailcalling
+    * computation */
   protected case class Done[A](override val result: A) extends TailRec[A]
 
   /** Performs a tailcall
@@ -47,10 +56,9 @@ object TailCalls {
 
   /** Used to return final result from tailcalling computation
    *  @param  `result` the result value
-   *  @return a `TailRec` object representing a computation which immediately returns `result`
+   *  @return a `TailRec` object representing a computation which immediately
+   *          returns `result`
    */
   def done[A](result: A): TailRec[A] = new Done(result)
 
 }
-
-