document scala.util.control.Breaks methods

Authored by Chris League and Roland Kuhn

git-svn-id: http://lampsvn.epfl.ch/svn-repos/scala/scala/trunk@25314 5e8d7ff9-d8ef-0310-90f0-a4852d11357a

src/library/scala/util/control/Breaks.scala

@@ -16,7 +16,7 @@ package scala.util.control
  *
  *  breakable {
  *    for (...) {
- *      if (...) break
+ *      if (...) break()
  *    }
  *  }
  *  }}}
@@ -27,7 +27,11 @@ 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`. The `break` may be
+   * executed further down in the call stack provided that it is called on the
+   * exact same instance of `Breaks`.
+   */
   def breakable(op: => Unit) {
     try {
       op
@@ -41,6 +45,18 @@ class Breaks {
     def catchBreak(onBreak: => Unit): Unit
   }
 
+  /**
+   * This variant enables the execution of a code block in case of a `break()`:
+   * {{{
+   * tryBreakable {
+   *   for (...) {
+   *     if (...) break()
+   *   }
+   * } catchBreak {
+   *   doCleanup()
+   * }
+   * }}}
+   */
   def tryBreakable(op: => Unit) = new TryBlock {
     def catchBreak(onBreak: => Unit) = try {
       op
@@ -51,9 +67,11 @@ class Breaks {
     }
   }
 
-  /** Break from dynamically closest enclosing breakable block.
+  /**
+   * Break from dynamically closest enclosing breakable block using this exact
+   * `Breaks` instance.
    *
-   *  @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 }
 }