more collection cleanups and better docs

25 files changed, 97 insertions, 79 deletions

diff --git a/src/library/scala/collection/Map.scala b/src/library/scala/collection/Map.scala
index 174ed8e863..0cc1f33404 100644
--- a/src/library/scala/collection/Map.scala
+++ b/src/library/scala/collection/Map.scala
@@ -37,7 +37,6 @@ import generic._
  */
 trait Map[A, +B] extends Iterable[(A, B)] with MapTemplate[A, B, Map[A, B]] {
   def empty: Map[A, B] = Map.empty
-  override protected[this] def newBuilder: Builder[(A, B), Map[A, B]] = immutable.Map.newBuilder[A, B]
 }
 
 /* Factory object for `Map` class */
diff --git a/src/library/scala/collection/Traversable.scala b/src/library/scala/collection/Traversable.scala
index 4d2ace813c..cadd4c8c80 100644
--- a/src/library/scala/collection/Traversable.scala
+++ b/src/library/scala/collection/Traversable.scala
@@ -11,7 +11,7 @@ package scala.collection
 
 // import immutable.{List, Stream, Nil}
 import mutable.{Buffer, ArrayBuffer, ListBuffer}
-import util.control.Breaks._
+import util.control.Breaks
 import generic._
 
 /** A template trait for traversable collections.
@@ -93,6 +93,8 @@ trait Traversable[+A] extends TraversableTemplate[A, Traversable[A]]
 /** Factory methods and utilities for instances of type Traversable */
 object Traversable extends TraversableFactory[Traversable] { self =>
 
+  /** provide braek functionality separate from client code */
+  private[collection] val breaks: Breaks = new Breaks
 
   implicit def builderFactory[A]: BuilderFactory[A, Traversable[A], Coll] = new VirtualBuilderFactory[A]
 //    new BuilderFactory[A, Traversable[A], Coll] { def apply(from: Coll) = from.traversableBuilder[A] }
diff --git a/src/library/scala/collection/generic/Addable.scala b/src/library/scala/collection/generic/Addable.scala
index b6fcefb113..d64aee1a61 100644
--- a/src/library/scala/collection/generic/Addable.scala
+++ b/src/library/scala/collection/generic/Addable.scala
@@ -12,7 +12,7 @@ package scala.collection.generic
 
 /** This class represents collections that can be augmented usmutableing a += operator.
  *
- *  @autor   Martin Odersky
+ *  @author   Martin Odersky
  *  @owner   Martin Odersky
  *  @version 2.8
  */
diff --git a/src/library/scala/collection/generic/Growable.scala b/src/library/scala/collection/generic/Growable.scala
index a085c9f9fd..7d41277ecd 100644
--- a/src/library/scala/collection/generic/Growable.scala
+++ b/src/library/scala/collection/generic/Growable.scala
@@ -13,7 +13,7 @@ package scala.collection.generic
 /** This class represents collections that can be augmented using a `+=` operator
  *  and that can be cleared of all elements using the `clear` method.
  *
- *  @autor   Martin Odersky
+ *  @author   Martin Odersky
  *  @owner   Martin Odersky
  *  @version 2.8
  */
diff --git a/src/library/scala/collection/generic/ImmutableMapFactory.scala b/src/library/scala/collection/generic/ImmutableMapFactory.scala
index 07eb37a4ad..2472472eb8 100644
--- a/src/library/scala/collection/generic/ImmutableMapFactory.scala
+++ b/src/library/scala/collection/generic/ImmutableMapFactory.scala
@@ -5,5 +5,5 @@ package scala.collection.generic
 abstract class ImmutableMapFactory[CC[A, +B] <: immutable.Map[A, B] with ImmutableMapTemplate[A, B, CC[A, B]]]
   extends MapFactory[CC] {
 
-  def newBuilder[A, B] = new ImmutableMapBuilder[A, B, CC[A, B]](empty[A, B])
+  def newBuilder[A, B] = new MapBuilder[A, B, CC[A, B]](empty[A, B])
 }
diff --git a/src/library/scala/collection/generic/ImmutableMapTemplate.scala b/src/library/scala/collection/generic/ImmutableMapTemplate.scala
index 005d561ff0..b001e72a08 100644
--- a/src/library/scala/collection/generic/ImmutableMapTemplate.scala
+++ b/src/library/scala/collection/generic/ImmutableMapTemplate.scala
@@ -31,8 +31,6 @@ trait ImmutableMapTemplate[A, +B, +This <: ImmutableMapTemplate[A, B, This] with
   extends MapTemplate[A, B, This] {
 self =>
 
-  override protected[this] def newBuilder: Builder[(A, B), This] = new ImmutableMapBuilder[A, B, This](empty)
-
   /** A new immutable map containing updating this map with a given key/value mapping.
    *  @param    key the key
    *  @param    value the value
diff --git a/src/library/scala/collection/generic/ImmutableSortedMapFactory.scala b/src/library/scala/collection/generic/ImmutableSortedMapFactory.scala
index d6751e24e9..47e767974a 100644
--- a/src/library/scala/collection/generic/ImmutableSortedMapFactory.scala
+++ b/src/library/scala/collection/generic/ImmutableSortedMapFactory.scala
@@ -6,5 +6,5 @@ abstract class ImmutableSortedMapFactory[CC[A, B] <: immutable.SortedMap[A, B] w
   extends SortedMapFactory[CC] {
 
   def newBuilder[A, B](implicit ord: Ordering[A]): Builder[(A, B), CC[A, B]] =
-    new ImmutableMapBuilder[A, B, CC[A, B]](empty(ord))
+    new MapBuilder[A, B, CC[A, B]](empty(ord))
 }
diff --git a/src/library/scala/collection/generic/IterableTemplate.scala b/src/library/scala/collection/generic/IterableTemplate.scala
index 8e05b95c29..c540f5d3c9 100644
--- a/src/library/scala/collection/generic/IterableTemplate.scala
+++ b/src/library/scala/collection/generic/IterableTemplate.scala
@@ -42,13 +42,17 @@ trait IterableTemplate[+A, +This <: IterableTemplate[A, This] with Iterable[A]]
   /** Apply a function <code>f</code> to all elements of this
    *  traversable object.
    *
-   *  @param  f   a function that is applied to every element.
+   *  @param  f   A function that is applied for its side-effect to every element.
+   *              The result (of arbitrary type U) of function `f` is discarded.
+   *
    *  @note This method underlies the implementation of most other bulk operations.
-   *  It should be overridden in concrete collection classes with efficient implementations.
+   *        Implementing `foreach` with `elements` is often suboptimal.
+   *        So `foreach` should be overridden in concrete collection classes if a more
+   *        efficient implementation is available.
    */
-  def foreach[B](f: A => B): Unit = elements.foreach(f)
+  def foreach[U](f: A => U): Unit = elements.foreach(f)
 
-  /** Is this collection empty?
+  /** Does this iterable contain no elements?
    */
   override def isEmpty: Boolean = !elements.hasNext
 
diff --git a/src/library/scala/collection/generic/ImmutableMapBuilder.scala b/src/library/scala/collection/generic/MapBuilder.scala
index 060e71a2d8..4f54447620 100644
--- a/src/library/scala/collection/generic/ImmutableMapBuilder.scala
+++ b/src/library/scala/collection/generic/MapBuilder.scala
@@ -12,15 +12,21 @@ package scala.collection.generic
 
 // import collection.immutable.{List, Nil, ::}
 
-/** The canonical builder for collections that are addable, i.e. that support an efficient + method
- *  which adds an element to the collection.
- *  Collections are built from their empty element using this + method.
+/** The canonical builder for immutable maps, working with the map's `+` method
+ *  to add new elements.
+ *  Collections are built from their `empty` element using this + method.
  *  @param empty   The empty element of the collection.
  */
-class ImmutableMapBuilder[A, B, Coll <: immutable.Map[A, B] with MapTemplate[A, B, Coll]](empty: Coll)
+class MapBuilder[A, B, Coll <: Map[A, B] with MapTemplate[A, B, Coll]](empty: Coll)
 extends Builder[(A, B), Coll] {
   protected var elems: Coll = empty
-  def +=(x: (A, B)): this.type = { elems = (elems + x).asInstanceOf[Coll]; this }
+  def +=(x: (A, B)): this.type = {
+    elems = (elems + x).asInstanceOf[Coll]
+      // the cast is necessary because right now we cannot enforce statically that
+      // for every map of type Coll, `+` yields again a Coll. With better support
+      // for hk-types we might be able to enforce this in the future, though.
+    this
+  }
   def clear() { elems = empty }
   def result: Coll = elems
 }
diff --git a/src/library/scala/collection/generic/MutableMapBuilder.scala b/src/library/scala/collection/generic/MutableMapBuilder.scala
deleted file mode 100644
index 1e55a3b069..0000000000
--- a/src/library/scala/collection/generic/MutableMapBuilder.scala
+++ /dev/null
@@ -1,26 +0,0 @@
-/*                     __                                               *\
-**     ________ ___   / /  ___     Scala API                            **
-**    / __/ __// _ | / /  / _ |    (c) 2003-2009, LAMP/EPFL             **
-**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
-** /____/\___/_/ |_/____/_/ | |                                         **
-**                          |/                                          **
-\*                                                                      */
-
-// $Id: ListBuffer.scala 14378 2008-03-13 11:39:05Z dragos $
-
-package scala.collection.generic
-
-// import collection.immutable.{List, Nil, ::}
-
-/** The canonical builder for collections that are addable, i.e. that support an efficient + method
- *  which adds an element to the collection.
- *  Collections are built from their empty element using this + method.
- *  @param empty   The empty element of the collection.
- */
-class MutableMapBuilder[A, B, Coll <: mutable.Map[A, B] with MapTemplate[A, B, Coll]](empty: Coll)
-extends Builder[(A, B), Coll] {
-  protected val elems: Coll = empty
-  def +=(x: (A, B)): this.type = { elems += x; this }
-  def clear() { elems.clear() }
-  def result: Coll = elems
-}
diff --git a/src/library/scala/collection/generic/MutableMapFactory.scala b/src/library/scala/collection/generic/MutableMapFactory.scala
index 09fc16cd02..7e33fc091f 100644
--- a/src/library/scala/collection/generic/MutableMapFactory.scala
+++ b/src/library/scala/collection/generic/MutableMapFactory.scala
@@ -5,5 +5,5 @@ package scala.collection.generic
 abstract class MutableMapFactory[CC[A, B] <: mutable.Map[A, B] with MutableMapTemplate[A, B, CC[A, B]]]
   extends MapFactory[CC] {
 
-  def newBuilder[A, B] = new MutableMapBuilder[A, B, CC[A, B]](empty[A, B])
+  def newBuilder[A, B] = new MapBuilder[A, B, CC[A, B]](empty[A, B])
 }
diff --git a/src/library/scala/collection/generic/MutableMapTemplate.scala b/src/library/scala/collection/generic/MutableMapTemplate.scala
index d7efc0bd0a..9ccb13787b 100644
--- a/src/library/scala/collection/generic/MutableMapTemplate.scala
+++ b/src/library/scala/collection/generic/MutableMapTemplate.scala
@@ -37,7 +37,10 @@ trait MutableMapTemplate[A, B, +This <: MutableMapTemplate[A, B, This] with muta
      with Cloneable[This]
 { self =>
 
-  override protected[this] def newBuilder: Builder[(A, B), This] = new MutableMapBuilder[A, B, This](empty.asInstanceOf[This]) // !!! concrete overrides abstract problem
+  /** A common implementation of `newBuilder` for all mutable maps in terms of `empty`.
+   *  Overrides `MapTemplate` implementation for better efficiency.
+   */
+  override protected[this] def newBuilder: Builder[(A, B), This] = empty
 
   /** Adds a new mapping from <code>key</code>
    *  to <code>value</code> to the map. If the map already contains a
@@ -60,7 +63,7 @@ trait MutableMapTemplate[A, B, +This <: MutableMapTemplate[A, B, This] with muta
    *  @return   An option consisting of value associated previously associated with `key` in the map,
    *            or None if `key` was not yet defined in the map.
    */
-  def update(key: A, elem: B) { this += ((key, elem)) }
+  def update(key: A, value: B) { this += ((key, value)) }
 
   /** Add a new key/value mapping this map.
    *  @param    kv the key/value pair.
@@ -195,6 +198,9 @@ trait MutableMapTemplate[A, B, +This <: MutableMapTemplate[A, B, This] with muta
     this
   }
 
+  /** @return the values of this map as a set */
+  override def valueSet: immutable.Set[B] = immutable.Set.empty[B] ++ (self map (_._2))
+
   override def clone(): This =
     empty ++ thisCollection
 
diff --git a/src/library/scala/collection/generic/MutableSetTemplate.scala b/src/library/scala/collection/generic/MutableSetTemplate.scala
index c0780ad66e..46134fcfee 100644
--- a/src/library/scala/collection/generic/MutableSetTemplate.scala
+++ b/src/library/scala/collection/generic/MutableSetTemplate.scala
@@ -35,6 +35,9 @@ trait MutableSetTemplate[A, +This <: MutableSetTemplate[A, This] with mutable.Se
      with Cloneable[This]
 { self =>
 
+  /** A common implementation of `newBuilder` for all mutable sets in terms of `empty`.
+   *  Overrides `SetTemplate` implementation for better efficiency.
+   */
   override protected[this] def newBuilder: Builder[A, This] = empty
 
   /** Adds a new element to the set.
@@ -68,8 +71,6 @@ trait MutableSetTemplate[A, +This <: MutableSetTemplate[A, This] with mutable.Se
     if (included) this += elem else this -= elem
   }
 
-
-
   /** Adds a new element to the set.
    *
    *  @param elem the element to be added
diff --git a/src/library/scala/collection/generic/SequenceTemplate.scala b/src/library/scala/collection/generic/SequenceTemplate.scala
index c8f321075f..8efbe9ebb8 100644
--- a/src/library/scala/collection/generic/SequenceTemplate.scala
+++ b/src/library/scala/collection/generic/SequenceTemplate.scala
@@ -15,7 +15,6 @@ import mutable.{ListBuffer, HashMap}
 
 // import immutable.{List, Nil, ::}
 import generic._
-import util.control.Breaks._
 
 /** Class <code>Sequence[A]</code> represents sequences of elements
  *  of type <code>A</code>.
@@ -31,6 +30,8 @@ import util.control.Breaks._
  */
 trait SequenceTemplate[+A, +This <: IterableTemplate[A, This] with Sequence[A]] extends IterableTemplate[A, This] { self =>
 
+  import Traversable.breaks._
+
   /** Returns the length of the sequence.
    *
    *  @return the sequence length.
diff --git a/src/library/scala/collection/generic/SetTemplate.scala b/src/library/scala/collection/generic/SetTemplate.scala
index ed706ab1bc..4556f81976 100644
--- a/src/library/scala/collection/generic/SetTemplate.scala
+++ b/src/library/scala/collection/generic/SetTemplate.scala
@@ -12,7 +12,7 @@ package scala.collection.generic
 
 /** A generic template for sets of type A.
  *  To implement a concrete set, you need to provide implementations of the following methods:
- *  (where This is the type of the set in question):
+ *  (where `This` is the type of the set in question):
  *
  *   def contains(key: A): Boolean
  *   def elements: Iterator[A]
@@ -29,7 +29,12 @@ package scala.collection.generic
 trait SetTemplate[A, +This <: SetTemplate[A, This] with Set[A]] extends IterableTemplate[A, This] with Addable[A, This] with Subtractable[A, This] {
 self =>
 
+  /* The empty set of the dame type as this set */
   def empty: This
+
+  /** A common implementation of `newBuilder` for all sets in terms of `empty`.
+   *  Overridden for mutable sets in `MutableSetTemplate`.
+   */
   override protected[this] def newBuilder: Builder[A, This] = new AddingBuilder[A, This](empty)
 
   /** Checks if this set contains element <code>elem</code>.
diff --git a/src/library/scala/collection/generic/Shrinkable.scala b/src/library/scala/collection/generic/Shrinkable.scala
index 227b47af44..c47ad2235b 100644
--- a/src/library/scala/collection/generic/Shrinkable.scala
+++ b/src/library/scala/collection/generic/Shrinkable.scala
@@ -12,7 +12,7 @@ package scala.collection.generic
 
 /** This class represents collections that can be reduced using a -= operator.
  *
- *  @autor   Martin Odersky
+ *  @author   Martin Odersky
  *  @owner   Martin Odersky
  *  @version 2.8
  */
diff --git a/src/library/scala/collection/generic/Subtractable.scala b/src/library/scala/collection/generic/Subtractable.scala
index 4847dedbff..8a0f3798c9 100644
--- a/src/library/scala/collection/generic/Subtractable.scala
+++ b/src/library/scala/collection/generic/Subtractable.scala
@@ -12,7 +12,7 @@ package scala.collection.generic
 
 /** This class represents collections that can be reduced using a -= operator.
  *
- *  @autor   Martin Odersky
+ *  @author   Martin Odersky
  *  @owner   Martin Odersky
  *  @version 2.8
  */
diff --git a/src/library/scala/collection/generic/TraversableForwarder.scala b/src/library/scala/collection/generic/TraversableForwarder.scala
index f3ab981526..7ed718edcd 100644
--- a/src/library/scala/collection/generic/TraversableForwarder.scala
+++ b/src/library/scala/collection/generic/TraversableForwarder.scala
@@ -35,6 +35,7 @@ trait TraversableForwarder[+A] extends Traversable[A] {
   // Iterable methods could be printed by  cat IterableTemplate.scala | sed -n '/trait Iterable/,$ p' | egrep '^  (override )?def'
 
   override def isEmpty = underlying.isEmpty
+  override def nonEmpty = underlying.nonEmpty
   override def hasDefiniteSize = underlying.hasDefiniteSize
   override def foreach[B](f: A => B) = underlying.foreach(f)
   override def forall(p: A => Boolean): Boolean = underlying.forall(p)
@@ -45,8 +46,8 @@ trait TraversableForwarder[+A] extends Traversable[A] {
   override def foldRight[B](z: B)(op: (A, B) => B): B = underlying.foldRight(z)(op)
   override def reduceLeft[B >: A](op: (B, A) => B): B = underlying.reduceLeft(op)
   override def reduceRight[B >: A](op: (A, B) => B): B = underlying.reduceRight(op)
-  override def reduceLeftOpt[B >: A](op: (B, A) => B): Option[B] = underlying.reduceLeftOpt(op)
-  override def reduceRightOpt[B >: A](op: (A, B) => B): Option[B] = underlying.reduceRightOpt(op)
+  override def reduceLeftOption[B >: A](op: (B, A) => B): Option[B] = underlying.reduceLeftOption(op)
+  override def reduceRightOption[B >: A](op: (A, B) => B): Option[B] = underlying.reduceRightOption(op)
   override def copyToBuffer[B >: A](dest: Buffer[B]) = underlying.copyToBuffer(dest)
   override def copyToArray[B >: A](xs: Array[B], start: Int, len: Int) = underlying.copyToArray(xs, start, len)
   override def toArray[B >: A]: Array[B] = underlying.toArray
diff --git a/src/library/scala/collection/generic/TraversableProxyTemplate.scala b/src/library/scala/collection/generic/TraversableProxyTemplate.scala
index a7ec343827..ab358cbe66 100644
--- a/src/library/scala/collection/generic/TraversableProxyTemplate.scala
+++ b/src/library/scala/collection/generic/TraversableProxyTemplate.scala
@@ -46,9 +46,9 @@ trait TraversableProxyTemplate[+A, +This <: TraversableTemplate[A, This] with Tr
   override def foldRight[B](z: B)(op: (A, B) => B): B = self.foldRight(z)(op)
   override def :\ [B](z: B)(op: (A, B) => B): B = self.:\(z)(op)
   override def reduceLeft[B >: A](op: (B, A) => B): B = self.reduceLeft(op)
-  override def reduceLeftOpt[B >: A](op: (B, A) => B): Option[B] = self.reduceLeftOpt(op)
+  override def reduceLeftOption[B >: A](op: (B, A) => B): Option[B] = self.reduceLeftOption(op)
   override def reduceRight[B >: A](op: (A, B) => B): B = self.reduceRight(op)
-  override def reduceRightOpt[B >: A](op: (A, B) => B): Option[B] = self.reduceRightOpt(op)
+  override def reduceRightOption[B >: A](op: (A, B) => B): Option[B] = self.reduceRightOption(op)
   override def head: A = self.head
   override def headOption: Option[A] = self.headOption
   override def tail: This = self.tail
diff --git a/src/library/scala/collection/generic/TraversableTemplate.scala b/src/library/scala/collection/generic/TraversableTemplate.scala
index 9992df1a95..a6aec19331 100644
--- a/src/library/scala/collection/generic/TraversableTemplate.scala
+++ b/src/library/scala/collection/generic/TraversableTemplate.scala
@@ -11,7 +11,6 @@ package scala.collection.generic
 
 // import immutable.{List, Stream, Nil} //!!!
 import mutable.{Buffer, ArrayBuffer, ListBuffer}
-import util.control.Breaks._
 
 /** A template trait for traversable collections.
  *  This is a base trait of all kinds of Scala collections. It implements the
@@ -50,14 +49,26 @@ import util.control.Breaks._
 trait TraversableTemplate[+A, +This <: TraversableTemplate[A, This] with Traversable[A]] {
 self =>
 
+  import Traversable.breaks._
+
   /** The proper way to do this would be to make `self` of type `This`. But unfortunately this
    *  makes `this` to be of type `Traversable[A]`. Since `Traversable` is a subtype of
-   *  `TraversableTemplate` this means that all methods of `this` are taken from `Traversable`.
+   *  `TraversableTemplate`, all methods of `this` are taken from `Traversable`. In particular
+   *  the `newBuilder` method is taken from `Traversable`, which means it yields a `Traversable[A]`
+   *  instyead of a `This`.
+   *
+   *  The right way out of this is to change Scala's member selection rules, so that
+   *  always the most specific type will be selected, no matter whether a member is abstract
+   *  or concrete. I tried to fake this by having a method `thisTemplate` which
+   *  returns this at the Template type. But unfortunately that does not work, because
+   *  we need to call `newBuilder` on this at the Template type (so that we get back a `This`)
+   *  and `newBuilder` has to be a proctected[this] because of variance.
+   *  The less appealing alternative is implemented now: Forget the self type and
+   *  introduce a `thisCollection` which is this seen as an instance of `This`.
+   *  We should go back to this once we have ameliorated Scala's member selection rules.
    */
   protected def thisCollection: This = this.asInstanceOf[This]
 
-  protected def thisTemplate: TraversableTemplate[A, This] = this
-
   /** Create a new builder for this collection type.
    */
   protected[this] def newBuilder: Builder[A, This]
@@ -94,9 +105,7 @@ self =>
    */
   def size: Int = {
     var result = 0
-    breakable {
-      for (x <- this) result += 1
-    }
+    for (x <- this) result += 1
     result
   }
 
@@ -362,7 +371,7 @@ self =>
    *  @param op  The operator to apply
    *  @return  If the traversable is non-empty, the result of the operations as an Option, otherwise None.
    */
-  def reduceLeftOpt[B >: A](op: (B, A) => B): Option[B] = {
+  def reduceLeftOption[B >: A](op: (B, A) => B): Option[B] = {
     if (isEmpty) None else Some(reduceLeft(op))
   }
 
@@ -394,7 +403,7 @@ self =>
    *  @param op  The operator to apply
    *  @return  If the iterable is non-empty, the result of the operations as an Option, otherwise None.
    */
-  def reduceRightOpt[B >: A](op: (A, B) => B): Option[B] = {
+  def reduceRightOption[B >: A](op: (A, B) => B): Option[B] = {
     if (isEmpty) None else Some(reduceRight(op))
   }
 
@@ -781,5 +790,3 @@ self =>
    */
   def view(from: Int, until: Int): TraversableView[A, This] = view.slice(from, until)
 }
-
-
diff --git a/src/library/scala/collection/immutable/Iterable.scala b/src/library/scala/collection/immutable/Iterable.scala
index bcc3951965..31d7d6db8d 100644
--- a/src/library/scala/collection/immutable/Iterable.scala
+++ b/src/library/scala/collection/immutable/Iterable.scala
@@ -6,7 +6,7 @@ import generic._
  *  that cannot be mutated.
  *
  *  @author  Matthias Zenger
- *  @autor   Martin Odersky
+ *  @author   Martin Odersky
  *  @version 2.8
  */
 trait Iterable[+A] extends Traversable[A]
diff --git a/src/library/scala/collection/immutable/Traversable.scala b/src/library/scala/collection/immutable/Traversable.scala
index ffb389212b..398a0264c8 100644
--- a/src/library/scala/collection/immutable/Traversable.scala
+++ b/src/library/scala/collection/immutable/Traversable.scala
@@ -6,7 +6,7 @@ import generic._
  *  that cannot be mutated.
  *  !!! todo: revise equality
  *  @author  Matthias Zenger
- *  @autor   Martin Odersky
+ *  @author   Martin Odersky
  *  @version 2.8
  */
 trait Traversable[+A] extends collection.Traversable[A]
diff --git a/src/library/scala/collection/mutable/Iterable.scala b/src/library/scala/collection/mutable/Iterable.scala
index 18ca5588d6..66c678adb9 100644
--- a/src/library/scala/collection/mutable/Iterable.scala
+++ b/src/library/scala/collection/mutable/Iterable.scala
@@ -12,7 +12,7 @@ import generic._
 /** A subtrait of collection.Iterable which represents iterables
  *  that can be mutated.
  *
- *  @autor   Martin Odersky
+ *  @author   Martin Odersky
  *  @version 2.8
  */
 trait Iterable[A] extends Traversable[A]
diff --git a/src/library/scala/collection/mutable/Traversable.scala b/src/library/scala/collection/mutable/Traversable.scala
index 46a99c7b42..f6d2433be2 100644
--- a/src/library/scala/collection/mutable/Traversable.scala
+++ b/src/library/scala/collection/mutable/Traversable.scala
@@ -12,7 +12,7 @@ import generic._
 /** A subtrait of collection.Traversable which represents traversables
  *  that can be mutated.
  *
- *  @autor   Martin Odersky
+ *  @author   Martin Odersky
  *  @version 2.8
  */
 trait Traversable[A] extends collection.Traversable[A]
diff --git a/src/library/scala/util/control/Breaks.scala b/src/library/scala/util/control/Breaks.scala
index 12a06c0d1c..a6d6686c72 100755
--- a/src/library/scala/util/control/Breaks.scala
+++ b/src/library/scala/util/control/Breaks.scala
@@ -1,23 +1,37 @@
 package scala.util.control
 
-object Breaks {
-  private class BreakException extends RuntimeException
+/** An object that can be used for the break control abstraction.
+ *  Example usage:
+ *
+ *  import Breaks.{break, breakable}
+ *
+ *  breakable {
+ *    for (...) {
+ *      if (...) break
+ *    }
+ *  }
+ *
+ */
+class Breaks {
+
   private val breakException = new BreakException
-  private class ContinueException extends RuntimeException
-  private val continueException = new ContinueException
 
-  /** A block from which one can exit with a `break' and which can be resumed with a `continue'. */
+  /** A block from which one can exit with a `break''. */
   def breakable(op: => Unit) {
     try {
       op
     } catch {
       case ex: BreakException =>
+        if (ex ne breakException) throw ex
     }
   }
 
   /* Break from closest enclosing breakable block */
   def break { throw breakException }
-
-  /* Continue with start of closest enclosing breakable block */
-  def continue { throw continueException }
 }
+
+/** A singleton object providing the Break functionality */
+object Breaks extends Breaks
+
+private class BreakException extends RuntimeException
+