lost of documentation and some small adjustment...

lost of documentation and some small adjustments to collection classes.

34 files changed, 1160 insertions, 969 deletions

diff --git a/src/library/scala/PartialFunction.scala b/src/library/scala/PartialFunction.scala
index 37464421f9..81ca2e4e10 100644
--- a/src/library/scala/PartialFunction.scala
+++ b/src/library/scala/PartialFunction.scala
@@ -11,9 +11,9 @@
 
 package scala
 
-/** A partial function of type <code>PartialFunction[A, B]</code> is a
+/** A partial function of type `PartialFunction[A, B]` is a
  *  unary function where the domain does not necessarily include all values of type
- *  <code>A</code>. The function <code>isDefinedAt</code> allows to
+ *  `A`. The function `isDefinedAt` allows to
  *  test dynamically if a value is in the domain of the function.
  *
  *  @author  Martin Odersky
@@ -24,7 +24,7 @@ trait PartialFunction[-A, +B] extends (A => B) {
   /** Checks if a value is contained in the function's domain.
    *
    *  @param  x   the value to test
-   *  @return `true`, iff <code>x</code> is in the domain of this function, `false` otherwise.
+   *  @return `true`, iff `x` is in the domain of this function, `false` otherwise.
    */
   def isDefinedAt(x: A): Boolean
 
@@ -90,7 +90,7 @@ object PartialFunction
    *
    *  @param  x   the value to test
    *  @param  pf  the partial function
-   *  @return true, iff <code>x</code> is in the domain of pf && pf(x) == true
+   *  @return true, iff `x` is in the domain of `pf` and `pf(x) == true`.
    */
   def cond[T](x: T)(pf: PartialFunction[T, Boolean]): Boolean =
     (pf isDefinedAt x) && pf(x)
@@ -102,7 +102,7 @@ object PartialFunction
    *
    *  @param  x     the value to test
    *  @param  pf    the PartialFunction[T,U]
-   *  @return Some(pf(x)) iff (pf isDefinedAt x) and None otherwise
+   *  @return `Some(pf(x))` if `pf isDefinedAt x`, `None` otherwise.
    */
   def condOpt[T,U](x: T)(pf: PartialFunction[T, U]): Option[U] =
     if (pf isDefinedAt x) Some(pf(x)) else None
diff --git a/src/library/scala/collection/BitSet.scala b/src/library/scala/collection/BitSet.scala
index 136e623cef..abb4856bcd 100644
--- a/src/library/scala/collection/BitSet.scala
+++ b/src/library/scala/collection/BitSet.scala
@@ -13,8 +13,11 @@ package scala.collection
 
 import generic._
 
-/** common base class for mutable and immutable bit sets
- *
+/** A common base class for mutable and immutable bitsets.
+ *  $bitsetinfo
+
+ *  @author Martin Odersky
+ *  @version 2.8
  *  @since 1
  */
 trait BitSet extends Set[Int]
@@ -22,11 +25,10 @@ trait BitSet extends Set[Int]
   override def empty: BitSet = BitSet.empty
 }
 
-/** A factory object for bitsets
- *
- *  @since 2.8
- */
+/** $factoryInfo */
 object BitSet extends BitSetFactory[BitSet] {
   val empty: BitSet = immutable.BitSet.empty
+  /** $canBuildFromInfo */
+  implicit def canBuildFrom: CanBuildFrom[BitSet, Int, BitSet] = bitsetCanBuildFrom
 }
 
diff --git a/src/library/scala/collection/BitSetLike.scala b/src/library/scala/collection/BitSetLike.scala
index 0e13a5f8b5..aac731fec9 100644
--- a/src/library/scala/collection/BitSetLike.scala
+++ b/src/library/scala/collection/BitSetLike.scala
@@ -15,9 +15,24 @@ import BitSetLike._
 import generic._
 import mutable.StringBuilder
 
-/** common base class for mutable and immutable bit sets
+/** A template trait for bitsets.
+ *  $bitsetinfo
  *
+ * This trait provides most of the operations of a `BitSet` independently of its representation.
+ * It is inherited by all concrete implementations of bitsets.
+ *
+ * @tparam  This the type of the bitset itself.
+ *
+ *  @author  Martin Odersky
+ *  @version 2.8
  *  @since 2.8
+ *  @define coll bitset
+ *  @define Coll BitSet
+ *  define bitsetinfo
+ *  Bitsets are sets of non-negative integers which are represented as
+ *  variable-size arrays of bits packed into 64-bit words. The size of a bitset is
+ *  determined by the largest number stored in it.
+
  */
 trait BitSetLike[+This <: BitSetLike[This] with Set[Int]] extends SetLike[Int, This] { self =>
 
@@ -31,12 +46,10 @@ trait BitSetLike[+This <: BitSetLike[This] with Set[Int]] extends SetLike[Int, T
    */
   protected def word(idx: Int): Long
 
-  /** Create a new set of this kind from an array of longs
+  /** Creates a new set of this kind from an array of longs
    */
   protected def fromArray(elems: Array[Long]): This
 
-  /** The number of elements in the bitset.
-   */
   override def size: Int = {
     var s = 0
     var i = nwords
@@ -68,7 +81,12 @@ trait BitSetLike[+This <: BitSetLike[This] with Set[Int]] extends SetLike[Int, T
     }
   }
 
-  /** A new bitset which is the logical or of this set and the given argument set.
+  /** Computes the union between this bitset and another bitset by performing
+   *  a bitwise "or".
+   *
+   *  @param   other  the bitset to form the union with.
+   *  @return  a new bitset consisting of all bits that are in this
+   *           bitset or in the given bitset `other`.
    */
   def | (other: BitSet): This = {
     val len = this.nwords max other.nwords
@@ -78,7 +96,11 @@ trait BitSetLike[+This <: BitSetLike[This] with Set[Int]] extends SetLike[Int, T
     fromArray(words)
   }
 
-  /** A new bitset which is the logical and of this set and the given argument set.
+  /** Computes the intersection between this bitset and another bitset by performing
+   *  a bitwise "and".
+   *  @param   that  the bitset to intersect with.
+   *  @return  a new bitset consisting of all elements that are both in this
+   *  bitset and in the given bitset `other`.
    */
   def & (other: BitSet): This = {
     val len = this.nwords min other.nwords
@@ -88,7 +110,12 @@ trait BitSetLike[+This <: BitSetLike[This] with Set[Int]] extends SetLike[Int, T
     fromArray(words)
   }
 
-  /** A new bitset which is the logical and-not of this set and the given argument set.
+  /** Computes the difference of this bitset and another bitset by performing
+   *  a bitwise "and-not".
+   *
+   *  @param that the set of bits to exclude.
+   *  @return     a bitset containing those bits of this
+   *              bitset that are not also contained in the given bitset `other`.
    */
   def &~ (other: BitSet): This = {
     val len = this.nwords
@@ -98,7 +125,12 @@ trait BitSetLike[+This <: BitSetLike[This] with Set[Int]] extends SetLike[Int, T
     fromArray(words)
   }
 
-  /** A new bitset which is the logical exclusive or of this set and the given argument set.
+  /** Computes the symmetric difference of this bitset and another bitset by performing
+   *  a bitwise "exclusive-or".
+   *
+   *  @param that the other bitset to take part in the symmetric difference.
+   *  @return     a bitset containing those bits of this
+   *              bitset or the other bitset that are not contained in both bitsets.
    */
   def ^ (other: BitSet): This = {
     val len = this.nwords max other.nwords
@@ -108,18 +140,18 @@ trait BitSetLike[+This <: BitSetLike[This] with Set[Int]] extends SetLike[Int, T
     fromArray(words)
   }
 
-  /** Does the set contain the given element?
-   */
   def contains(elem: Int): Boolean =
     0 <= elem && (word(elem >> LogWL) & (1L << elem)) != 0L
 
-  /** Is the set a subset of the given bitset
+  /** Tests whether this bitset is a subset of another bitset.
+   *
+   *  @param that  the bitset to test.
+   *  @return     `true` if this bitset is a subset of `other`, i.e. if
+   *              every bit of this set is also an element in `other`.
    */
-  def subSet(other: BitSet): Boolean =
+  def subsetOf(other: BitSet): Boolean =
     (0 until nwords) forall (idx => (this.word(idx) & ~ other.word(idx)) == 0L)
 
-  /** Add bitset elements as numbers to string buffer
-   */
   override def addString(sb: StringBuilder, start: String, sep: String, end: String) = {
     sb append start
     var pre = ""
@@ -134,6 +166,7 @@ trait BitSetLike[+This <: BitSetLike[This] with Set[Int]] extends SetLike[Int, T
   override def stringPrefix = "BitSet"
 }
 
+/** Companion object for BitSets. Contains private data only */
 object BitSetLike {
   private[collection] val LogWL = 6
   private val WordLength = 64
diff --git a/src/library/scala/collection/IndexedSeqLike.scala b/src/library/scala/collection/IndexedSeqLike.scala
index 7951dc99c5..8164075629 100644
--- a/src/library/scala/collection/IndexedSeqLike.scala
+++ b/src/library/scala/collection/IndexedSeqLike.scala
@@ -31,6 +31,8 @@ import scala.annotation.tailrec
  *
  *  @tparam A    the element type of the $coll
  *  @tparam Repr the type of the actual $coll containing the elements.
+ *  @define willNotTerminateInf
+ *  @define mayNotTerminateInf
  */
 trait IndexedSeqLike[+A, +Repr] extends SeqLike[A, Repr] { self =>
 
diff --git a/src/library/scala/collection/Iterable.scala b/src/library/scala/collection/Iterable.scala
index 4c4e152483..ba5eb4c0a0 100644
--- a/src/library/scala/collection/Iterable.scala
+++ b/src/library/scala/collection/Iterable.scala
@@ -15,32 +15,7 @@ import generic._
 import scala.util.control.Breaks._
 import mutable.Builder
 
-/** <p>
- *    A template trait for iterable collections.
- *  </p>
- *  <p>
- *    Collection classes mixing in this trait provide a method
- *    <code>iterator</code> which returns an iterator over all the
- *    elements contained in the collection. They also provide a method
- *    <code>newBuilder</code> which creates a builder for collections
- *    of the same kind.
- *  </p>
- *  <p>
- *    This trait implements <code>Traversable</code>'s <code>foreach</code>
- *    method by stepping through all elements. Subclasses of <code>Iterable</code>
- *    should re-implement <code>foreach</code> with something more efficient,
- *    if possible.
- *  </p>
- *  <p>
- *    This trait adds methods <code>iterator</code>, <code>zip</code>,
- *    <code>zipAll</code>, <code>zipWithIndex</code>, <code>sameElements</code>,
- *    <code>takeRight</code>, <code>dropRight</code> to the methods inherited
- *    from trait <code>Traversable</code>.
- *  </p>
- *
- *  @author Martin Odersky
- *  @version 2.8
- *  @since   2.8
+/** $iterableInfo
  */
 trait Iterable[+A] extends Traversable[A]
                       with GenericTraversableTemplate[A, Iterable]
@@ -59,22 +34,21 @@ trait Iterable[+A] extends Traversable[A]
 
 }
 
-/** Factory methods and utilities for instances of type <code>Iterable</code>.
- *
- *  @author Martin Odersky
- *  @version 2.8
+/** $factoryInfo
  */
 object Iterable extends TraversableFactory[Iterable] {
 
+  /** $genericCanBuildFromInfo */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Iterable[A]] = new GenericCanBuildFrom[A]
+
   def newBuilder[A]: Builder[A, Iterable[A]] = immutable.Iterable.newBuilder[A]
 
   /** The minimum element of a non-empty sequence of ordered elements */
-  @deprecated("use seq.min instead")
+  @deprecated("use <seq>.min instead, where <seq> is the sequence for which you want to compute the minimum")
   def min[A](seq: Iterable[A])(implicit ord: Ordering[A]): A = seq.min
 
   /** The maximum element of a non-empty sequence of ordered elements */
-  @deprecated("use seq.max instead")
+  @deprecated("use <seq>.max instead, where <seq> is the sequence for which you want to compute the maximum")
   def max[A](seq: Iterable[A])(implicit ord: Ordering[A]): A = seq.max
 
   @deprecated("use View instead")
diff --git a/src/library/scala/collection/IterableLike.scala b/src/library/scala/collection/IterableLike.scala
index 41dc774cd9..06db5fb6fc 100644
--- a/src/library/scala/collection/IterableLike.scala
+++ b/src/library/scala/collection/IterableLike.scala
@@ -13,40 +13,38 @@ import generic._
 import immutable.{List, Stream}
 import annotation.unchecked.uncheckedVariance
 
-/** <p>
- *    A template trait for iterable collections of type `Iterable[A]`.
- *  </p>
- *  <p>
- *    Collection classes mixing in this trait provide a method
- *    <code>iterator</code> which returns an iterator over all the
- *    elements contained in the collection. They also provide a method
- *    <code>newBuilder</code> which creates a builder for collections of the
- *    same kind.
- *  </p>
- *  <p>
- *    This trait implements <code>Iterable</code>'s <code>foreach</code>
- *    method by stepping through all elements. Subclasses of <code>Iterable</code>
- *    should re-implement <code>foreach</code> with something more efficient,
- *    if possible.
- *  </p>
- *  <p>
- *    This trait adds methods <code>iterator</code>, <code>sameElements</code>,
- *    <code>takeRight</code>, <code>dropRight</code> to the methods inherited
- *    from trait <a href="../Iterable.html" target="ContentFrame">
- *    <code>Iterable</code></a>.
- *  </p>
- *
- *  Note: This trait replaces every method that uses breaks in the original by an iterator version.
+/** A template trait for iterable collections of type `Iterable[A]`.
+ *  $iterableInfo
+ *  @tparam A    the element type of the collection
+ *  @tparam Repr the type of the actual collection containing the elements.
+ *  @define iterableInfo
+ *    This is a base trait for all scala collections that define an `iterator`
+ *    method to step through one-by-one the collection's elements.
+ *    Implementations of this trait need to provide a concrete method with
+ *    signature:
+ *    {{{
+ *       def iterator: Iterator[A]
+ *    }}}
+ *    They also need to provide a method `newBuilder`
+ *    which creates a builder for collections of the same kind.
  *
- *  @see Iterable
+ *    This trait implements `Iterable`'s `foreach`
+ *    method by stepping through all elements using `iterator`.
+ *    Subclasses should re-implement `foreach` with something more efficient,
+ *    if possible.
+
+ *    This trait adds methods `iterator`, `sameElements`,
+ *    `takeRight`, `dropRight` to the methods inherited
+ *    from trait <a href="../Traversable.html" target="ContentFrame">
+ *    `Traversable`</a>.
+
+ *    Note: This trait replaces every method that uses `break` in
+ *    `TraversableLike` by an iterator version.
  *
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   2.8
  *
- *  @tparam A    the element type of the collection
- *  @tparam Repr the type of the actual collection containing the elements.
- *
  *  @define Coll Iterable
  *  @define coll iterable collection
  *  @define zipthatinfo the class of the returned collection. Where possible, `That` is
@@ -337,19 +335,16 @@ self =>
 
   override /*TraversableLike*/ def view(from: Int, until: Int) = view.slice(from, until)
 
-  /** @deprecated use `head' instead. */
   @deprecated("use `head' instead") def first: A = head
 
-  /** <code>None</code> if iterable is empty.
-   *  @deprecated "use `headOption' instead"
+  /** `None` if iterable is empty.
    */
   @deprecated("use `headOption' instead") def firstOption: Option[A] = headOption
 
   /**
-   * returns a projection that can be used to call non-strict <code>filter</code>,
-   * <code>map</code>, and <code>flatMap</code> methods that build projections
+   * returns a projection that can be used to call non-strict `filter`,
+   * `map`, and `flatMap` methods that build projections
    * of the collection.
-   * @deprecated "use `view' instead"
    */
   @deprecated("use `view' instead")
   def projection = view
diff --git a/src/library/scala/collection/Iterator.scala b/src/library/scala/collection/Iterator.scala
index b4b71be8e1..61eabefe8b 100644
--- a/src/library/scala/collection/Iterator.scala
+++ b/src/library/scala/collection/Iterator.scala
@@ -15,7 +15,7 @@ import mutable.{Buffer, ArrayBuffer, ListBuffer, StringBuilder}
 import immutable.{List, Stream}
 import annotation.{ tailrec }
 
-/** The <code>Iterator</code> object provides various functions for
+/** The `Iterator` object provides various functions for
  *  creating specialized iterators.
  *
  *  @author  Martin Odersky
@@ -25,13 +25,16 @@ import annotation.{ tailrec }
  */
 object Iterator {
 
+  /** The iterator which produces no values */
   val empty = new Iterator[Nothing] {
     def hasNext: Boolean = false
     def next(): Nothing = throw new NoSuchElementException("next on empty iterator")
   }
 
-  /** An iterator with a single element.
+  /** Creates an iterator which produces a single element.
    *  @param elem the element
+   *  @return An iterator which produces `elem` on the first call to `next`,
+   *          and which has no further elements.
    *  @note  Equivalent, but more efficient than Iterator(elem)
    */
   def single[A](elem: A) = new Iterator[A] {
@@ -44,12 +47,16 @@ object Iterator {
 
   /** Creates an iterator with given elements
    *  @param elems  The elements returned one-by-one from the iterator
+   *  @return An iterator which produces the given elements on the
+   *          first calls to `next`, and which has no further elements.
    */
   def apply[A](elems: A*): Iterator[A] = elems.iterator
 
-  /** An iterator that returns the results of some element computation a number of times.
-   *  @param   len  The number of elements returned
-   *  @param   elem The element computation determinining each result
+  /** Creates iterator that produces the results of some element computation
+   *  a number of times.
+   *  @param   n  the number of elements returned by the iterator.
+   *  @param   elem the element computation
+   *  @return  An iterator that produces the results of `n` evaluations of `elem`.
    */
   def fill[A](len: Int)(elem: => A) = new Iterator[A] {
     private var i = 0
@@ -59,12 +66,10 @@ object Iterator {
       else empty.next()
   }
 
-  /** An iterator that returns values of a given function over a range of
-   *  integer values starting from 0.
-   *
-   *  @param end   The argument up to which values are tabulated.
-   *  @param f     The function computing the results
-   *  @return  An iterator with values `f(0) ... f(end-1)`
+  /** Creates an iterator producing the values of a given function over a range of integer values starting from 0.
+   *  @param  n   The number of elements returned by the iterator
+   *  @param  f   The function computing element values
+   *  @return An iterator that produces the values `f(0), ..., f(n -1)`.
    */
   def tabulate[A](end: Int)(f: Int => A) = new Iterator[A] {
     private var i = 0
@@ -74,20 +79,20 @@ object Iterator {
       else empty.next()
   }
 
-  /** An iterator returning successive values in some integer interval.
+  /** Creates nn iterator returning successive values in some integer interval.
    *
    *  @param start the start value of the iterator
    *  @param end   the end value of the iterator (the first value NOT returned)
-   *  @return      the iterator with values in range `start, start + 1, ..., end - 1`
+   *  @return      the iterator producing values `start, start + 1, ..., end - 1`
    */
   def range(start: Int, end: Int): Iterator[Int] = range(start, end, 1)
 
-  /** An iterator returning equally spaced values in some integer interval.
+  /** An iterator producing equally spaced values in some integer interval.
    *
    *  @param start the start value of the iterator
    *  @param end   the end value of the iterator (the first value NOT returned)
    *  @param step  the increment value of the iterator (must be positive or negative)
-   *  @return      the iterator with values in `start, start + step, ...` up to, but excluding `end`
+   *  @return      the iterator producing values `start, start + step, ...` up to, but excluding `end`
    */
   def range(start: Int, end: Int, step: Int) = new Iterator[Int] {
     if (step == 0) throw new IllegalArgumentException("zero step")
@@ -98,11 +103,11 @@ object Iterator {
       else empty.next()
   }
 
-  /** An infinite iterator that repeatedly applies a given function to the previous result.
+  /** Creates an infinite iterator that repeatedly applies a given function to the previous result.
    *
    *  @param start the start value of the iterator
    *  @param f     the function that's repeatedly applied
-   *  @return      the iterator returning the infinite sequence of values `start, f(start), f(f(start)), ...`
+   *  @return      the iterator producing the infinite sequence of values `start, f(start), f(f(start)), ...`
    */
   def iterate[T](start: T)(f: T => T): Iterator[T] = new Iterator[T] {
     private[this] var acc = start
@@ -110,18 +115,18 @@ object Iterator {
     def next(): T = { val res = acc ; acc = f(acc) ; res }
   }
 
-  /** An infinite-length iterator which returns successive values from some start value.
+  /** Creates an infinite-length iterator which returns successive values from some start value.
 
    *  @param start the start value of the iterator
-   *  @return      the iterator returning the infinite sequence of values `start, start + 1, start + 2, ...`
+   *  @return      the iterator producing the infinite sequence of values `start, start + 1, start + 2, ...`
    */
   def from(start: Int): Iterator[Int] = from(start, 1)
 
-  /** An infinite-length iterator returning values equally spaced apart.
+  /** Creates an infinite-length iterator returning values equally spaced apart.
    *
    *  @param start the start value of the iterator
    *  @param step  the increment between successive values
-   *  @return      the iterator returning the infinite sequence of values `start, start + 1 * step, start + 2 * step, ...`
+   *  @return      the iterator producing the infinite sequence of values `start, start + 1 * step, start + 2 * step, ...`
    */
   def from(start: Int, step: Int): Iterator[Int] = new Iterator[Int] {
     private var i = start
@@ -129,19 +134,19 @@ object Iterator {
     def next(): Int = { val result = i; i += step; result }
   }
 
-  /** Create an infinite iterator based on the given expression
-   *  (which is recomputed for every element)
+  /** Creates an infinite-length iterator returning the results of evaluating
+   *  an expression. The epxression is recomputed for every element.
    *
-   *  @param elem the element composing the resulting iterator
-   *  @return the iterator containing an infinite number of elem
+   *  @param elem the element computation.
+   *  @return the iterator containing an infinite number of results of evaluating `elem`.
    */
   def continually[A](elem: => A): Iterator[A] = new Iterator[A] {
     def hasNext = true
     def next = elem
   }
 
-  /** A wrapper class for the <code>flatten</code> method that is added to
-   *  class <code>Iterator</code> with implicit conversion
+  /** A wrapper class for the `flatten` method that is added to
+   *  class `Iterator` with implicit conversion
    *  @see iteratorIteratorWrapper.
    */
   class IteratorIteratorOps[A](its: Iterator[Iterator[A]]) {
@@ -162,8 +167,7 @@ object Iterator {
   @deprecated("use `xs.iterator' or `Iterator(xs)' instead")
   def fromValues[a](xs: a*) = xs.iterator
 
-  /**
-   *  @param xs the array of elements
+  /** @param xs the array of elements
    *  @see also: IndexedSeq.iterator and slice
    */
   @deprecated("use `xs.iterator' instead")
@@ -182,7 +186,7 @@ object Iterator {
 
   /**
    *  @param n the product arity
-   *  @return  the iterator on <code>Product&lt;n&gt;</code>.
+   *  @return  the iterator on `Product&lt;n&gt;`.
    */
   @deprecated("use product.productIterator instead")
   def fromProduct(n: Product): Iterator[Any] = new Iterator[Any] {
@@ -193,15 +197,15 @@ object Iterator {
   }
 
   /** Create an iterator with elements
-   *  <code>e<sub>n+1</sub> = step(e<sub>n</sub>)</code>
-   *  where <code>e<sub>0</sub> = start</code>
-   *  and elements are in the range between <code>start</code> (inclusive)
-   *  and <code>end</code> (exclusive)
+   *  `e<sub>n+1</sub> = step(e<sub>n</sub>)`
+   *  where `e<sub>0</sub> = start`
+   *  and elements are in the range between `start` (inclusive)
+   *  and `end` (exclusive)
    *
    *  @param start the start value of the iterator
    *  @param end   the end value of the iterator
    *  @param step  the increment function of the iterator, must be monotonically increasing or decreasing
-   *  @return      the iterator with values in range <code>[start;end)</code>.
+   *  @return      the iterator with values in range `[start;end)`.
    */
   @deprecated("use Iterator.iterate(start, end - start)(step) instead")
   def range(start: Int, end: Int, step: Int => Int) = new Iterator[Int] {
@@ -215,12 +219,12 @@ object Iterator {
   }
 
   /** Create an iterator with elements
-   *  <code>e<sub>n+1</sub> = step(e<sub>n</sub>)</code>
-   *  where <code>e<sub>0</sub> = start</code>.
+   *  `e<sub>n+1</sub> = step(e<sub>n</sub>)`
+   *  where `e<sub>0</sub> = start`.
    *
    *  @param start the start value of the iterator
    *  @param step  the increment function of the iterator
-   *  @return      the iterator starting at value <code>start</code>.
+   *  @return      the iterator starting at value `start`.
    */
   @deprecated("use iterate(start)(step) instead")
   def from(start: Int, step: Int => Int): Iterator[Int] = new Iterator[Int] {
@@ -249,29 +253,32 @@ object Iterator {
 import Iterator.empty
 
 /** Iterators are data structures that allow to iterate over a sequence
- *  of elements. They have a <code>hasNext</code> method for checking
- *  if there is a next element available, and a <code>next</code> method
+ *  of elements. They have a `hasNext` method for checking
+ *  if there is a next element available, and a `next` method
  *  which returns the next element and discards it from the iterator.
  *
  *  @author  Martin Odersky, Matthias Zenger
  *  @version 2.8
- *  @since   2.8
+ *  @since   1
  */
 trait Iterator[+A] { self =>
 
-  /** Does this iterator provide another element?
+  /** Tests whether this iterator can provide another element.
+   *  @return  `true` if a subsequent call to `next` will yield an element,
+   *           `false` otherwise.
    */
   def hasNext: Boolean
 
-  /** Returns the next element of this iterator.
+  /** Produces the next element of this iterator.
+   *  @return  the next element of this iterator, if `hasNext` is `true`,
+   *           undefined behavior otherwise.
    */
   def next(): A
 
-  /** Returns a new iterator that iterates only over the first <code>n</code>
-   *  elements of this iterator, or the length of the iterator, whichever is smaller.
-   *
-   *  @param n the number of elements to take
-   *  @return  the new iterator
+  /** Selects first ''n'' values of this iterator.
+   *  @param  n    the number of values to take
+   *  @return an iterator producing only of the first `n` values of this iterator, or else the
+   *          whole iterator, if it produces less than `n` values.
    */
   def take(n: Int): Iterator[A] = new Iterator[A] {
     private var remaining = n
@@ -281,11 +288,12 @@ trait Iterator[+A] { self =>
       else empty.next()
   }
 
-  /** Advances this iterator past the first <code>n</code> elements,
+  /** Advances this iterator past the first ''n'' elements,
    *  or the length of the iterator, whichever is smaller.
    *
    *  @param n the number of elements to drop
-   *  @return  the new iterator
+   *  @return  an iterator which produces all values of the current iterator, except
+   *           it omits the first `n` values.
    */
   def drop(n: Int): Iterator[A] = {
     @tailrec
@@ -296,24 +304,30 @@ trait Iterator[+A] { self =>
     loop(n)
   }
 
-  /** Advances this iterator past the first `from` elements using `drop`,
+  /** Creates an iterator returning an interval of the values produced by this iterator.
+   *  @param from   the index of the first element in this iterator which forms part of the slice.
+   *  @param until  the index of the first element following the slice.
+   *  @return an iterator which advances this iterator past the first `from` elements using `drop`,
    *  and then takes `until - from` elements, using `take`.
-   *
-   *  @param from   The index of the first element of the slice
-   *  @param until    The index of the element following the slice
    */
   def slice(from: Int, until: Int): Iterator[A] = drop(from).take(until - from)
 
-  /** Returns a new iterator that maps all elements of this iterator
-   *  to new elements using function <code>f</code>.
+  /** Creates a new iterator that maps all produced values of this iterator
+   *  to new values using a transformation function.
+   *  @param f  the transformation function
+   *  @return a new iterator which transformes every value produced by this
+   *          iterator by applying the functon `f` to it.
    */
   def map[B](f: A => B): Iterator[B] = new Iterator[B] {
     def hasNext = self.hasNext
     def next() = f(self.next())
   }
 
-  /** Returns a new iterator that first yields the elements of this
-   *  iterator followed by the elements provided by iterator <code>that</code>.
+  /** Concatenates this iterator with another.
+   *  @that   the other iterator
+   *  @return  a new iterator that first yields the values produced by this
+   *  iterator followed by the values produced by iterator `that`.
+   *  @usecase def ++(that: => Iterator[A]): Iterator[A]
    */
   def ++[B >: A](that: => Iterator[B]): Iterator[B] = new Iterator[B] {
     // optimize a little bit to prevent n log n behavior.
@@ -329,13 +343,12 @@ trait Iterator[+A] { self =>
     def next() = { hasNext; cur.next() }
   }
 
-  /** Applies the given function <code>f</code> to each element of
-   *  this iterator, then concatenates the results.
+  /** Creates a new iterator by applying a function to all values produced by this iterator
+   *  and concatenating the results.
    *
    *  @param f the function to apply on each element.
-   *  @return  an iterator over <code>f(a<sub>0</sub>), ... ,
-   *           f(a<sub>n</sub>)</code> if this iterator yields the
-   *           elements <code>a<sub>0</sub>, ..., a<sub>n</sub></code>.
+   *  @return   the iterator resulting from applying the given iterator-valued function
+   *                `f` to each value produced by this iterator and concatenating the results.
    */
   def flatMap[B](f: A => Iterator[B]): Iterator[B] = new Iterator[B] {
     private var cur: Iterator[B] = empty
@@ -345,11 +358,11 @@ trait Iterator[+A] { self =>
   }
 
   /** Returns an iterator over all the elements of this iterator that
-   *  satisfy the predicate <code>p</code>. The order of the elements
+   *  satisfy the predicate `p`. The order of the elements
    *  is preserved.
    *
-   *  @param p the predicate used to filter the iterator.
-   *  @return  the elements of this iterator satisfying <code>p</code>.
+   *  @param p the predicate used to test values.
+   *  @return  an iterator which produces those values of this iterator which satisfy the predicate `p`.
    */
   def filter(p: A => Boolean): Iterator[A] = new Iterator[A] {
     private var hd: A = _
@@ -367,64 +380,28 @@ trait Iterator[+A] { self =>
     def next() = if (hasNext) { hdDefined = false; hd } else empty.next()
   }
 
-  def withFilter(p: A => Boolean): WithFilter = new WithFilter(p)
-
-  final class WithFilter private[Iterator] (p: A => Boolean) {
-
-    def map[B](f: A => B): Iterator[B] = new Iterator[B] {
-      private var hd: A = _
-      private var hdDefined: Boolean = false
-
-      def hasNext: Boolean = hdDefined || {
-        do {
-          if (!self.hasNext) return false
-          hd = self.next()
-        } while (!p(hd))
-        hdDefined = true
-        true
-      }
-
-      def next() = if (hasNext) { hdDefined = false; f(hd) } else empty.next()
-    }
-
-    def flatMap[B](f: A => Iterator[B]): Iterator[B] = new Iterator[B] {
-      private var cur: Iterator[B] = empty
-
-      @tailrec
-      def hasNext: Boolean = cur.hasNext || {
-        var x = null.asInstanceOf[A]
-        do {
-          if (!self.hasNext) return false
-          x = self.next()
-        } while (!p(x))
-        cur = f(x)
-        hasNext
-      }
-
-      def next(): B = (if (hasNext) cur else empty).next()
-    }
-
-    def foreach[U](f: A => U) {
-      while (self.hasNext) {
-        val x = self.next()
-        if (p(x)) f(x)
-      }
-    }
-
-    def withFilter(q: A => Boolean): WithFilter = new WithFilter(x => p(x) && q(x))
-  }
+  /** Returns an iterator over all the elements of this iterator that
+   *  satisfy the predicate `p`. The order of the elements
+   *  is preserved.
+   *
+   *  @note `withFilter` is the same as `filter` on iterators. It exists so that
+   *  for-expressions with filters work over iterators.
+   *
+   *  @param p the predicate used to test values.
+   *  @return  an iterator which produces those values of this iterator which satisfy the predicate `p`.
+   */
+  def withFilter(p: A => Boolean): Iterator[A] = filter(p)
 
   /** Returns an iterator over all the elements of this iterator which
-   *  do not satisfy the predicate <code>p</code>.
+   *  do not satisfy a predicate p.
    *
-   *  @param p the predicate used to filter.
-   *  @return  the elements of this iterator not satisfying <code>p</code>.
+   *  @param p the predicate used to test values.
+   *  @return  an iterator which produces those values of this iterator which do not satisfy the predicate `p`.
    */
-
   def filterNot(p: A => Boolean): Iterator[A] = filter(!p(_))
 
- /** Returns a new iterator based on the partial function <code>pf</code>,
-  *  containing <code>pf(x)</code> for all the elements which are defined on pf.
+ /** Returns a new iterator based on the partial function `pf`,
+  *  containing `pf(x)` for all the elements which are defined on pf.
   *  The order of the elements is preserved.
   *
   *  @param pf the partial function which filters and maps the iterator.
@@ -440,11 +417,11 @@ trait Iterator[+A] { self =>
   }
 
   /** Returns an iterator over the longest prefix of this iterator such that
-   *  all elements of the result satisfy the predicate <code>p</code>.
+   *  all elements of the result satisfy the predicate `p`.
    *  The order of the elements is preserved.
    *
    *  @param p the predicate used to filter the iterator.
-   *  @return  the longest prefix of this iterator satisfying <code>p</code>.
+   *  @return  the longest prefix of this iterator satisfying `p`.
    */
   def takeWhile(p: A => Boolean): Iterator[A] = new Iterator[A] {
     private var hd: A = _
@@ -464,7 +441,7 @@ trait Iterator[+A] { self =>
    *
    *  @param p the predicate on which to partition
    *  @return  a pair of iterators: the iterator that satisfies the predicate
-   *           <code>p</code> and the iterator that does not.
+   *           `p` and the iterator that does not.
    *           The relative order of the elements in the resulting iterators
    *           is the same as in the original iterator.
    */
@@ -489,7 +466,7 @@ trait Iterator[+A] { self =>
   }
 
   /** Skips longest sequence of elements of this iterator which satisfy given
-   *  predicate <code>p</code>, and returns an iterator of the remaining elements.
+   *  predicate `p`, and returns an iterator of the remaining elements.
    *
    *  @param p the predicate used to skip elements.
    *  @return  an iterator consisting of the remaining elements
@@ -509,7 +486,7 @@ trait Iterator[+A] { self =>
   }
 
   /** Return an iterator formed from this iterator and the specified iterator
-   *  <code>that</code> by associating each element of the former with
+   *  `that` by associating each element of the former with
    *  the element at the same position in the latter.
    *  If one of the two iterators is longer than the other, its remaining
    *  elements are ignored.
@@ -519,7 +496,7 @@ trait Iterator[+A] { self =>
     def next = (self.next, that.next)
   }
 
-  /** Return a new iterator with a length equal or longer to <code>len</code>.
+  /** Return a new iterator with a length equal or longer to `len`.
    *  If the current iterator returns fewer than `len` elements
    *  return `elem` until the required length `len` is reached.
    */
@@ -549,23 +526,23 @@ trait Iterator[+A] { self =>
   }
 
   /** Returns an iterator formed from this iterator and the specified iterator
-   *  <code>that</code> by associating each element of the former with
+   *  `that` by associating each element of the former with
    *  the element at the same position in the latter.
    *
-   *  @param that     iterator <code>that</code> may have a different length
+   *  @param that     iterator `that` may have a different length
    *                  as the self iterator.
-   *  @param thisElem element <code>thisElem</code> is used to fill up the
+   *  @param thisElem element `thisElem` is used to fill up the
    *                  resulting iterator if the self iterator is shorter than
-   *                  <code>that</code>
-   *  @param thatElem element <code>thatElem</code> is used to fill up the
-   *                  resulting iterator if <code>that</code> is shorter than
+   *                  `that`
+   *  @param thatElem element `thatElem` is used to fill up the
+   *                  resulting iterator if `that` is shorter than
    *                  the self iterator
-   *  @return         <code>Iterator((a<sub>0</sub>,b<sub>0</sub>), ...,
+   *  @return         `Iterator((a<sub>0</sub>,b<sub>0</sub>), ...,
    *                  (a<sub>n</sub>,b<sub>n</sub>), (elem,b<sub>n+1</sub>),
-   *                  ..., {elem,b<sub>m</sub>})</code>
-   *                  when <code>[a<sub>0</sub>, ..., a<sub>n</sub>] zip
-   *                  [b<sub>0</sub>, ..., b<sub>m</sub>]</code> is
-   *                  invoked where <code>m &gt; n</code>.
+   *                  ..., {elem,b<sub>m</sub>})`
+   *                  when `[a<sub>0</sub>, ..., a<sub>n</sub>] zip
+   *                  [b<sub>0</sub>, ..., b<sub>m</sub>]` is
+   *                  invoked where `m &gt; n`.
    */
   def zipAll[B, A1 >: A, B1 >: B](that: Iterator[B], thisElem: A1, thatElem: B1) = new Iterator[(A1, B1)] {
     def hasNext = self.hasNext || that.hasNext
@@ -579,19 +556,19 @@ trait Iterator[+A] { self =>
       }
   }
 
-  /** Execute a function <code>f</code> for all elements of this
+  /** Execute a function `f` for all elements of this
    *  iterator.
    *
    *  @param  f   a function that is applied to every element.
    */
   def foreach[U](f: A =>  U) { while (hasNext) f(next()) }
 
-  /** Apply a predicate <code>p</code> to all elements of this
-   *  iterable object and return <code>true</code> iff the predicate yields
-   *  <code>true</code> for all elements.
+  /** Apply a predicate `p` to all elements of this
+   *  iterable object and return `true` iff the predicate yields
+   *  `true` for all elements.
    *
    *  @param p the predicate
-   *  @return  <code>true</code> iff the predicate yields <code>true</code>
+   *  @return  `true` iff the predicate yields `true`
    *           for all elements.
    */
   def forall(p: A => Boolean): Boolean = {
@@ -600,12 +577,12 @@ trait Iterator[+A] { self =>
     res
   }
 
-  /** Apply a predicate <code>p</code> to all elements of this
+  /** Apply a predicate `p` to all elements of this
    *  iterable object and return true iff there is at least one
-   *  element for which <code>p</code> yields <code>true</code>.
+   *  element for which `p` yields `true`.
    *
    *  @param p the predicate
-   *  @return  <code>true</code> iff the predicate yields <code>true</code>
+   *  @return  `true` iff the predicate yields `true`
    *           for at least one element.
    */
   def exists(p: A => Boolean): Boolean = {
@@ -614,7 +591,7 @@ trait Iterator[+A] { self =>
     res
   }
 
- /** Tests if the given value <code>elem</code> is a member of this iterator.
+ /** Tests if the given value `elem` is a member of this iterator.
    *
    *  @param elem element whose membership has to be tested.
    */
@@ -625,7 +602,7 @@ trait Iterator[+A] { self =>
    *
    *  @param p the predicate
    *  @return  the first element in the iterable object satisfying
-   *           <code>p</code>, or <code>None</code> if none exists.
+   *           `p`, or `None` if none exists.
    */
   def find(p: A => Boolean): Option[A] = {
     var res: Option[A] = None
@@ -655,7 +632,7 @@ trait Iterator[+A] { self =>
    *
    *  @note may not terminate for infinite-sized collections.
    *  @param  p the predicate
-   *  @return   the index of the first element satisfying <code>p</code>,
+   *  @return   the index of the first element satisfying `p`,
    *           or -1 if such an element does not exist
    */
   def indexWhere(p: A => Boolean): Int = {
@@ -694,12 +671,12 @@ trait Iterator[+A] { self =>
   }
 
   /** Combines the elements of this iterator together using the binary
-   *  operator <code>op</code>, from left to right, and starting with
-   *  the value <code>z</code>.
+   *  operator `op`, from left to right, and starting with
+   *  the value `z`.
    *
-   *  @return <code>op(... (op(op(z,a<sub>0</sub>),a<sub>1</sub>) ...),
-   *          a<sub>n</sub>)</code> if the iterator yields elements
-   *          <code>a<sub>0</sub>, a<sub>1</sub>, ..., a<sub>n</sub></code>.
+   *  @return `op(... (op(op(z,a<sub>0</sub>),a<sub>1</sub>) ...),
+   *          a<sub>n</sub>)` if the iterator yields elements
+   *          `a<sub>0</sub>, a<sub>1</sub>, ..., a<sub>n</sub>`.
    */
   def foldLeft[B](z: B)(op: (B, A) => B): B = {
     var acc = z
@@ -708,46 +685,46 @@ trait Iterator[+A] { self =>
   }
 
   /** Combines the elements of this iterator together using the binary
-   *  operator <code>op</code>, from right to left, and starting with
-   *  the value <code>z</code>.
+   *  operator `op`, from right to left, and starting with
+   *  the value `z`.
    *
-   *  @return <code>a<sub>0</sub> op (... op (a<sub>n</sub> op z)...)</code>
-   *          if the iterator yields elements <code>a<sub>0</sub>, a<sub>1</sub>, ...,
-   *          a<sub>n</sub></code>.
+   *  @return `a<sub>0</sub> op (... op (a<sub>n</sub> op z)...)`
+   *          if the iterator yields elements `a<sub>0</sub>, a<sub>1</sub>, ...,
+   *          a<sub>n</sub>`.
    */
   def foldRight[B](z: B)(op: (A, B) => B): B =
     if (hasNext) op(next(), foldRight(z)(op)) else z
 
-  /** Similar to <code>foldLeft</code> but can be used as
+  /** Similar to `foldLeft` but can be used as
    *  an operator with the order of iterator and zero arguments reversed.
-   *  That is, <code>z /: xs</code> is the same as <code>xs foldLeft z</code>.
+   *  That is, `z /: xs` is the same as `xs foldLeft z`.
    *
-   *  @param z the left argument of the first application of <code>op</code>
+   *  @param z the left argument of the first application of `op`
    *           (evaluation occurs from left to right).
    *  @param op the applied operator.
    *  @return  the result value
-   *  @see     <code><a href="#foldLeft">foldLeft</a></code>.
+   *  @see     `<a href="#foldLeft">foldLeft</a>`.
    */
   def /:[B](z: B)(op: (B, A) => B): B = foldLeft(z)(op)
 
-  /** An alias for <code>foldRight</code>.
-   *  That is, <code>xs :\ z</code> is the same as <code>xs foldRight z</code>.
+  /** An alias for `foldRight`.
+   *  That is, `xs :\ z` is the same as `xs foldRight z`.
    *
-   *  @param z the right argument of the first application of <code>op</code>
+   *  @param z the right argument of the first application of `op`
    *           (evaluation occurs from right to left).
    *  @param op the applied operator.
    *  @return  the result value.
-   *  @see     <code><a href="#foldRight">foldRight</a></code>.
+   *  @see     `<a href="#foldRight">foldRight</a>`.
    */
   def :\[B](z: B)(op: (A, B) => B): B = foldRight(z)(op)
 
   /** Combines the elements of this iterator together using the binary
-   *  operator <code>op</code>, from left to right.
+   *  operator `op`, from left to right.
    *
    *  @param op  The operator to apply
-   *  @return <code>op(... op(a<sub>0</sub>,a<sub>1</sub>), ..., a<sub>n</sub>)</code>
+   *  @return `op(... op(a<sub>0</sub>,a<sub>1</sub>), ..., a<sub>n</sub>)`
    *  if the iterator yields elements
-   *          <code>a<sub>0</sub>, a<sub>1</sub>, ..., a<sub>n</sub></code>.
+   *          `a<sub>0</sub>, a<sub>1</sub>, ..., a<sub>n</sub>`.
    *  @throws Predef.UnsupportedOperationException if the iterator is empty.
    */
   def reduceLeft[B >: A](op: (B, A) => B): B = {
@@ -756,12 +733,12 @@ trait Iterator[+A] { self =>
   }
 
   /** Combines the elements of this iterator together using the binary
-   *  operator <code>op</code>, from right to left
+   *  operator `op`, from right to left
    *  @param op  The operator to apply
    *
-   *  @return <code>a<sub>0</sub> op (... op (a<sub>n-1</sub> op a<sub>n</sub>)...)</code>
-   *          if the iterator yields elements <code>a<sub>0</sub>, a<sub>1</sub>, ...,
-   *          a<sub>n</sub></code>.
+   *  @return `a<sub>0</sub> op (... op (a<sub>n-1</sub> op a<sub>n</sub>)...)`
+   *          if the iterator yields elements `a<sub>0</sub>, a<sub>1</sub>, ...,
+   *          a<sub>n</sub>`.
 
    *  @throws Predef.UnsupportedOperationException if the iterator is empty.
    */
@@ -771,7 +748,7 @@ trait Iterator[+A] { self =>
   }
 
   /** Combines the elements of this iterator together using the binary
-   *  operator <code>op</code>, from left to right
+   *  operator `op`, from left to right
    *  @param op  The operator to apply
    *  @return  If the iterable is non-empty, the result of the operations as an Option, otherwise None.
    */
@@ -780,7 +757,7 @@ trait Iterator[+A] { self =>
   }
 
   /** Combines the elements of this iterable object together using the binary
-   *  operator <code>op</code>, from right to left.
+   *  operator `op`, from right to left.
    *
    *  @param op  The operator to apply
    *  @return  If the iterable is non-empty, the result of the operations as an Option, otherwise None.
@@ -828,7 +805,7 @@ trait Iterator[+A] { self =>
     buf
   }
 
-  /** A flexible iterator for transforming an <code>Iterator[A]</code> into an
+  /** A flexible iterator for transforming an `Iterator[A]` into an
    *  Iterator[Seq[A]], with configurable sequence size, step, and
    *  strategy for dealing with elements which don't fit evenly.
    *
@@ -1028,8 +1005,8 @@ trait Iterator[+A] { self =>
     }
   }
 
-  /** Fills the given array <code>xs</code> with the elements of
-   *  this iterator starting at position <code>start</code>
+  /** Fills the given array `xs` with the elements of
+   *  this iterator starting at position `start`
    *  until either the end of the current iterator or the end of array `xs` is reached.
    *
    *  @param  xs the array to fill.
@@ -1038,8 +1015,8 @@ trait Iterator[+A] { self =>
   def copyToArray[B >: A](xs: Array[B], start: Int): Unit =
     copyToArray(xs, start, xs.length - start)
 
-  /** Fills the given array <code>xs</code> with the elements of
-   *  this iterator starting at position <code>0</code>
+  /** Fills the given array `xs` with the elements of
+   *  this iterator starting at position `0`
    *  until either the end of the current iterator or the end of array `xs` is reached.
    *
    *  @param  xs the array to fill.
@@ -1095,13 +1072,13 @@ trait Iterator[+A] { self =>
   }
 
   /** Returns a string representation of the elements in this iterator. The resulting string
-   *  begins with the string <code>start</code> and is finished by the string
-   *  <code>end</code>. Inside, the string representations of elements (w.r.t.
-   *  the method <code>toString</code>) are separated by the string
-   *  <code>sep</code>.
+   *  begins with the string `start` and is finished by the string
+   *  `end`. Inside, the string representations of elements (w.r.t.
+   *  the method `toString`) are separated by the string
+   *  `sep`.
    *  <p/>
    *  Ex: <br/>
-   *  <code>List(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)"</code>
+   *  `List(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)"`
    *
    *  @param start starting string.
    *  @param sep separator string.
@@ -1114,8 +1091,8 @@ trait Iterator[+A] { self =>
   }
 
   /** Returns a string representation of this iterable object. The string
-   *  representations of elements (w.r.t. the method <code>toString()</code>)
-   *  are separated by the string <code>sep</code>.
+   *  representations of elements (w.r.t. the method `toString()`)
+   *  are separated by the string `sep`.
    *
    *  @param sep separator string.
    *  @return a string representation of this iterable object.
@@ -1123,7 +1100,7 @@ trait Iterator[+A] { self =>
   def mkString(sep: String): String = mkString("", sep, "")
 
   /** Returns a string representation of this iterable object. The string
-   *  representations of elements (w.r.t. the method <code>toString()</code>)
+   *  representations of elements (w.r.t. the method `toString()`)
    *  are concatenated without any separator string.
    *
    *  @return a string representation of this iterable object.
@@ -1131,10 +1108,10 @@ trait Iterator[+A] { self =>
   def mkString: String = mkString("")
 
   /** Write all elements of this iterator into given string builder.
-   *  The written text begins with the string <code>start</code> and is finished by the string
-   *  <code>end</code>. Inside, the string representations of elements (w.r.t.
-   *  the method <code>toString()</code>) are separated by the string
-   *  <code>sep</code>.
+   *  The written text begins with the string `start` and is finished by the string
+   *  `end`. Inside, the string representations of elements (w.r.t.
+   *  the method `toString()`) are separated by the string
+   *  `sep`.
    */
   def addString(buf: StringBuilder, start: String, sep: String, end: String): StringBuilder = {
     buf.append(start)
@@ -1147,8 +1124,8 @@ trait Iterator[+A] { self =>
   }
 
   /** Write all elements of this iterator into given string builder.
-   *  The string representations of elements (w.r.t. the method <code>toString()</code>)
-   *  are separated by the string <code>sep</code>.
+   *  The string representations of elements (w.r.t. the method `toString()`)
+   *  are separated by the string `sep`.
    */
   def addString(buf: StringBuilder, sep: String): StringBuilder = addString(buf, "", sep, "")
 
@@ -1160,9 +1137,9 @@ trait Iterator[+A] { self =>
   override def toString = (if (hasNext) "non-empty" else "empty")+" iterator"
 
   /** Returns a new iterator that first yields the elements of this
-   *  iterator followed by the elements provided by iterator <code>that</code>.
+   *  iterator followed by the elements provided by iterator `that`.
    */
-  @deprecated("use <code>++</code>")
+  @deprecated("use `++`")
   def append[B >: A](that: Iterator[B]) = self ++ that
 
   /** Returns index of the first element satisfying a predicate, or -1. */
@@ -1186,14 +1163,14 @@ trait Iterator[+A] { self =>
     def next(): A = { cnt += 1; self.next }
   }
 
-  /** Fills the given array <code>xs</code> with the elements of
-   *  this sequence starting at position <code>start</code>.  Like <code>copyToArray</code>,
+  /** Fills the given array `xs` with the elements of
+   *  this sequence starting at position `start`.  Like `copyToArray`,
    *  but designed to accomodate IO stream operations.
    *
    *  @param  xs    the array to fill.
    *  @param  start the starting index.
    *  @param  sz    the maximum number of elements to be read.
-   *  @pre          the array must be large enough to hold <code>sz</code> elements.
+   *  @pre          the array must be large enough to hold `sz` elements.
    */
   @deprecated("use copyToArray instead")
   def readInto[B >: A](xs: Array[B], start: Int, sz: Int) {
diff --git a/src/library/scala/collection/MapLike.scala b/src/library/scala/collection/MapLike.scala
index c856fd61a2..812d420331 100644
--- a/src/library/scala/collection/MapLike.scala
+++ b/src/library/scala/collection/MapLike.scala
@@ -19,22 +19,25 @@ import PartialFunction._
  *
  *  @tparam A    the type of the keys.
  *  @tparam B    the type of associated values.
- *  @tparam This the type of the `Map` itself.
+ *  @tparam This the type of the map itself.
+ *
+ *  $mapnote
+ *
  *  @author  Martin Odersky
  *  @version 2.8
  *  @since   2.8
  *  $mapnote
  *  @define $mapnote  @note
+ *    This trait provides most of the operations of a `Map` independently of its representation.
+ *    It is typically inherited by concrete implementations of maps.
+ *
  *    To implement a concrete map, you need to provide implementations of the
- *    following methods
+ *    following methods:
  *    {{{
  *       def get(key: A): Option[B]
- *
  *       def iterator: Iterator[(A, B)]
- *
  *       def + [B1 >: B](kv: (A, B1)): This
- *
- *       def -(key: A): This</pre>
+ *       def -(key: A): This
  *    }}}
  *    If you wish that methods like `take`, `drop`, `filter` also return the same kind of map
  *    you should also override:
@@ -43,14 +46,22 @@ import PartialFunction._
  *    }}}
  *    It is also good idea to override methods `foreach` and
  *    `size` for efficiency.
+ *  @define coll map
+ *  @define Coll Map
+ *  @define willNotTerminateInf
+ *  @define mayNotTerminateInf
  */
 trait MapLike[A, +B, +This <: MapLike[A, B, This] with Map[A, B]]
   extends PartialFunction[A, B]
      with IterableLike[(A, B), This]
      with Subtractable[A, This] {
 self =>
+  // note: can't inherit Addable because of variance problems: Map
+  // is covariant in its value type B, but Addable is nonvariant.
 
-  /* The empty map of the dame type as this map */
+  /* The empty map of the same type as this map
+   *   @return   an empty map of type `This`.
+   */
   def empty: This
 
   /** A common implementation of `newBuilder` for all maps in terms of `empty`.
@@ -58,78 +69,95 @@ self =>
    */
   override protected[this] def newBuilder: Builder[(A, B), This] = new MapBuilder[A, B, This](empty)
 
-  /** Check if this map maps <code>key</code> to a value and return the
-   *  value as an option if it exists, None if not.
+  /** Optionally returns the value associated with a key.
    *
-   *  @param      key the key of the mapping of interest.
-   *  @return     the value of the mapping as an option, if it exists, or None.
+   *  @key    the key value
+   *  @return an option value containing the value associated with `key` in this map,
+   *          or `None` if none exists.
    */
   def get(key: A): Option[B]
 
-  /** An iterator yielding all key/value mappings of this map. */
+  /** Creates a new iterator over all key/value pairs of this map
+   *
+   *  @return the new iterator
+   */
   def iterator: Iterator[(A, B)]
 
-  /** Add a key/value pair to this map, returning a new map.
+  /** Adds a key/value pair to this map, returning a new map.
    *  @param    kv the key/value pair
-   *  @return   A new map with the new binding added to this map
+   *  @tparam   B1 the type of the value in the key/value pair.
+   *  @return   a new map with the new binding added to this map
+   *  @usecase  def + (kv: (A, B)): Map[A, B]
    */
   def + [B1 >: B] (kv: (A, B1)): Map[A, B1]
 
-  /** Removes a key from this map, returning a new map
+  /** Removes a key from this map, returning a new map.
    *  @param    key the key to be removed
-   *  @return   A new map without a binding for <code>key</code>
+   *  @return   a new map without a binding for `key`
+   *  @usecase  def - (key: A): Map[A, B]
    */
   def - (key: A): This
 
-  /** Is this an empty map?
+  /** Tests whether the map is empty.
    *
-   *  @return <code>true</code> iff the map does not contain any key/value mapping.
+   *  @return `true` if the map does not contain any key/value binding, `false` otherwise.
    */
   override def isEmpty: Boolean = size == 0
 
-  /**  Check if this map maps <code>key</code> to a value.
-   *   Return that value if it exists, otherwise return <code>default</code>.
+  /**  Returns the value associated with a key, or a default value if the key is not contained in the map.
    *   @param   key      the key.
-   *   @param   default  a computation that yields a default value in case no binding for the key is
+   *   @param   default  a computation that yields a default value in case no binding for `key` is
    *                     found in the map.
+   *   @tparam  B1       the result type of the default computation.
+   *   @return  the value assocuated with `key` if it exists,
+   *            otherwise the result of the `default` computation.
+   *   @usecase getOrElse(key: A, default: => B): B
    */
   def getOrElse[B1 >: B](key: A, default: => B1): B1 = get(key) match {
     case Some(v) => v
     case None => default
   }
 
-  /** Retrieve the value which is associated with the given key. This
-   *  method throws an exception if there is no mapping from the given
-   *  key to a value.
+  /** Retrieves the value which is associated with the given key. This
+   *  method invokes the `default` method of the map if there is no mapping
+   *  from the given key to a value. Unless overridden, the `default` method throws a
+   *  `NoSuchElementException`.
    *
    *  @param  key the key
-   *  @return     the value associated with the given key.
+   *  @return     the value associated with the given key, or the result of the
+   *              map's `default` method, if none exists.
    */
   def apply(key: A): B = get(key) match {
     case None => default(key)
     case Some(value) => value
   }
 
-  /** Is the given key mapped to a value by this map?
+  /** Tests whether this map contains a binding for a key.
    *
    *  @param key the key
-   *  @return    <code>true</code> iff there is a mapping for key in this map
+   *  @return    `true` if there is a binding for `key` in this map, `false` otherwise.
    */
   def contains(key: A): Boolean = get(key) match {
     case None => false
     case Some(_) => true
   }
 
-  /** Does this map contain a mapping from the given key to a value?
+  /** Tests whether this map contains a binding for a key. This method,
+   *  which implements an abstract method of trait `PartialFunction`,
+   *  is equivalent to `contains`.
    *
    *  @param key the key
-   *  @return    <code>true</code> iff there is a mapping for key in this map
+   *  @return    `true` if there is a binding for `key` in this map, `false` otherwise.
    */
   def isDefinedAt(key: A) = contains(key)
 
-  /** @return the keys of this map as a set. */
+  /** Collects all keys of this map in a set.
+   * @return  a set containing all keys of this map.
+   */
   def keySet: Set[A] = new DefaultKeySet
 
+  /** The implementation class of the set returned by `keySet`.
+   */
   protected class DefaultKeySet extends Set[A] {
     def contains(key : A) = self.contains(key)
     def iterator = keysIterator
@@ -156,19 +184,22 @@ self =>
   @deprecated("use `keysIterator' instead")
   def keys: Iterator[A] = keysIterator
 
-  /** @return the values of this map as an iterable.
+  /** Collects all values of this map in an iterable collection.
+   * @return the values of this map as an iterable.
    */
   def valuesIterable: Iterable[B] = new DefaultValuesIterable
 
+  /** The implementation class of the iterable returned by `valuesIterable`.
+   */
   protected class DefaultValuesIterable extends Iterable[B] {
     def iterator = valuesIterator
     override def size = self.size
     override def foreach[C](f: B => C) = for ((k, v) <- self) f(v)
   }
 
-  /** Creates an iterator for a contained values.
+  /** Creates an iterator for all values in this map.
    *
-   *  @return an iterator over all values.
+   *  @return an iterator over all values that are associated with some key in this map.
    */
   def valuesIterator: Iterator[B] = new Iterator[B] {
     val iter = self.iterator
@@ -176,25 +207,28 @@ self =>
     def next = iter.next._2
   }
 
-  /** Creates an iterator for a contained values.
+  /** Creates an iterator for all contained values.
    *
    *  @return an iterator over all values.
    */
   @deprecated("use `valuesIterator' instead")
   def values: Iterator[B] = valuesIterator
 
-  /** The default value for the map, returned when a key is not found
-   *  The method implemented here yields an error,
+  /** Defines the default value computation for the map,
+   *  returned when a key is not found
+   *  The method implemented here throws an exception,
    *  but it might be overridden in subclasses.
    *
-   *  @param key the given key value
-   *  @throws Predef.NoSuchElementException
+   *  @param key the given key value for which a binding is missing.
+   *  @throws `NoSuchElementException`
    */
   def default(key: A): B =
     throw new NoSuchElementException("key not found: " + key)
 
-  /** A map view consisting only of those key value pairs where the key satisfies a given
-   *  predicate `p`.
+  /** Filters this map by retaining only keys satisfying a predicate.
+   *  @param  p   the predicate used to test keys
+   *  @return an immutable map consisting only of those key value pairs of this map where the key satisfies
+   *          the predicate `p`. The resulting map wraps the original map without copying any elements.
    */
   def filterKeys(p: A => Boolean) = new DefaultMap[A, B] {
     override def foreach[C](f: ((A, B)) => C): Unit = for (kv <- self) if (p(kv._1)) f(kv)
@@ -203,6 +237,11 @@ self =>
     def get(key: A) = if (!p(key)) None else self.get(key)
   }
 
+  /** Transforms this map by applying a function to every retrieved value.
+   *  @param  d   the function used to transform values of this map.
+   *  @return an immutable map which maps every key of this map
+   *          to `f(this(key))`. The resulting map wraps the original map without copying any elements.
+   */
   /** A map view resulting from applying a given function `f` to each value
    *  associated with a key in this map.
    */
@@ -220,54 +259,73 @@ self =>
   // generic, returning This[B]. We need better covariance support to express that though.
   // So right now we do the brute force approach of code duplication.
 
-  /** A new immutable map containing updating this map with a given key/value mapping.
+  /** Creates a new map obtained by updating this map with a given key/value pair.
    *  @param    key the key
    *  @param    value the value
-   *  @return   A new map with the new key/value mapping
+   *  @tparam   B1 the type of the added value
+   *  @return   A new map with the new key/value mapping added to this map.
+   *  @usecase  def updated(key: A, value: B): Map[A, B]
    */
   def updated [B1 >: B](key: A, value: B1): Map[A, B1] = this + ((key, value))
 
-  /** Adds two or more elements to this collection and returns
-   *  a new collection.
+  /** Adds key/value pairs to this map, returning a new map.
    *
-   *  @param elem1 the first element to add.
-   *  @param elem2 the second element to add.
-   *  @param elems the remaining elements to add.
+   *  This method takes two or more key/value pairs. Another overloaded
+   *  variant of this method handles the case where a single key/value pair is
+   *  added.
+   *  @param    kv1 the first key/value pair
+   *  @param    kv2 the second key/value pair
+   *  @param    kvs the remaining key/value pairs
+   *  @tparam   B1  the type of the added values
+   *  @return   a new map with the given bindings added to this map
+   *  @usecase  def + (kvs: (A, B)*): Map[A, B]
+   *  @param    the key/value pairs
    */
-  def + [B1 >: B] (elem1: (A, B1), elem2: (A, B1), elems: (A, B1) *): Map[A, B1] =
-    this + elem1 + elem2 ++ elems
+  def + [B1 >: B] (kv1: (A, B1), kv2: (A, B1), kvs: (A, B1) *): Map[A, B1] =
+    this + kv1 + kv2 ++ kvs
 
-  /** Adds a number of elements provided by a traversable object
-   *  and returns a new collection with the added elements.
+  /** Adds all key/value pairs in a traversable collection to this map, returning a new map.
    *
-   *  @param elems     the traversable object.
+   *  @param    kvs the collection containing the added key/value pairs
+   *  @tparam   B1  the type of the added values
+   *  @return   a new map with the given bindings added to this map
+   *  @usecase  def + (kvs: Traversable[(A, B)]): Map[A, B]
    */
-  def ++[B1 >: B](elems: Traversable[(A, B1)]): Map[A, B1] =
-    ((repr: Map[A, B1]) /: elems) (_ + _)
+  def ++[B1 >: B](kvs: Traversable[(A, B1)]): Map[A, B1] =
+    ((repr: Map[A, B1]) /: kvs) (_ + _)
 
-  /** Adds a number of elements provided by an iterator
-   *  and returns a new collection with the added elements.
+  /** Adds all key/value pairs produced by an iterator to this map, returning a new map.
    *
-   *  @param iter   the iterator
+   *  @param    iter the iterator producing key/value pairs
+   *  @tparam   B1  the type of the added values
+   *  @return   a new map with the given bindings added to this map
+   *  @usecase  def + (iter: Iterator[(A, B)]): Map[A, B]
    */
   def ++[B1 >: B] (iter: Iterator[(A, B1)]): Map[A, B1] =
     ((repr: Map[A, B1]) /: iter) (_ + _)
 
-  /** Creates a string representation for this map.
+  /** Appends all bindings of this map to a string builder using start, end, and separator strings.
+   *  The written text begins with the string `start` and ends with the string
+   *  `end`. Inside, the string representations of all bindings of this map
+   *  in the form of `key -> value` are separated by the string `sep`.
    *
-   *  @return    a string showing all mappings
+   *  @param  b    the builder to which strings are appended.
+   *  @param start the starting string.
+   *  @param sep   the separator string.
+   *  @param end   the ending string.
+   *  @return      the string builder `b` to which elements were appended.
    */
   override def addString(b: StringBuilder, start: String, sep: String, end: String): StringBuilder =
     this.iterator.map { case (k, v) => k+" -> "+v }.addString(b, start, sep, end)
 
-  /** Defines the prefix of this object's <code>toString</code> representation.
-   *  !!! todo: remove stringPrefix overrides where possible
+  /** Defines the prefix of this object's `toString` representation.
+   *  @return  a string representation which starts the result of `toString` applied to this $coll.
+   *           Unless overridden in subclasse, the string prefix of every map is `"Map"`.
    */
   override def stringPrefix: String = "Map"
 
-  /** Need to override string, so that it's not the Function1's string that gets mixed in.
-   */
-  override def toString = super[IterableLike].toString
+  override /*PartialFunction*/
+  def toString = super[IterableLike].toString
 
   override def hashCode() = this map (_.hashCode) sum
 
@@ -276,8 +334,8 @@ self =>
    *  and vice versa.
    *
    *  @param that the other map
-   *  @return     <code>true</code> iff both maps contain exactly the
-   *              same mappings.
+   *  @return     `true` if both maps contain exactly the
+   *              same mappings, `false` otherwise.
    */
   override def equals(that: Any): Boolean = that match {
     case that: Map[b, _] =>
diff --git a/src/library/scala/collection/Seq.scala b/src/library/scala/collection/Seq.scala
index ac41c32021..1fac25d00d 100644
--- a/src/library/scala/collection/Seq.scala
+++ b/src/library/scala/collection/Seq.scala
@@ -14,21 +14,9 @@ package scala.collection
 import generic._
 import mutable.Builder
 
-/** <p>
- *    Class <code>Seq[A]</code> represents sequences of elements
- *    of type <code>A</code>.<br/>
- *    It adds the following methods to class <code>Iterable</code>:
- *    <code>length</code>, <code>lengthCompare</code>, <code>apply</code>,
- *    <code>isDefinedAt</code>, <code>segmentLength</code>,
- *    <code>prefixLength</code>, <code>indexWhere</code>, <code>indexOf</code>,
- *    <code>lastIndexWhere</code>, <code>lastIndexOf</code>, <code>reverse</code>,
- *    <code>reverseIterator</code>, <code>startsWith</code>,
- *    <code>endsWith</code>, <code>indexOfSlice</code>.
- *  </p>
- *
- *  @author  Martin Odersky
- *  @author  Matthias Zenger
- *  @version 1.0, 16/07/2003
+/** A base trait for sequences.
+ *  $seqInfo
+ *  @tparam A    the element type of the $coll
  */
 trait Seq[+A] extends PartialFunction[Int, A]
                       with Iterable[A]
@@ -37,16 +25,14 @@ trait Seq[+A] extends PartialFunction[Int, A]
   override def companion: GenericCompanion[Seq] = Seq
 }
 
-/** Factory object for <code>Seq</code> trait.
- *
- *  @author  Martin Odersky
- *  @version 2.8
- */
+/** $factoryInfo */
 object Seq extends SeqFactory[Seq] {
 
   private[collection] val hashSeed = "Seq".hashCode
 
+  /** $genericCanBuildFromInfo */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Seq[A]] = new GenericCanBuildFrom[A]
+
   def newBuilder[A]: Builder[A, Seq[A]] = immutable.Seq.newBuilder[A]
 
   @deprecated("use View instead")
diff --git a/src/library/scala/collection/SeqLike.scala b/src/library/scala/collection/SeqLike.scala
index e36f2e6ad2..0462bdc93a 100644
--- a/src/library/scala/collection/SeqLike.scala
+++ b/src/library/scala/collection/SeqLike.scala
@@ -101,7 +101,12 @@ object SeqLike {
 
 /** A template trait for sequences of type `Seq[A]`, representing
  *  sequences of elements of type <code>A</code>.
+ *  $seqInfo
  *
+ *  @tparam A    the element type of the collection
+ *  @tparam Repr the type of the actual collection containing the elements.
+ *
+ *  @define seqInfo
  *  Sequences are special cases of iterable collections of class `Iterable`.
  *  Unlike iterables, sequences always have a defined order of elements.
  *  Sequences provide a method `apply` for indexing. Indices range from `0` up the the `length` of
@@ -126,9 +131,6 @@ object SeqLike {
  *  @version 1.0, 16/07/2003
  *  @since   2.8
  *
- *  @tparam A    the element type of the collection
- *  @tparam Repr the type of the actual collection containing the elements.
- *
  *  @define Coll Seq
  *  @define coll sequence
  *  @define thatinfo the class of the returned collection. Where possible, `That` is
@@ -265,7 +267,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
   }
 
   /** Returns index of the first element satisying a predicate, or `-1`.
-   *  @deprecated "Use `indexWhere` instead"
    */
   def findIndexOf(p: A => Boolean): Int = indexWhere(p)
 
@@ -402,7 +403,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
    */
   def reverseIterator: Iterator[A] = toCollection(reverse).iterator
 
-  /** @deprecated use `reverseIterator` instead */
   @deprecated("use `reverseIterator' instead")
   def reversedElements = reverseIterator
 
@@ -849,12 +849,20 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
   override def toString = super[IterableLike].toString
 
   /** Returns index of the last element satisying a predicate, or -1.
-   * @deprecated use `lastIndexWhere' instead
    */
   def findLastIndexOf(p: A => Boolean): Int = lastIndexWhere(p)
 
-  /** @deprecated Use `corresponds` instead.
+  /** Tests whether every element of this $coll relates to the
+   *  corresponding element of another sequence by satisfying a test predicate.
+   *
+   *  @param   that  the other sequence
+   *  @param   p     the test predicate, which relates elements from both sequences
+   *  @tparam  B     the type of the elements of `that`
+   *  @return  `true` if both sequences have the same length and
+   *                  `p(x, y)` is `true` for all corresponding elements `x` of this $coll
+   *                  and `y` of `that`, otherwise `false`.
    */
+  @deprecated("use `corresponds` instead")
   def equalsWith[B](that: Seq[B])(f: (A,B) => Boolean): Boolean = {
     val i = this.iterator
     val j = that.iterator
@@ -865,7 +873,7 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
     !i.hasNext && !j.hasNext
   }
 
- /** @deprecated Use `view' instead.
+ /**
    * returns a projection that can be used to call non-strict <code>filter</code>,
    * <code>map</code>, and <code>flatMap</code> methods that build projections
    * of the collection.
diff --git a/src/library/scala/collection/SetLike.scala b/src/library/scala/collection/SetLike.scala
index 81f73611ee..156d0d8b2b 100644
--- a/src/library/scala/collection/SetLike.scala
+++ b/src/library/scala/collection/SetLike.scala
@@ -14,49 +14,61 @@ import generic._
 import mutable.{Builder, AddingBuilder}
 import PartialFunction._
 
-/** <p>
- *    A generic template for sets of type <code>A</code>.<br/>
- *    To implement a concrete set, you need to provide implementations of the
- *    following methods (where <code>This</code> is the type of the set in
- *    question):
- *  </p>
- *  <pre>
- *    <b>def</b> contains(key: A): Boolean
- *    <b>def</b> iterator: Iterator[A]
- *    <b>def</b> +(elem: A): This
- *    <b>def</b> -(elem: A): This</pre>
- *  <p>
- *    If you wish that methods <code>like</code>, <code>take</code>, <code>drop</code>,
- *    <code>filter</code> return the same kind of set, you should also override:
- *  </p>
- *  <pre>
- *   <b>def</b> empty: This</pre>
- *  <p>
- *    It is also good idea to override methods <code>foreach</code> and
- *    <code>size</code> for efficiency.
- *  </p>
+/** A template trait for sets of type `Set[A]`.
+ *
+ * This trait provides most of the operations of a `Set` independently of its representation.
+ * It is typically inherited by concrete implementations of sets.
+ *
+ * $setnote
+ *
+ *  @tparam A    the type of the elements of the set
+ *  @tparam This the type of the set itself.
  *
  *  @author  Martin Odersky
  *  @version 2.8
+ *  @define setnote
+ *    To implement a concrete set, you need  to provide implementations of the
+ *    following methods:
+ *    {{{
+ *       def contains(key: A): Boolean
+ *       def iterator: Iterator[A]
+ *       def +(elem: A): This
+ *       def -(elem: A): This
+ *    }}}
+ *    If you wish that methods like `take`, `drop`,
+ *    `filter` return the same kind of set, you should also override:
+ *    {{{
+ *       def empty: This
+ *    }}}
+ *    It is also good idea to override methods `foreach` and
+ *    `size` for efficiency.
+ *   @define coll set
+ *   @define Coll Set
+ *   @define willNotTerminateInf
+ *   @define mayNotTerminateInf
  */
-trait SetLike[A, +This <: SetLike[A, This] with Set[A]] extends IterableLike[A, This] with Addable[A, This] with Subtractable[A, This] {
+trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
+extends IterableLike[A, This]
+   with Addable[A, This]
+   with Subtractable[A, This] {
 self =>
 
-  /* The empty set of the dame type as this set */
+  /* The empty set of the same type as this set
+   * @return  an empty set of type `This`.
+   */
   def empty: This
 
-  /** A common implementation of <code>newBuilder</code> for all sets in terms
-   *  of <code>empty</code>. Overridden for mutable sets in
+  /** A common implementation of `newBuilder` for all sets in terms
+   *  of `empty`. Overridden for mutable sets in
    *  <a href="mutable/SetLike.html" target="ContentFrame">
-   *  <code>mutable.SetLike</code></a>.
+   *  `mutable.SetLike`</a>.
    */
   override protected[this] def newBuilder: Builder[A, This] = new AddingBuilder[A, This](empty)
 
-  /** Checks if this set contains element <code>elem</code>.
+  /** Tests if some element is contained in this set.
    *
-   *  @param elem the element to check for membership.
-   *  @return     <code>true</code> iff <code>elem</code> is contained in
-   *              this set.
+   *  @param elem the element to test for membership.
+   *  @return     `true` if `elem` is contained in this set, `false` otherwise.
    */
   def contains(elem: A): Boolean
 
@@ -64,116 +76,118 @@ self =>
    *  already present.
    *
    *  @param elem the element to be added
+   *  @return a new set that contains all elements of this set and that also
+   *          contains `elem`.
    */
   def + (elem: A): This
 
-  /** Creates a new set with given element removed from this set, unless the
-   *  element is not present.
+  /** Creates a new set with a given element removed from this set.
    *
    *  @param elem the element to be removed
+   *  @return a new set that contains all elements of this set but that does not
+   *          contain `elem`.
    */
   def - (elem: A): This
 
-  /** Checks if this set is empty.
+  /** Tests if this set is empty.
    *
-   *  @return <code>true</code> iff there is no element in the set.
+   *  @return `true` if there is no element in the set, `false` otherwise.
    */
   override def isEmpty: Boolean = size == 0
 
-  /** This method allows sets to be interpreted as predicates.
-   *  It returns <code>true</code>, iff this set contains element
-   *  <code>elem</code>.
+  /** Tests if some element is contained in this set.
    *
-   *  @param elem the element to check for membership.
-   *  @return     <code>true</code> iff <code>elem</code> is contained in
-   *              this set.
+   *  This method is equivalent to `contains`. It allows sets to be interpreted as predicates.
+   *  @param elem the element to test for membership.
+   *  @return  `true` if `elem` is contained in this set, `false` otherwise.
    */
   def apply(elem: A): Boolean = contains(elem)
 
-  /** Returns a new set consisting of all elements that are both in the current
-   *  set and in the argument set.
+  /** Computes the intersection between this set and another set.
    *
-   *  @param that the set to intersect with.
+   *  @param   that  the set to intersect with.
+   *  @return  a new set consisting of all elements that are both in this
+   *  set and in the given set `that`.
    */
   def intersect(that: Set[A]): This = filter(that.contains)
 
-  /** Returns a new set consisting of all elements that are both in the current
-   *  set and in the argument set.
+  /** Computes the intersection between this set and another set.
    *
-   *  @param that the set to intersect with.
-   *  @note  same as <code>intersect</code>.
+   *  @param   that  the set to intersect with.
+   *  @return  a new set consisting of all elements that are both in this
+   *  set and in the given set `that`.
+   *  @note  Same as `intersect`.
    */
   def &(that: Set[A]): This = intersect(that)
 
- /**  This method is an alias for <code>intersect</code>.
-   *  It computes an intersection with set <code>that</code>.
-   *  It removes all the elements that are not present in <code>that</code>.
+ /**  This method is an alias for `intersect`.
+   *  It computes an intersection with set `that`.
+   *  It removes all the elements that are not present in `that`.
    *
    *  @param that the set to intersect with
    */
   @deprecated("use & instead") def ** (that: Set[A]): This = intersect(that)
 
-  /** The union of this set and the given set <code>that</code>.
+  /** Computes the union between of set and another set.
    *
-   *  @param that the set of elements to add
-   *  @return     a set containing the elements of this
-   *              set and those of the given set <code>that</code>.
+   *  @param   that  the set to form the union with.
+   *  @return  a new set consisting of all elements that are in this
+   *  set or in the given set `that`.
    */
   def union(that: Set[A]): This = this.++(that)
 
-  /** The union of this set and the given set <code>that</code>.
+  /** Computes the union between this set and another set.
    *
-   *  @param that the set of elements to add
-   *  @return     a set containing the elements of this
-   *              set and those of the given set <code>that</code>.
-   *  @note       same as <code>union</code>.
+   *  @param   that  the set to form the union with.
+   *  @return  a new set consisting of all elements that are in this
+   *  set or in the given set `that`.
+   *  @note       Same as `union`.
    */
   def | (that: Set[A]): This = union(that)
 
-  /** The difference of this set and the given set <code>that</code>.
+  /** Computes the difference of this set and another set.
    *
-   *  @param that the set of elements to remove
+   *  @param that the set of elements to exclude.
    *  @return     a set containing those elements of this
-   *              set that are not also contained in the given set <code>that</code>.
+   *              set that are not also contained in the given set `that`.
    */
   def diff(that: Set[A]): This = --(that)
 
-  /** The difference of this set and the given set <code>that</code>.
+  /** The difference of this set and another set.
    *
-   *  @param that the set of elements to remove
+   *  @param that the set of elements to exclude.
    *  @return     a set containing those elements of this
-   *              set that are not also contained in the given set <code>that</code>.
-   *  @note       same as <code>diff</code>.
+   *              set that are not also contained in the given set `that`.
+   *  @note       Same as `diff`.
    */
   def &~(that: Set[A]): This = diff(that)
 
-  /** Checks if this set is a subset of set <code>that</code>.
+  /** Tests whether this set is a subset of another set.
    *
-   *  @param that another set.
-   *  @return     <code>true</code> iff the other set is a superset of
-   *              this set.
-   *  todo: rename to isSubsetOf
+   *  @param that  the set to test.
+   *  @return     `true` if this set is a subset of `that`, i.e. if
+   *              every element of this set is also an element of `that`.
    */
   def subsetOf(that: Set[A]): Boolean = forall(that.contains)
 
-  /** Defines the prefix of this object's <code>toString</code> representation.
+  /** Defines the prefix of this object's `toString` representation.
+   *  @return  a string representation which starts the result of `toString` applied to this set.
+   *           Unless overridden this is simply `"Set"`.
    */
   override def stringPrefix: String = "Set"
 
-  /** Need to override string, so that it's not the Function1's string that gets mixed in.
-   */
   override def toString = super[IterableLike].toString
-
   override def hashCode() = this map (_.hashCode) sum
 
-  /** Compares this set with another object and returns true, iff the
-   *  other object is also a set which contains the same elements as
-   *  this set.
+  /** Compares this set with another object for equality.
    *
    *  @param that the other object
-   *  @note not necessarily run-time type safe.
-   *  @return     <code>true</code> iff this set and the other set
-   *              contain the same elements.
+   *  @return     `true` if `that` is a set which contains the same elements
+   *              as this set.
+   *  @note This operation contains an unchecked cast: if `that`
+   *        is a set, it will assume with an unchecked cast
+   *        that it has the same element type as this set.
+   *        Any subsequuent ClassCastException is treated as a `false` result.
    */
   override def equals(that: Any): Boolean = that match {
     case that: Set[_] =>
diff --git a/src/library/scala/collection/Traversable.scala b/src/library/scala/collection/Traversable.scala
index 912948a08d..c3d7fa8bc7 100644
--- a/src/library/scala/collection/Traversable.scala
+++ b/src/library/scala/collection/Traversable.scala
@@ -16,41 +16,7 @@ import mutable.{Builder, Buffer, ArrayBuffer, ListBuffer}
 import scala.util.control.Breaks
 
 /** A template trait for traversable collections.
- *
- *  Collection classes mixing in this trait provide a method
- *  `foreach` which traverses all the elements contained in the collection, applying
- *  a given procedure to each element.
- *  They also provide a method <code>newBuilder</code>
- *  which creates a builder for collections of the same kind.
- *
- *  A traversable class might or might not have two properties: strictness
- *  and orderedness. Neither is represented as a type.
- *
- *  The instances of a strict collection class have all their elements
- *  computed before they can be used as values. By contrast, instances of
- *  a non-strict collection class may defer computation of some of their
- *  elements until after the instance is available as a value.
- *  A typical example of a non-strict collection class is a
- *  <a href="../immutable/Stream.html" target="ContentFrame">
- *  `scala.collection.immutable.Stream`</a>.
- *  A more general class of examples are `TraversableViews`.
- *
- *  If a collection is an instance of an ordered collection class, traversing
- *  its elements with `foreach` will always visit elements in the
- *  same order, even for different runs of the program. If the class is not
- *  ordered, `foreach` can visit elements in different orders for
- *  different runs (but it will keep the same order in the same run).'
- *
- *  A typical example of a collection class which is not ordered is a
- *  `HashMap` of objects. The traversal order for hash maps will
- *  depend on the hash codes of its elements, and these hash codes might
- *  differ from one run to the next. By contrast, a `LinkedHashMap`
- *  is ordered because it's `foreach` method visits elements in the
- *  order they were inserted into the `HashMap`.
- *
- *  @author Martin Odersky
- *  @version 2.8
- *  @since   2.8
+ *  $traversableinfo
  *
  *  @tparam A    The element type of the collection
  */
@@ -105,7 +71,7 @@ trait Traversable[+A] extends TraversableLike[A, Traversable[A]]
   override def toIterable: Iterable[A]
   override def toSeq: Seq[A]
   override def toStream: Stream[A]
-//  override def sortWith(lt : (A,A) => Boolean): Traversable[A]
+  override def sortWith(lt : (A,A) => Boolean): Traversable[A]
   override def mkString(start: String, sep: String, end: String): String
   override def mkString(sep: String): String
   override def mkString: String
@@ -119,17 +85,15 @@ trait Traversable[+A] extends TraversableLike[A, Traversable[A]]
   */
 }
 
-/** Factory methods and utilities for instances of type <code>Traversable</code>.
- *
- *  @author Martin Odersky
- *  @version 2.8
- */
+/** $factoryInfo */
 object Traversable extends TraversableFactory[Traversable] { self =>
 
-  /** provide break functionality separate from client code */
+  /** Provides break functionality separate from client code */
   private[collection] val breaks: Breaks = new Breaks
 
+  /** $genericCanBuildFromInfo */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Traversable[A]] = new GenericCanBuildFrom[A]
+
   def newBuilder[A]: Builder[A, Traversable[A]] = immutable.Traversable.newBuilder[A]
 }
 
diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index 37dccedd95..069f45909d 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -16,7 +16,13 @@ import scala.reflect.ClassManifest
 import mutable.{Builder, StringBuilder, Buffer, ArrayBuffer, ListBuffer}
 import immutable.{List, Stream, Nil, ::}
 
-/** A template trait for traversable collections.
+/** A template trait for traversable collections of type `Traversable[A]`.
+ *  $traversableinfo
+ *
+ *  @tparam A    the element type of the collection
+ *  @tparam Repr the type of the actual collection containing the elements.
+ *
+ *  @define traversableinfo
  *  This is a base trait of all kinds of Scala collections. It implements
  *  the behavior common to all collections, in terms of a method
  *  `foreach` with signature:
@@ -57,10 +63,7 @@ import immutable.{List, Stream, Nil, ::}
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   2.8
- *
- *  @tparam A    the element type of the collection
- *  @tparam Repr the type of the actual collection containing the elements.
- *
+
  *  @define Coll Traversable
  *  @define coll traversable collection
  *  @define thatinfo the class of the returned collection. Where possible, `That` is
@@ -69,7 +72,7 @@ import immutable.{List, Stream, Nil, ::}
  *    which means that an implicit instance of type `CanBuildFrom[Repr, B, That]`
  *    is found.
  *  @define bfinfo an implicit value of class `CanBuildFrom` which determines the
- *    result class `That` from the current representation type `Repr`
+ *    result class `That` from the current representation type `Repr` and
  *    and the new element type `B`.
  *  @define orderDependent
  *
@@ -130,7 +133,7 @@ self =>
    */
   def foreach[U](f: A => U): Unit
 
-  /** Tests whether the $coll is empty.
+  /** Tests whether this $coll is empty.
    *
    *  @return    `true` if the $coll contain no elements, `false` otherwise.
    */
@@ -686,7 +689,7 @@ self =>
     acc
   }
 
-  /** Selects the first element.
+  /** Selects the first element of this $coll.
    *  $orderDependent
    *  @return  the first element of this $coll.
    *  @throws `NoSuchElementException` if the $coll is empty.
@@ -758,7 +761,7 @@ self =>
 
   /** Selects first ''n'' elements.
    *  $orderDependent
-   *  @param  n    The number of elements to take
+   *  @param  n    Tt number of elements to take from this $coll.
    *  @return a $coll consisting only of the first `n` elements of this $coll, or else the
    *          whole $coll, if it has less than `n` elements.
    */
@@ -777,7 +780,7 @@ self =>
 
   /** Selects all elements except first ''n'' ones.
    *  $orderDependent
-   *  @param  n    The number of elements to take
+   *  @param  n    the number of elements to drop from this $coll.
    *  @return a $coll consisting of all elements of this $coll except the first `n` ones, or else the
    *          empty $coll, if this $coll has less than `n` elements.
    */
@@ -1003,7 +1006,7 @@ self =>
    *  @param sep   the separator string.
    *  @param end   the ending string.
    *  @return      a string representation of this $coll. The resulting string
-   *               begins with the string `start` and is finished by the string
+   *               begins with the string `start` and ends with the string
    *               `end`. Inside, the string representations (w.r.t. the method `toString`)
    *               of all elements of this $coll are separated by the string `sep`.
    *
@@ -1033,7 +1036,7 @@ self =>
     addString(new StringBuilder()).toString
 
   /** Appends all elements of this $coll to a string builder using start, end, and separator strings.
-   *  The written text begins with the string `start` and is finished by the string
+   *  The written text begins with the string `start` and ends with the string
    *  `end`. Inside, the string representations (w.r.t. the method `toString`)
    *  of all elements of this $coll are separated by the string `sep`.
    *
diff --git a/src/library/scala/collection/generic/Addable.scala b/src/library/scala/collection/generic/Addable.scala
index c053fbbe33..9686e96c09 100644
--- a/src/library/scala/collection/generic/Addable.scala
+++ b/src/library/scala/collection/generic/Addable.scala
@@ -11,47 +11,55 @@
 package scala.collection
 package generic
 
-/** This class represents collections that can be added to other
- *  collections using a '+' operator.
- *
+/** This trait represents collection-like objects that can be added to
+ *  using a '+' operator. It defines variants of `+` and `++`
+ *  as convenience methods in terms of single-element addition `+`.
+ *  @tparam   A    the type of the elements of the $coll
+ *  @tparam   Repr the type of the $coll itself
  *  @author   Martin Odersky
- *  @owner   Martin Odersky
  *  @version 2.8
  *  @since   2.8
+ *  @define  $coll collection
+ *  @define  $Coll Addable
  */
-trait Addable[A, +This <: Addable[A, This]] { self =>
+trait Addable[A, +Repr <: Addable[A, Repr]] { self =>
 
-  protected def repr: This
+  /** The representation object of type `Repr` which contains the collection's elements
+   */
+  protected def repr: Repr
 
-  /** Creates a new collection with an additional element, unless the element is already present.
-   *  @param elem the element to be added
-   *  @return a fresh collection
+  /** Creates a new $coll with an additional element, unless the element is already present.
+   *  @param elem the element to add
+   *  @return a fresh collection with `elem` added.
    */
-  def +(elem: A): This
+  def +(elem: A): Repr
 
-  /** Adds two or more elements to this collection and returns
-   *  a new collection.
+  /** Creates a new $coll with additional elements.
    *
+   *  This method takes two or more elements to be added. Another overloaded
+   *  variant of this method handles the case where a single element is
+   *  added.
    *  @param elem1 the first element to add.
    *  @param elem2 the second element to add.
    *  @param elems the remaining elements to add.
+   *  @return   a new $coll with the given elements added.
    */
-  def + (elem1: A, elem2: A, elems: A*): This =
+  def + (elem1: A, elem2: A, elems: A*): Repr =
     this + elem1 + elem2 ++ elems
 
-  /** Adds a number of elements provided by a traversable object
-   *  and returns a new collection with the added elements.
+  /** Creates a new $coll by adding all elements contained in another collection to this $coll.
    *
-   *  @param elems     the traversable object.
+   *  @param elems     the collection containing the added elements.
+   *  @return a new $coll with the given elements added.
    */
-  def ++ (elems: Traversable[A]): This = (repr /: elems) (_ + _)
+  def ++ (elems: Traversable[A]): Repr = (repr /: elems) (_ + _)
 
-  /** Adds a number of elements provided by an iterator
-   *  and returns a new collection with the added elements.
+  /** Creates a new $coll by adding all elements produced by an iterator to this $coll.
    *
-   *  @param iter   the iterator
+   *  @param iter     the iterator producing the added elements.
+   *  @return a new $coll with the given elements added.
    */
-  def ++ (iter: Iterator[A]): This = (repr /: iter) (_ + _)
+  def ++ (iter: Iterator[A]): Repr = (repr /: iter) (_ + _)
 }
 
 
diff --git a/src/library/scala/collection/generic/CanBuildFrom.scala b/src/library/scala/collection/generic/CanBuildFrom.scala
index 87e4dfd79d..9bc5914168 100644
--- a/src/library/scala/collection/generic/CanBuildFrom.scala
+++ b/src/library/scala/collection/generic/CanBuildFrom.scala
@@ -13,17 +13,32 @@ package generic
 
 import mutable.Builder
 
-/** A base class for builder factories
+
+/** A base trait for builder factories.
+ *
+ *  @tparam From  the type of the underlying collection that requests
+ *                a builder to be created.
+ *  @tparam Elem  the element type of the collection to be created.
+ *  @tparam To    the type of the collection to be created.
  *
+ *  @see Builder
+ *  @author Martin Odersky
+ *  @author Adriaan Moors
  *  @since 2.8
  */
 trait CanBuildFrom[-From, -Elem, +To] {
 
-  /** Creates a new builder, using `from` as a prototype
-   * the resulting Builder will build the same kind of collection
+  /** Creates a new builder on request of a collection.
+   *  @param from  the collection requesting the builder to be created.
+   *  @return a builder for collections of type `To` with element type `Elem`.
+   *          The collections framework usually arranges things so
+   *          that the created builder will build the same kind of collection
+   *          as `from`.
    */
   def apply(from: From): Builder[Elem, To]
 
-  /** Creates a new builder from scratch */
+  /** Creates a new builder from scratch
+   *  @return a builder for collections of type `To` with element type `Elem`.
+   */
   def apply(): Builder[Elem, To]
 }
diff --git a/src/library/scala/collection/generic/GenericCompanion.scala b/src/library/scala/collection/generic/GenericCompanion.scala
index df9a3d9274..4332a1c936 100644
--- a/src/library/scala/collection/generic/GenericCompanion.scala
+++ b/src/library/scala/collection/generic/GenericCompanion.scala
@@ -14,21 +14,33 @@ package generic
 
 import mutable.Builder
 
-/**
- * @since 2.8
+/** A template class for companion objects of ``regular'' collection classes
+ *  represent an unconstrained higher-kinded type. Typically
+ *  such classes inherit from trait `GenericTraversableTemplate`.
+ *  @tparam  CC   The type constructor representing the collection class.
+ *  @see GenericTraversableTemplate
+ *  @author Martin Odersky
+ *  @since 2.8
+ *  @define coll  collection
+ *  @define Coll  CC
  */
 abstract class GenericCompanion[+CC[X] <: Traversable[X]] {
+  /** The underlying collection type with unknown element type */
   type Coll = CC[_]
 
+  /** The default builder for $Coll objects. */
   def newBuilder[A]: Builder[A, CC[A]]
 
- /** The empty iterable of type <code>CC</code>. */
+  /** The empty collection of type $Coll[A] */
   def empty[A]: CC[A] = newBuilder[A].result
 
-  /** Creates an iterable of type <code>CC</code> with specified elements. */
-  def apply[A](args: A*): CC[A] = {
+  /** Creates a $coll with the specified elements.
+   *  @param elems  the elements of the created $coll
+   *  @return a new $coll with elements `elems`
+   */
+  def apply[A](elems: A*): CC[A] = {
     val b = newBuilder[A]
-    b ++= args
+    b ++= elems
     b.result
   }
 }
diff --git a/src/library/scala/collection/generic/GenericTraversableTemplate.scala b/src/library/scala/collection/generic/GenericTraversableTemplate.scala
index 71557d6326..0ebcbe6a8b 100644
--- a/src/library/scala/collection/generic/GenericTraversableTemplate.scala
+++ b/src/library/scala/collection/generic/GenericTraversableTemplate.scala
@@ -15,24 +15,64 @@ package generic
 import mutable.Builder
 import annotation.unchecked.uncheckedVariance
 
-/**
- * @since 2.8
+/** A template class for companion objects of ``regular'' collection classes
+ *  that represent an unconstrained higher-kinded type.
+ *  @tparam  A    The type of the collection elements.
+ *  @tparam  CC   The type constructor representing the collection class.
+ *  @author Martin Odersky
+ *  @since 2.8
+ *  @define coll  collection
+ *  @define Coll  CC
  */
 trait GenericTraversableTemplate[+A, +CC[X] <: Traversable[X]] extends HasNewBuilder[A, CC[A] @uncheckedVariance] {
 
+  /** Applies a function `f` to all elements of this $coll.
+   *
+   *  @param  f   the function that is applied for its side-effect to every element.
+   *              The result of function `f` is discarded.
+   *
+   *  @tparam  U  the type parameter describing the result of function `f`.
+   *              This result will always be ignored. Typically `U` is `Unit`,
+   *              but this is not necessary.
+   *
+   *  @usecase def foreach(f: A => Unit): Unit
+   */
   def foreach[U](f: A => U): Unit
+
+  /** Selects the first element of this $coll.
+   *  @return  the first element of this $coll.
+   *  @throws `NoSuchElementException` if the $coll is empty.
+   */
   def head: A
+
+  /** Tests whether this $coll is empty.
+   *
+   *  @return    `true` if the $coll contain no elements, `false` otherwise.
+   */
   def isEmpty: Boolean
 
-  /** The factory companion object that builds instances of class CC */
+  /** The factory companion object that builds instances of class $Coll.
+   */
   def companion: GenericCompanion[CC]
 
-  /** The builder that builds instances of CC[A] */
+  /** The builder that builds instances of type $Coll[A]
+   */
   protected[this] def newBuilder: Builder[A, CC[A]] = companion.newBuilder[A]
 
-  /** The generic builder that builds instances of CC at arbitrary element types. */
+  /** The generic builder that builds instances of $Coll
+   *  at arbitrary element types.
+   */
   def genericBuilder[B]: Builder[B, CC[B]] = companion.newBuilder[B]
 
+  /** Converts this $coll of pairs into two collections of the first and second
+   *  halfs of each pair.
+   *  @param A1 the type of the first half of the element pairs
+   *  @param A2 the type of the second half of the element pairs
+   *  @param asPair an implicit conversion which asserts that the element type of this
+   *          $coll is a pair.
+   *  @return a pair ${coll}s, containing the first, respectively second half
+   *          of each element pair of this $coll.
+   */
   def unzip[A1, A2](implicit asPair: A => /*<:<!!!*/ (A1, A2)): (CC[A1], CC[A2]) = {
     val b1 = genericBuilder[A1]
     val b2 = genericBuilder[A2]
@@ -44,6 +84,13 @@ trait GenericTraversableTemplate[+A, +CC[X] <: Traversable[X]] extends HasNewBui
     (b1.result, b2.result)
   }
 
+  /** Converts this $coll of traversable collections into
+   *  a $coll in which all element collections are concatenated.
+   *  @B the type of the elements of each traversable collection.
+   *  @asTraversable an implicit conversion which asserts that the element type of this
+   *          $coll is a `Traversable`.
+   *  @return a new $coll reuslting from concatenating all element ${coll}s.
+   */
   def flatten[B](implicit asTraversable: A => /*<:<!!!*/ Traversable[B]): CC[B] = {
     val b = genericBuilder[B]
     for (xs <- this)
@@ -51,6 +98,13 @@ trait GenericTraversableTemplate[+A, +CC[X] <: Traversable[X]] extends HasNewBui
     b.result
   }
 
+  /** Transposes this $coll of traversable collections into
+   *  @B the type of the elements of each traversable collection.
+   *  @asTraversable an implicit conversion which asserts that the element type of this
+   *          $coll is a `Traversable`.
+   *  @return a two-dimensional $coll of ${coll}s which has as ''n''th row
+   *          the ''n''th column of this $coll.
+   */
   def transpose[B](implicit asTraversable: A => /*<:<!!!*/ Traversable[B]): CC[CC[B] @uncheckedVariance] = {
     val bs: IndexedSeq[Builder[B, CC[B]]] = asTraversable(head).map(_ => genericBuilder[B]).toIndexedSeq
     for (xs <- this) {
diff --git a/src/library/scala/collection/generic/Growable.scala b/src/library/scala/collection/generic/Growable.scala
index c5febe5fc2..7950dee9de 100644
--- a/src/library/scala/collection/generic/Growable.scala
+++ b/src/library/scala/collection/generic/Growable.scala
@@ -11,43 +11,53 @@
 package scala.collection
 package generic
 
-/** This class represents collections that can be augmented using a `+=` operator
- *  and that can be cleared of all elements using the `clear` method.
+/** This trait forms part of collections that can be augmented
+ *  using a `+=` operator and that can be cleared of all elements using
+ *  a `clear` method.
  *
  *  @author   Martin Odersky
  *  @owner   Martin Odersky
  *  @version 2.8
  *  @since   2.8
+ *  @define coll growable collection
+ *  @define Coll Growable
+ *  @define add  add
+ *  @define Add  add
  */
 trait Growable[-A] {
 
-  /** Adds a single element to this collection.
+  /** ${Add}s a single element to this $coll.
    *
-   *  @param elem  the element to add.
+   *  @param elem  the element to $add.
+   *  @return the $coll itself
    */
   def +=(elem: A): this.type
 
-  /** Adds two or more elements to this collection.
+  /** ${Add}s two or more elements to this $coll.
    *
-   *  @param elem1 the first element to add.
-   *  @param elem2 the second element to add.
-   *  @param elems the remaining elements to add.
+   *  @param elem1 the first element to $add.
+   *  @param elem2 the second element to $add.
+   *  @param elems the remaining elements to $add.
+   *  @return the $coll itself
    */
   def +=(elem1: A, elem2: A, elems: A*): this.type = this += elem1 += elem2 ++= elems
 
-  /** Adds a number of elements provided by an iterator to this collection.
+  /** ${Add}s all elements produced by an iterator to this $coll.
    *
-   *  @param iter  the iterator.
+   *  @param iter  the iterator producing the elements to $add.
+   *  @return  the $coll itself.
    */
   def ++=(iter: Iterator[A]): this.type = { iter foreach += ; this }
 
-  /** Adds a number of elements provided by an iterable object to this collection.
+  /** ${Add}s all elements contained in a traversable collection to this $coll.
    *
-   *  @param iter  the iterable object.
+   *  @param elems  the collection containing the elements to $add.
+   *  @return  the $coll itself.
    */
-  def ++=(iter: Traversable[A]): this.type = { iter foreach +=; this }
+  def ++=(elems: Traversable[A]): this.type = { elems foreach +=; this }
 
-  /** Clears the collection contents.
+  /** Clears the $coll's contents. After this operation, the
+   *  $coll is empty.
    */
   def clear()
 }
diff --git a/src/library/scala/collection/generic/Shrinkable.scala b/src/library/scala/collection/generic/Shrinkable.scala
index f096547714..bd773a97f9 100644
--- a/src/library/scala/collection/generic/Shrinkable.scala
+++ b/src/library/scala/collection/generic/Shrinkable.scala
@@ -11,26 +11,31 @@
 package scala.collection
 package generic
 
-/** This class represents collections that can be reduced using a -= operator.
+/** This trait forms part of collections that can be reduced
+ *  using a `-=` operator.
  *
  *  @author   Martin Odersky
  *  @owner   Martin Odersky
  *  @version 2.8
  *  @since   2.8
+ *  @define coll shrinkable collection
+ *  @define Coll Shrinkable
  */
 trait Shrinkable[-A] {
 
-  /** Removes a single element from this collection.
+  /** Removes a single element from this $coll.
    *
    *  @param elem  the element to remove.
+   *  @return the $coll itself
    */
   def -=(elem: A): this.type
 
-  /** Removes two or more elements from this collection.
+  /** Removes two or more elements from this $coll.
    *
    *  @param elem1 the first element to remove.
    *  @param elem2 the second element to remove.
    *  @param elems the remaining elements to remove.
+   *  @return the $coll itself
    */
   def -=(elem1: A, elem2: A, elems: A*): this.type = {
     this -= elem1
@@ -38,15 +43,17 @@ trait Shrinkable[-A] {
     this --= elems
   }
 
-  /** Removes a number of elements provided by an iterator from this collection.
+  /** Removes all elements produced by an iterator from this $coll.
    *
-   *  @param iter  the iterator.
+   *  @param iter  the iterator producing the elements to remove.
+   *  @return the $coll itself
    */
   def --=(iter: Iterator[A]): this.type = { iter foreach -=; this }
 
-  /** Removes a number of elements provided by an iterable object from this collection.
+  /** Removes all elements contained in a traversable collection from this $coll.
    *
-   *  @param iter  the iterable object.
+   *  @param iter  the collection containing the elements to remove.
+   *  @return the $coll itself
    */
   def --=(iter: Traversable[A]): this.type = { iter foreach -=; this }
 }
diff --git a/src/library/scala/collection/generic/Subtractable.scala b/src/library/scala/collection/generic/Subtractable.scala
index 2d5e9b5bf4..8ded9c22d1 100644
--- a/src/library/scala/collection/generic/Subtractable.scala
+++ b/src/library/scala/collection/generic/Subtractable.scala
@@ -11,46 +11,59 @@
 package scala.collection
 package generic
 
-/** This class represents collections that can be reduced using a - operator.
- *
+/** This trait represents collection-like objects that can be reduced
+ *  using a '+' operator. It defines variants of `-` and `--`
+ *  as convenience methods in terms of single-element removal `-`.
+ *  @tparam   A    the type of the elements of the $coll.
+ *  @tparam   Repr the type of the $coll itself
  *  @author   Martin Odersky
- *  @owner   Martin Odersky
  *  @version 2.8
  *  @since   2.8
+ *  @define  $coll collection
+ *  @define  $Coll Subtractable
  */
-trait Subtractable[A, +This <: Subtractable[A, This]] { self =>
+trait Subtractable[A, +Repr <: Subtractable[A, Repr]] { self =>
 
-  protected def repr: This
+  /** The representation object of type `Repr` which contains the collection's elements
+   */
+  protected def repr: Repr
 
-  /** Returns a new collection that contains all elements of the current collection
-   *  except a given element.
-   *
-   *  @param elem  the element to remove.
+  /** Creates a new $coll from this $coll with an element removed.
+   *  @param elem the element to remove
+   *  @return a new collection that contains all elements of the current $coll
+   *  except one less occurrence of `elem`.
    */
-  def -(elem: A): This
+  def -(elem: A): Repr
 
-  /** Returns a new collection that contains all elements of the current collection
-   *  except a two or more given elements.
+  /** Creates a new $coll from this $coll with some elements removed.
    *
+   *  This method takes two or more elements to be removed. Another overloaded
+   *  variant of this method handles the case where a single element is
+   *  removed.
    *  @param elem1 the first element to remove.
    *  @param elem2 the second element to remove.
    *  @param elems the remaining elements to remove.
+   *  @return a new $coll that contains all elements of the current $coll
+   *  except one less occurrence of each of the given elements.
    */
-  def -(elem1: A, elem2: A, elems: A*): This =
+  def -(elem1: A, elem2: A, elems: A*): Repr =
     this - elem1 - elem2 -- elems
 
-  /** Returns a new collection that contains all elements of the current collection
-   *  except the elements provided by a traversable object
+  /** Creates a new $coll from this $coll by removing all elements of another
+   *  collection.
    *
-   *  @param elems     the traversable object containing the elements that do not form part of the new collection.
+   *  @param elems     the collection containing the removed elements.
+   *  @return a new $coll that contains all elements of the current $coll
+   *  except one less occurrence of each of the elements of `elems`.
    */
-  def --(elems: Traversable[A]): This = (repr /: elems) (_ - _)
+  def --(elems: Traversable[A]): Repr = (repr /: elems) (_ - _)
 
-  /** Returns a new collection that contains all elements of the current collection
-   *  except the elements provided by an iterator
+  /** Creates a new $coll from this $coll by removing all elements produced
+   *  by an iterator.
    *
-   *  @param elems     the iterator containing the elements that do not form part of the new collection
-   *  @note  same as --
+   *  @param iter     the iterator producing the removed elements.
+   *  @return a new $coll that contains all elements of the current $coll
+   *  except one less occurrence of each of the elements produced by `iter`.
    */
-  def --(iter: Iterator[A]): This = (repr /: iter) (_ - _)
+  def --(iter: Iterator[A]): Repr = (repr /: iter) (_ - _)
 }
diff --git a/src/library/scala/collection/generic/TraversableFactory.scala b/src/library/scala/collection/generic/TraversableFactory.scala
index 6c87bfe5a2..4f2eb40a64 100644
--- a/src/library/scala/collection/generic/TraversableFactory.scala
+++ b/src/library/scala/collection/generic/TraversableFactory.scala
@@ -11,22 +11,54 @@
 package scala.collection
 package generic
 
-/** A template for companion objects of Traversable and subclasses thereof.
+/** A template for companion objects of `Traversable` and subclasses thereof.
+ *  This class provides a set of operations to create `$Coll` objects.
+ *  It is typically inherited by companion objects of subclasses of `Traversable`.
  *
  *  @since 2.8
+ *
+ *  @define $coll collection
+ *  @define @Coll Traversable
+ *  @define factoryInfo
+ *    This object provides a set of operations to create `$Coll` values.
+ *    @author Martin Odersky
+ *    @version 2.8
+ *  @define canBuildFromInfo
+ *    The standard `CanBuildFrom` instance for $Coll objects.
+ *    @see CanBuildFrom
+ *  @define genericCanBuildFromInfo
+ *    The standard `CanBuildFrom` instance for $Coll objects.
+ *    The created value is an instance of class `GenericCanBuildFrom`,
+ *    which forwards calls to create a new builder to the
+ *    `genericBuilder` method of the requesting collection.
+ *    @see CanBuildFrom
+ *    @see GenericCanBuildFrom
  */
 abstract class TraversableFactory[CC[X] <: Traversable[X] with GenericTraversableTemplate[X, CC]]
   extends GenericCompanion[CC] {
 
+  /** A generic implementation of the `CanBuildFrom` trait, which forwards
+   *  all calls to `apply(from)` to the `genericBuilder` methof of
+   *  $coll `from`, and which forwards all calls of `apply()` to the
+   *  `newBuilder` method of this factory.
+   */
   class GenericCanBuildFrom[A] extends CanBuildFrom[CC[_], A, CC[A]] {
+    /** Creates a new builder on request of a collection.
+     *  @param from  the collection requesting the builder to be created.
+     *  @return the result of invoking the `genericBuilder` method on `from`.
+     */
     def apply(from: Coll) = from.genericBuilder[A]
+
+    /** Creates a new builder from scratch
+     *  @return the result of invoking the `newBuilder` method of this factory.
+     */
     def apply() = newBuilder[A]
   }
 
-  /** Concatenate all the argument collections into a single collection.
+  /** Concatenates all argument collections into a single $coll.
    *
-   *  @param xss the collections that are to be concatenated
-   *  @return the concatenation of all the collections
+   *  @param xss the collections that are to be concatenated.
+   *  @return the concatenation of all the collections.
    */
   def concat[A](xss: Traversable[A]*): CC[A] = {
     val b = newBuilder[A]
@@ -34,9 +66,10 @@ abstract class TraversableFactory[CC[X] <: Traversable[X] with GenericTraversabl
     b.result
   }
 
-  /** A traversable that contains the results of some element computation a number of times.
-   *  @param   n  the number of elements returned
+  /** Produces a $coll containing the results of some element computation a number of times.
+   *  @param   n  the number of elements contained in the $coll.
    *  @param   elem the element computation
+   *  @return  A $coll that contains the results of `n` evaluations of `elem`.
    */
   def fill[A](n: Int)(elem: => A): CC[A] = {
     val b = newBuilder[A]
@@ -48,48 +81,52 @@ abstract class TraversableFactory[CC[X] <: Traversable[X] with GenericTraversabl
     b.result
   }
 
-  /** A two-dimensional traversable that contains the results of some element computation a number of times.
+  /** Produces a two-dimensional $coll containing the results of some element computation a number of times.
    *  @param   n1  the number of elements in the 1st dimension
    *  @param   n2  the number of elements in the 2nd dimension
    *  @param   elem the element computation
+   *  @return  A $coll that contains the results of `n1 x n2` evaluations of `elem`.
    */
   def fill[A](n1: Int, n2: Int)(elem: => A): CC[CC[A]] =
     tabulate(n1)(_ => fill(n2)(elem))
 
-  /** A three-dimensional traversable that contains the results of some element computation a number of times.
+  /** Produces a three-dimensional $coll containing the results of some element computation a number of times.
    *  @param   n1  the number of elements in the 1st dimension
    *  @param   n2  the number of elements in the 2nd dimension
    *  @param   n3  the number of elements in the 3nd dimension
    *  @param   elem the element computation
+   *  @return  A $coll that contains the results of `n1 x n2 x n3` evaluations of `elem`.
    */
   def fill[A](n1: Int, n2: Int, n3: Int)(elem: => A): CC[CC[CC[A]]] =
     tabulate(n1)(_ => fill(n2, n3)(elem))
 
-  /** A four-dimensional traversable that contains the results of some element computation a number of times.
+  /** Produces a four-dimensional $coll containing the results of some element computation a number of times.
    *  @param   n1  the number of elements in the 1st dimension
    *  @param   n2  the number of elements in the 2nd dimension
    *  @param   n3  the number of elements in the 3nd dimension
    *  @param   n4  the number of elements in the 4th dimension
    *  @param   elem the element computation
+   *  @return  A $coll that contains the results of `n1 x n2 x n3 x n4` evaluations of `elem`.
    */
   def fill[A](n1: Int, n2: Int, n3: Int, n4: Int)(elem: => A): CC[CC[CC[CC[A]]]] =
     tabulate(n1)(_ => fill(n2, n3, n4)(elem))
 
-  /** A five-dimensional traversable that contains the results of some element computation a number of times.
+  /** Produces a five-dimensional $coll containing the results of some element computation a number of times.
    *  @param   n1  the number of elements in the 1st dimension
    *  @param   n2  the number of elements in the 2nd dimension
    *  @param   n3  the number of elements in the 3nd dimension
    *  @param   n4  the number of elements in the 4th dimension
    *  @param   n5  the number of elements in the 5th dimension
    *  @param   elem the element computation
+   *  @return  A $coll that contains the results of `n1 x n2 x n3 x n4 x n5` evaluations of `elem`.
    */
   def fill[A](n1: Int, n2: Int, n3: Int, n4: Int, n5: Int)(elem: => A): CC[CC[CC[CC[CC[A]]]]] =
     tabulate(n1)(_ => fill(n2, n3, n4, n5)(elem))
 
-  /** A traversable containing values of a given function over a range of integer values starting from 0.
-   *  @param  n   The number of elements in the traversable
+  /** Produces a $coll containing values of a given function over a range of integer values starting from 0.
+   *  @param  n   The number of elements in the $coll
    *  @param  f   The function computing element values
-   *  @return A traversable consisting of elements `f(0), ..., f(n -1)`
+   *  @return A $coll consisting of elements `f(0), ..., f(n -1)`
    */
   def tabulate[A](n: Int)(f: Int => A): CC[A] = {
     val b = newBuilder[A]
@@ -101,58 +138,65 @@ abstract class TraversableFactory[CC[X] <: Traversable[X] with GenericTraversabl
     b.result
   }
 
-  /** A two-dimensional traversable containing values of a given function over ranges of integer values starting from 0.
+  /** Produces a two-dimensional $coll containing values of a given function over ranges of integer values starting from 0.
    *  @param   n1  the number of elements in the 1st dimension
    *  @param   n2  the number of elements in the 2nd dimension
    *  @param   f   The function computing element values
+   *  @return A $coll consisting of elements `f(i1, i2)`
+   *          for `0 <= i1 < n1` and `0 <= i2 < n2`.
    */
   def tabulate[A](n1: Int, n2: Int)(f: (Int, Int) => A): CC[CC[A]] =
     tabulate(n1)(i1 => tabulate(n2)(f(i1, _)))
 
-  /** A three-dimensional traversable containing values of a given function over ranges of integer values starting from 0.
+  /** Produces a three-dimensional $coll containing values of a given function over ranges of integer values starting from 0.
    *  @param   n1  the number of elements in the 1st dimension
    *  @param   n2  the number of elements in the 2nd dimension
    *  @param   n3  the number of elements in the 3nd dimension
    *  @param   f   The function computing element values
+   *  @return A $coll consisting of elements `f(i1, i2, i3)`
+   *          for `0 <= i1 < n1`, `0 <= i2 < n2`, and `0 <= i3 < n3`.
    */
   def tabulate[A](n1: Int, n2: Int, n3: Int)(f: (Int, Int, Int) => A): CC[CC[CC[A]]] =
     tabulate(n1)(i1 => tabulate(n2, n3)(f(i1, _, _)))
 
-  /** A four-dimensional traversable containing values of a given function over ranges of integer values starting from 0.
+  /** Produces a four-dimensional $coll containing values of a given function over ranges of integer values starting from 0.
    *  @param   n1  the number of elements in the 1st dimension
    *  @param   n2  the number of elements in the 2nd dimension
    *  @param   n3  the number of elements in the 3nd dimension
    *  @param   n4  the number of elements in the 4th dimension
    *  @param   f   The function computing element values
+   *  @return A $coll consisting of elements `f(i1, i2, i3, i4)`
+   *          for `0 <= i1 < n1`, `0 <= i2 < n2`, `0 <= i3 < n3`, and `0 <= i4 < n4`.
    */
   def tabulate[A](n1: Int, n2: Int, n3: Int, n4: Int)(f: (Int, Int, Int, Int) => A): CC[CC[CC[CC[A]]]] =
     tabulate(n1)(i1 => tabulate(n2, n3, n4)(f(i1, _, _, _)))
 
-  /** A five-dimensional traversable containing values of a given function over ranges of integer values starting from 0.
+  /** Produces a five-dimensional $coll containing values of a given function over ranges of integer values starting from 0.
    *  @param   n1  the number of elements in the 1st dimension
    *  @param   n2  the number of elements in the 2nd dimension
    *  @param   n3  the number of elements in the 3nd dimension
    *  @param   n4  the number of elements in the 4th dimension
    *  @param   n5  the number of elements in the 5th dimension
    *  @param   f   The function computing element values
+   *  @return A $coll consisting of elements `f(i1, i2, i3, i4, i5)`
+   *          for `0 <= i1 < n1`, `0 <= i2 < n2`, `0 <= i3 < n3`, `0 <= i4 < n4`, and `0 <= i5 < n5`.
    */
   def tabulate[A](n1: Int, n2: Int, n3: Int, n4: Int, n5: Int)(f: (Int, Int, Int, Int, Int) => A): CC[CC[CC[CC[CC[A]]]]] =
     tabulate(n1)(i1 => tabulate(n2, n3, n4, n5)(f(i1, _, _, _, _)))
 
-  /** A traversable containing a sequence of increasing integers in a range.
+  /** Produces a $coll containing a sequence of increasing of integers.
    *
-   *  @param from the start value of the traversable
-   *  @param end the end value of the traversable (the first value NOT returned)
-   *  @return  the traversable with values in range `start, start + 1, ..., end - 1`
-   *  up to, but exclusding, `end`.
+   *  @param from the first element of the $coll
+   *  @param end the end value of the $coll (the first value NOT contained)
+   *  @return  a $coll with values `start, start + 1, ..., end - 1`
    */
   def range(start: Int, end: Int): CC[Int] = range(start, end, 1)
 
-  /** A traversable containing equally spaced values in some integer interval.
-    *  @param start the start value of the traversable
-   *  @param end   the end value of the traversable (the first value NOT returned)
-   *  @param step  the increment value of the traversable (must be positive or negative)
-   *  @return      the traversable with values in `start, start + step, ...` up to, but excluding `end`
+  /** Produces a $coll containing equally spaced values in some integer interval.
+   *  @param start the start value of the $coll
+   *  @param end   the end value of the $coll (the first value NOT contained)
+   *  @param step  the difference between successive elements of the $coll (must be positive or negative)
+   *  @return      a $coll with values `start, start + step, ...` up to, but excluding `end`
    */
   def range(start: Int, end: Int, step: Int): CC[Int] = {
     if (step == 0) throw new IllegalArgumentException("zero step")
@@ -165,12 +209,12 @@ abstract class TraversableFactory[CC[X] <: Traversable[X] with GenericTraversabl
     b.result
   }
 
-  /** A traversable containing repeated applications of a function to a start value.
+  /** Produces a $coll containing repeated applications of a function to a start value.
    *
-   *  @param start the start value of the traversable
-   *  @param len   the number of elements returned by the traversable
+   *  @param start the start value of the $coll
+   *  @param len   the number of elements contained inthe $coll
    *  @param f     the function that's repeatedly applied
-   *  @return      the traversable returning `len` values in the sequence `start, f(start), f(f(start)), ...`
+   *  @return      a $coll with `len` values in the sequence `start, f(start), f(f(start)), ...`
    */
   def iterate[A](start: A, len: Int)(f: A => A): CC[A] = {
     val b = newBuilder[A]
diff --git a/src/library/scala/collection/immutable/BitSet.scala b/src/library/scala/collection/immutable/BitSet.scala
index c8368d4480..e06218ff92 100644
--- a/src/library/scala/collection/immutable/BitSet.scala
+++ b/src/library/scala/collection/immutable/BitSet.scala
@@ -16,7 +16,10 @@ import generic._
 import BitSetLike.{LogWL, updateArray}
 
 /** A base class for immutable bit sets.
+ *  $bitsetinfo
  *
+ *  @author Martin Odersky
+ *  @version 2.8
  *  @since 1
  */
 @serializable @SerialVersionUID(1611436763290191562L)
@@ -35,7 +38,7 @@ abstract class BitSet extends Set[Int]
   /** Adds element to bitset, returning a new set.
    */
   def + (elem: Int): BitSet = {
-    require(elem >= 0)
+    require(elem >= 0, "bitset element must be >= 0")
     if (contains(elem)) this
     else {
       val idx = elem >> LogWL
@@ -46,7 +49,7 @@ abstract class BitSet extends Set[Int]
   /** Removes element from bitset, returning a new set
    */
   def - (elem: Int): BitSet = {
-    require(elem >= 0)
+    require(elem >= 0, "bitset element must be >= 0")
     if (contains(elem)) {
       val idx = elem >> LogWL
       updateWord(idx, word(idx) & ~(1L << elem))
diff --git a/src/library/scala/collection/immutable/List.scala b/src/library/scala/collection/immutable/List.scala
index acb1438f6c..9c5984db54 100644
--- a/src/library/scala/collection/immutable/List.scala
+++ b/src/library/scala/collection/immutable/List.scala
@@ -16,11 +16,12 @@ import generic._
 import mutable.{Builder, ListBuffer}
 import annotation.tailrec
 
-/** A class representing an ordered collection of elements of type
- *  `a`. This class comes with two implementing case
- *  classes `scala.Nil` and `scala.::` that
- *  implement the abstract members `isEmpty`,
- *  `head` and `tail`.
+/** A class for immutable linked lists representing ordered collections
+ *  of elements of type.
+ *
+ * This class comes with two implementing case classes `scala.Nil`
+ * and `scala.::` that implement the abstract members `isEmpty`,
+ * `head` and `tail`.
  *
  *  @author  Martin Odersky and others
  *  @version 2.8
@@ -50,58 +51,40 @@ sealed abstract class List[+A] extends LinearSeq[A]
 
   import scala.collection.{Iterable, Traversable, Seq, IndexedSeq}
 
-  /** Returns true if the list does not contain any elements.
-   *  @return `true`, iff the list is empty.
-   */
   def isEmpty: Boolean
-
-  /** Returns this first element of the list.
-   *
-   *  @return the first element of this list.
-   *  @throws Predef.NoSuchElementException if the list is empty.
-   */
   def head: A
-
-  /** Returns this list without its first element.
-   *
-   *  @return this list without its first element.
-   *  @throws Predef.NoSuchElementException if the list is empty.
-   */
   def tail: List[A]
 
   // New methods in List
 
-  /** <p>
-   *    Add an element `x` at the beginning of this list.
-   *  </p>
-   *
+  /** Adds an element at the beginning of this list.
    *  @param x the element to prepend.
-   *  @return  the list with `x` added at the beginning.
+   *  @return  a list which contains `x` as first element and
+   *           which continues with this list.
    *  @ex `1 :: List(2, 3) = List(2, 3).::(1) = List(1, 2, 3)`
+   *  @usecase def ::(x: A): List[A]
    */
   def ::[B >: A] (x: B): List[B] =
     new scala.collection.immutable.::(x, this)
 
-  /** <p>
-   *    Returns a list resulting from the concatenation of the given
+  /** Adds the elements of a given list in front of this list.
+   *  @param prefix  The list elements to prepend.
+   *  @return a list resulting from the concatenation of the given
    *    list `prefix` and this list.
-   *  </p>
-   *
-   *  @param prefix the list to concatenate at the beginning of this list.
-   *  @return the concatenation of the two lists.
    *  @ex `List(1, 2) ::: List(3, 4) = List(3, 4).:::(List(1, 2)) = List(1, 2, 3, 4)`
+   *  @usecase def :::(prefix: List[A]): List[A]
    */
   def :::[B >: A](prefix: List[B]): List[B] =
     if (isEmpty) prefix
     else (new ListBuffer[B] ++= prefix).prependToList(this)
 
-  /** Reverse the given prefix and append the current list to that.
-   *  This function is equivalent to an application of `reverse`
-   *  on the prefix followed by a call to `:::`, but is more
-   *  efficient.
+  /** Adds the elements of a given list in reverse order in front of this list.
+   *  `xs reverse_::: ys` is equivalent to
+   *  `xs.reverse ::: ys` but is more efficient.
    *
    *  @param prefix the prefix to reverse and then prepend
    *  @return       the concatenation of the reversed prefix and the current list.
+   *  @usecase def reverse_:::(prefix: List[A]): List[A]
    */
   def reverse_:::[B >: A](prefix: List[B]): List[B] = {
     var these: List[B] = this
@@ -113,9 +96,17 @@ sealed abstract class List[+A] extends LinearSeq[A]
     these
   }
 
-  /** Like xs map f, but returns `xs` unchanged if function
+  /** Builds a new list by applying a function to all elements of this list.
+   *  Like `xs map f`, but returns `xs` unchanged if function
    *  `f` maps all elements to themselves (wrt ==).
-   *  @note Unlike `map`, `mapConserve` is not tail-recursive.
+   *
+   *  Note: Unlike `map`, `mapConserve` is not tail-recursive.
+   *
+   *  @param f      the function to apply to each element.
+   *  @tparam B     the element type of the returned collection.
+   *  @return       a list resulting from applying the given function
+   *                `f` to each element of this list and collecting the results.
+   *  @usecase def mapConserve[B](f: A => B): List[A]
    */
   def mapConserve[B >: A] (f: A => B): List[B] = {
     def loop(ys: List[A]): List[B] =
@@ -144,33 +135,17 @@ sealed abstract class List[+A] extends LinearSeq[A]
 
   // Overridden methods from IterableLike or overloaded variants of such methods
 
-  /** Create a new list which contains all elements of this list
-   *  followed by all elements of Traversable `that'
-   */
   override def ++[B >: A, That](that: Traversable[B])(implicit bf: CanBuildFrom[List[A], B, That]): That = {
     val b = bf(this)
     if (b.isInstanceOf[ListBuffer[_]]) (this ::: that.toList).asInstanceOf[That]
     else super.++(that)
   }
 
-  /** Create a new list which contains all elements of this list
-   *  followed by all elements of Iterator `that'
-   */
   override def ++[B >: A, That](that: Iterator[B])(implicit bf: CanBuildFrom[List[A], B, That]): That =
     this ++ that.toList
 
-  /** Overrides the method in Iterable for efficiency.
-   *
-   *  @return  the list itself
-   */
   override def toList: List[A] = this
 
-  /** Returns the `n` first elements of this list, or else the whole
-   *  list, if it has less than `n` elements.
-
-   *  @param n the number of elements to take.
-   *  @return the `n` first elements of this list.
-   */
   override def take(n: Int): List[A] = {
     val b = new ListBuffer[A]
     var i = 0
@@ -184,12 +159,6 @@ sealed abstract class List[+A] extends LinearSeq[A]
     else b.toList
   }
 
-  /** Returns the list without its `n` first elements.
-   *  If this list has less than `n` elements, the empty list is returned.
-   *
-   *  @param n the number of elements to drop.
-   *  @return the list without its `n` first elements.
-   */
   override def drop(n: Int): List[A] = {
     var these = this
     var count = n
@@ -200,23 +169,12 @@ sealed abstract class List[+A] extends LinearSeq[A]
     these
   }
 
-  /** Returns the list with elements belonging to the given index range.
-   *
-   *  @param start the start position of the list slice.
-   *  @param end   the end position (exclusive) of the list slice.
-   *  @return the list with elements belonging to the given index range.
-   */
   override def slice(start: Int, end: Int): List[A] = {
     var len = end
     if (start > 0) len -= start
     drop(start) take len
   }
 
-  /** Returns the rightmost `n` elements from this list.
-   *
-   *  @param n the number of elements to take
-   *  @return the suffix of length `n` of the list
-   */
   override def takeRight(n: Int): List[A] = {
     @tailrec
     def loop(lead: List[A], lag: List[A]): List[A] = lead match {
@@ -226,15 +184,8 @@ sealed abstract class List[+A] extends LinearSeq[A]
     loop(drop(n), this)
   }
 
-  // dropRight is inherited from Stream
+  // dropRight is inherited from LinearSeq
 
-  /** Split the list at a given point and return the two parts thus
-   *  created.
-   *
-   *  @param n the position at which to split
-   *  @return  a pair of lists composed of the first `n`
-   *           elements, and the other elements.
-   */
   override def splitAt(n: Int): (List[A], List[A]) = {
     val b = new ListBuffer[A]
     var i = 0
@@ -247,13 +198,6 @@ sealed abstract class List[+A] extends LinearSeq[A]
     (b.toList, these)
   }
 
-  /** Returns the longest prefix of this list whose elements satisfy
-   *  the predicate `p`.
-   *
-   *  @param p the test predicate.
-   *  @return  the longest prefix of this list whose elements satisfy
-   *           the predicate `p`.
-   */
   override def takeWhile(p: A => Boolean): List[A] = {
     val b = new ListBuffer[A]
     var these = this
@@ -264,13 +208,6 @@ sealed abstract class List[+A] extends LinearSeq[A]
     b.toList
   }
 
-  /** Returns the longest suffix of this list whose first element
-   *  does not satisfy the predicate `p`.
-   *
-   *  @param p the test predicate.
-   *  @return  the longest suffix of the list whose first element
-   *           does not satisfy the predicate `p`.
-   */
   override def dropWhile(p: A => Boolean): List[A] = {
     @tailrec
     def loop(xs: List[A]): List[A] =
@@ -280,13 +217,6 @@ sealed abstract class List[+A] extends LinearSeq[A]
     loop(this)
   }
 
-  /** Returns the longest prefix of the list whose elements all satisfy
-   *  the given predicate, and the rest of the list.
-   *
-   *  @param p the test predicate
-   *  @return  a pair consisting of the longest prefix of the list whose
-   *           elements all satisfy `p`, and the rest of the list.
-   */
   override def span(p: A => Boolean): (List[A], List[A]) = {
     val b = new ListBuffer[A]
     var these = this
@@ -297,8 +227,6 @@ sealed abstract class List[+A] extends LinearSeq[A]
     (b.toList, these)
   }
 
-  /** A list consisting of all elements of this list in reverse order.
-   */
   override def reverse: List[A] = {
     var result: List[A] = Nil
     var these = this
@@ -454,7 +382,7 @@ case object Nil extends List[Nothing] {
   override def head: Nothing =
     throw new NoSuchElementException("head of empty list")
   override def tail: List[Nothing] =
-    throw new NoSuchElementException("tail of empty list")
+    throw new UnsupportedOperationException("tail of empty list")
   // Removal of equals method here might lead to an infinite recusion similar to IntMap.equals.
   override def equals(that: Any) = that match {
     case that1: Seq[_] => that1.isEmpty
@@ -463,7 +391,9 @@ case object Nil extends List[Nothing] {
 }
 
 /** A non empty list characterized by a head and a tail.
- *
+ *  @param hd   the first element of the list
+ *  @param tl   the list containing the remaining elements of this list after the first one.
+ *  @tparam B   the type of the list elements.
  *  @author  Martin Odersky
  *  @version 1.0, 15/07/2003
  *  @since   2.8
@@ -498,18 +428,14 @@ final case class ::[B](private var hd: B, private[scala] var tl: List[B]) extend
   }
 }
 
-/** This object provides methods for creating specialized lists, and for
- *  transforming special kinds of lists (e.g. lists of lists).
- *
- *  @author  Martin Odersky
- *  @version 2.8
- *  @since   2.8
- */
+/** $factoryInfo */
 object List extends SeqFactory[List] {
 
   import scala.collection.{Iterable, Seq, IndexedSeq}
 
+  /** $genericCanBuildFromInfo */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, List[A]] = new GenericCanBuildFrom[A]
+
   def newBuilder[A]: Builder[A, List[A]] = new ListBuffer[A]
 
   override def empty[A]: List[A] = Nil
diff --git a/src/library/scala/collection/immutable/NumericRange.scala b/src/library/scala/collection/immutable/NumericRange.scala
index b01c01d7e9..5514f7a24d 100644
--- a/src/library/scala/collection/immutable/NumericRange.scala
+++ b/src/library/scala/collection/immutable/NumericRange.scala
@@ -41,7 +41,7 @@ extends IndexedSeq[T]
 {
   import num._
 
-  private def fail(msg: String) = throw new UnsupportedOperationException(msg)
+  private def fail(msg: String) = throw new IllegalArgumentException(msg)
 
   if (step equiv zero)
     fail("NumericRange step cannot be zero.")
diff --git a/src/library/scala/collection/mutable/AddingBuilder.scala b/src/library/scala/collection/mutable/AddingBuilder.scala
index cbadf29a0a..06822e859b 100644
--- a/src/library/scala/collection/mutable/AddingBuilder.scala
+++ b/src/library/scala/collection/mutable/AddingBuilder.scala
@@ -13,17 +13,21 @@ package mutable
 
 import generic._
 
-/** The canonical builder for collections that are addable, i.e. that support an efficient + method
+/** 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.
+ *  Collections are built from their empty element using this `+` method.
+ *  @param empty  the empty element of the collection.
+ *  @tparam Elem  the type of elements that get added to the builder.
+ *  @tparam To    the type of the built collection.
  *
+ *  @author Martin Odersky
+ *  @version 2.8
  *  @since 2.8
  */
-class AddingBuilder[A, Coll <: Addable[A, Coll] with scala.collection.Iterable[A] with scala.collection.IterableLike[A, Coll]](empty: Coll)
-extends Builder[A, Coll] {
-  protected var elems: Coll = empty
-  def +=(x: A): this.type = { elems = elems + x; this }
+class AddingBuilder[Elem, To <: Addable[Elem, To] with scala.collection.Iterable[Elem] with scala.collection.IterableLike[Elem, To]](empty: To)
+extends Builder[Elem, To] {
+  protected var elems: To = empty
+  def +=(x: Elem): this.type = { elems = elems + x; this }
   def clear() { elems = empty }
-  def result: Coll = elems
+  def result: To = elems
 }
diff --git a/src/library/scala/collection/mutable/ArrayBuffer.scala b/src/library/scala/collection/mutable/ArrayBuffer.scala
index 9afcd9f6ad..c60cbcd68c 100644
--- a/src/library/scala/collection/mutable/ArrayBuffer.scala
+++ b/src/library/scala/collection/mutable/ArrayBuffer.scala
@@ -112,8 +112,7 @@ class ArrayBuffer[A](override protected val initialSize: Int)
    *  @throws Predef.IndexOutOfBoundsException if <code>n</code> is out of bounds.
    */
   def insertAll(n: Int, seq: Traversable[A]) {
-    if ((n < 0) || (n > size0))
-      throw new IndexOutOfBoundsException(n.toString)
+    if (n < 0 || n > size0) throw new IndexOutOfBoundsException(n.toString)
     val xs = seq.toList
     val len = xs.length
     ensureSize(size0 + len)
@@ -130,8 +129,8 @@ class ArrayBuffer[A](override protected val initialSize: Int)
    *  @throws Predef.IndexOutOfBoundsException if <code>n</code> is out of bounds.
    */
   override def remove(n: Int, count: Int) {
-    if ((n < 0) || (n >= size0) && count > 0)
-      throw new IndexOutOfBoundsException(n.toString)
+    require(count >= 0, "removing negative number of elements")
+    if (n < 0 || n > size0 - count) throw new IndexOutOfBoundsException(n.toString)
     copy(n + count, n, size0 - (n + count))
     size0 -= count
   }
diff --git a/src/library/scala/collection/mutable/BitSet.scala b/src/library/scala/collection/mutable/BitSet.scala
index 2744c04b24..92dad18956 100644
--- a/src/library/scala/collection/mutable/BitSet.scala
+++ b/src/library/scala/collection/mutable/BitSet.scala
@@ -16,7 +16,10 @@ import generic._
 import BitSetLike.{LogWL, updateArray}
 
 /** A class for mutable bitsets.
+ *  $bitsetinfo
  *
+ *  @author Martin Odersky
+ *  @version 2.8
  *  @since 1
  */
 @serializable @SerialVersionUID(8483111450368547763L)
@@ -48,9 +51,6 @@ class BitSet(protected var elems: Array[Long]) extends Set[Int]
 
   protected def fromArray(words: Array[Long]): BitSet = new BitSet(words)
 
-  /** Adds element to bitset,
-   *  @return element was already present.
-   */
   override def add(elem: Int): Boolean = {
     require(elem >= 0)
     if (contains(elem)) false
@@ -61,9 +61,6 @@ class BitSet(protected var elems: Array[Long]) extends Set[Int]
     }
   }
 
-  /** Removes element from bitset.
-   *  @return element was already present.
-   */
   override def remove(elem: Int): Boolean = {
     require(elem >= 0)
     if (contains(elem)) {
@@ -79,6 +76,11 @@ class BitSet(protected var elems: Array[Long]) extends Set[Int]
   override def clear() {
     elems = new Array[Long](elems.length)
   }
+
+  /** Wraps this bitset as an immutable bitset backed by the array of bits
+   *  of this bitset.
+   *  @note Subsequent changes in this bitset will be reflected in the returned immutable bitset.
+   */
   def toImmutable = immutable.BitSet.fromArray(elems)
 
   override def clone(): BitSet = {
@@ -88,8 +90,8 @@ class BitSet(protected var elems: Array[Long]) extends Set[Int]
   }
 }
 
-/** A factory object for mutable bitsets */
 object BitSet extends BitSetFactory[BitSet] {
   def empty: BitSet = new BitSet
+  /** $canBuildFromInfo */
   implicit def canBuildFrom: CanBuildFrom[BitSet, Int, BitSet] = bitsetCanBuildFrom
 }
diff --git a/src/library/scala/collection/mutable/BufferLike.scala b/src/library/scala/collection/mutable/BufferLike.scala
index b86caa644a..3516a60233 100644
--- a/src/library/scala/collection/mutable/BufferLike.scala
+++ b/src/library/scala/collection/mutable/BufferLike.scala
@@ -15,16 +15,49 @@ package mutable
 import generic._
 import script._
 
-/** Buffers are used to create sequences of elements incrementally by
+/** A template trait for buffers of type `Buffer[A]`.
+ *
+ *  Buffers are used to create sequences of elements incrementally by
  *  appending, prepending, or inserting new elements. It is also
  *  possible to access and modify elements in a random access fashion
  *  via the index of the element in the current sequence.
-  *
+ *
+ *  @tparam A    the type of the elements of the buffer
+ *  @tparam This the type of the buffer itself.
+ *
+ *  $buffernote
+ *
+ *  @author  Martin Odersky
+ *  @author  Matthias Zenger
+ *  @version 2.8
+ *  @since 2.8
  *  @author Matthias Zenger
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   2.8
-  */
+ *  @define buffernote @note
+ *    This trait provides most of the operations of a `Buffer` independently of its representation.
+ *    It is typically inherited by concrete implementations of buffers.
+ *
+ *    To implement a concrete buffer, you need to provide implementations of the
+ *    following methods:
+ *    {{{
+ *       def apply(idx: Int): A
+ *       def update(idx: Int, elem: A)
+ *       def length: Int
+ *       def clear()
+ *       def +=(elem: A): this.type
+ *       def +=:(elem: A): this.type
+ *       def insertAll(n: Int, iter: Traversable[A])
+ *       def remove(n: Int): A
+ *    }}}
+ *  @define coll buffer
+ *  @define Coll Buffer
+ *  @define add  append
+ *  @define Add  Append
+ *  @define willNotTerminateInf
+ *  @define mayNotTerminateInf
+ */
 @cloneable
 trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
                 extends Growable[A]
@@ -38,71 +71,50 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
 
   import scala.collection.{Iterable, Traversable}
 
-// Abstract methods from IndexedSeq:
+  // Abstract methods from IndexedSeq:
 
-  /** Return element at index `n`
-   *  @throws   IndexOutofBoundsException if the index is not valid
-   */
   def apply(n: Int): A
-
-  /** Replace element at index <code>n</code> with the new element
-   *  <code>newelem</code>.
-   *
-   *  @param n       the index of the element to replace.
-   *  @param newelem the new element.
-   *  @throws   IndexOutofBoundsException if the index is not valid
-   */
   def update(n: Int, newelem: A)
-
-  /** Return number of elements in the buffer
-   */
   def length: Int
 
-// Abstract methods from Appendabl
+  // Abstract methods from Growable:
 
-  /** Append a single element to this buffer.
-   *
-   *  @param elem  the element to append.
-   */
   def +=(elem: A): this.type
-
-  /** Clears the buffer contents.
-   */
   def clear()
 
-// Abstract methods new in this class
-  /** Prepend a single element to this buffer and return
-   *  the identity of the buffer.
+  // Abstract methods new in this class:
+
+  /** Prepends a single element to this buffer.
    *  @param elem  the element to prepend.
+   *  @return      the buffer itself.
    */
   def +=:(elem: A): this.type
 
-  @deprecated("use `+=:' instead")
-  final def +:(elem: A): This = +=:(elem)
-
-  /** Inserts new elements at the index <code>n</code>. Opposed to method
-   *  <code>update</code>, this method will not replace an element with a
-   *  one. Instead, it will insert a new element at index <code>n</code>.
-   *
-   *  @param n     the index where a new element will be inserted.
-   *  @param iter    the iterable object providing all elements to insert.
-   *  @throws   IndexOutofBoundsException if the index is not valid
-   */
-  def insertAll(n: Int, iter: Traversable[A])
-
-
-  /** Removes the element on a given index position.
+  /** Inserts new elements at a given index into this buffer.
    *
-   *  @param n  the index which refers to the element to delete.
-   *  @return   the previous element
+   *  @param n      the index where new elements are inserted.
+   *  @param elems  the traversable collection containing the elements to insert.
+   *  @throws   IndexOutofBoundsException if the index `n` is not in the valid range
+   *            `0 <= n <= length`.
    */
+  def insertAll(n: Int, elems: Traversable[A])
+
+   /** Removes the element at a given index from this buffer.
+    *
+    *  @param n  the index which refers to the element to delete.
+    *  @return   the previous element at index `n`
+    *   @throws   IndexOutofBoundsException if the if the index `n` is not in the valid range
+    *            `0 <= n < length`.
+    */
   def remove(n: Int): A
 
-  /** Removes  a number of elements from a given index position.
+  /** Removes a number of elements from a given index position.
    *
-   *  @param n  the index which refers to the element to delete.
-   *  @param count  the number of elements to delete
-   *  @throws   IndexOutofBoundsException if the index is not valid
+   *  @param n  the index which refers to the first element to remove.
+   *  @param count  the number of elements to remove.
+   *  @throws   IndexOutofBoundsException if the index `n` is not in the valid range
+   *            `0 <= n <= length - count`.
+   *  @throws   IllegalArgumentException if `count < 0`.
    */
   def remove(n: Int, count: Int) {
     for (i <- 0 until count) remove(n)
@@ -112,6 +124,7 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
    *  If the buffer does not contain that element, it is unchanged.
    *
    *  @param x  the element to remove.
+   *  @return   the buffer itself
    */
   def -= (x: A): this.type = {
     val i = indexOf(x)
@@ -119,77 +132,68 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
     this
   }
 
-  /** Prepends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method. The identity of the
-   *  buffer is returned.(repr /: elems) (_ plus _)
-   *
-   *  @param iter  the iterable object.
+  /** Prepends the elements contained in a traversable collection
+   *  to this buffer.
+   *  @param elems  the collection containing the elements to prepend.
+   *  @return the buffer itself.
    */
-  def ++=:(iter: Traversable[A]): this.type = { insertAll(0, iter); this }
-
-  @deprecated("use ++=: instead")
-  final def ++:(iter: Traversable[A]): This = ++=:(iter)
+  def ++=:(elems: Traversable[A]): this.type = { insertAll(0, elems); this }
 
-  /** Prepends a number of elements provided by an iterator
-   *  The identity of the buffer is returned.
+  /** Prepends the elements produced by an iterator to this buffer.
    *
-   *  @param iter   the iterator
-   *  @return       the updated buffer.
+   *  @param iter   the iterator producing the elements to prepend.
+   *  @return       the buffer itself.
    */
-  def ++=:(iter: Iterator[A]): This = { insertAll(0, iter.toSeq); this }
+  def ++=:(iter: Iterator[A]): this.type = { insertAll(0, iter.toSeq); this }
 
-  /** Appends elements to this buffer.
+  /** Appends the given elements to this buffer.
    *
    *  @param elems  the elements to append.
    */
   def append(elems: A*) { this ++= elems }
 
-  /** Appends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method.
-   *
-   *  @param iter  the iterable object.
+  /** Appends the elements contained in a traversable collection to this buffer.
+   *  @param elems  the collection containing the elements to append.
    */
-  def appendAll(iter: Traversable[A]) { this ++= iter }
+  def appendAll(elems: Traversable[A]) { this ++= elems }
 
-  /** Prepend given elements to this list.
-   *
-   *  @param elem  the element to prepend.
+  /** Appends the elements produced by an iterator to this buffer.
+   *  @param elems  the iterator producing the elements to append.
+   */
+  def appendAll(iter: Iterator[A]) { this ++= iter }
+
+  /** Prepends given elements to this buffer.
+   *  @param elems  the elements to prepend.
    */
   def prepend(elems: A*) { elems ++=: this }
 
-  /** Prepends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method. The identity of the
-   *  buffer is returned.
-   *
-   *  @param iter  the iterable object.
+  /** Prepends the elements contained in a traversable collection to this buffer.
+   *  @param elems  the collection containing the elements to prepend.
    */
   def prependAll(iter: Traversable[A]) { iter ++=: this }
 
-  /** Prepends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method. The identity of the
-   *  buffer is returned.
-   *
-   *  @param iter  the iterable object.
+  /** Prepends a number of elements produced by an iterator to this buffer.
+   *  @param iter  the iterator producing the elements to prepend.
    */
   def prependAll(iter: Iterator[A]) { iter ++=: this }
 
-  /** Inserts new elements at the index <code>n</code>. Opposed to method
-   *  <code>update</code>, this method will not replace an element with a
-   *  one. Instead, it will insert the new elements at index <code>n</code>.
+  /** Inserts new elements at a given index into this buffer.
    *
-   *  @param n      the index where a new element will be inserted.
-   *  @param elems  the new elements to insert.
+   *  @param n      the index where new elements are inserted.
+   *  @param elems  the traversable collection containing the elements to insert.
+   *  @throws   IndexOutofBoundsException if the index `n` is not in the valid range
+   *            `0 <= n <= length`.
    */
   def insert(n: Int, elems: A*) { insertAll(n, elems) }
 
-  /** Removes the first <code>n</code> elements.
+  /** Removes the first ''n'' elements of this buffer.
    *
    *  @param n  the number of elements to remove from the beginning
    *            of this buffer.
    */
   def trimStart(n: Int) { remove(0, n) }
 
-  /** Removes the last <code>n</code> elements.
+  /** Removes the last ''n'' elements of this buffer.
    *
    *  @param n  the number of elements to remove from the end
    *            of this buffer.
@@ -220,17 +224,24 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
     case _                      => throw new UnsupportedOperationException("message " + cmd + " not understood")
   }
 
-  /** Defines the prefix of the string representation.
+  /** Defines the prefix of this object's `toString` representation.
+   *  @return  a string representation which starts the result of `toString` applied to this set.
+   *           Unless overridden this is simply `"Buffer"`.
    */
   override def stringPrefix: String = "Buffer"
 
+  /** Provide a read-only view of this byffer as a sequence
+   *  @return  A sequence which refers to this buffer for all its operations.
+   */
+  def readOnly: scala.collection.Seq[A] = toSeq
+
   /** Adds a number of elements in an array
    *
    *  @param src    the array
    *  @param start  the first element to append
    *  @param len    the number of elements to append
    */
-  @deprecated("replace by: <code>buf ++= src.view(start, end)</code>")
+  @deprecated("replace by: `buf ++= src.view(start, end)`")
   def ++=(src: Array[A], start: Int, len: Int) {
     var i = start
     val end = i + len
@@ -240,6 +251,9 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
     }
   }
 
+  @deprecated("use ++=: instead")
+  final def ++:(iter: Traversable[A]): This = ++=:(iter)
+
   /** Adds a single element to this collection and returns
    *  the collection itself.
    *
@@ -322,6 +336,9 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
     repr
   }
 
+  @deprecated("use `+=:' instead")
+  final def +:(elem: A): This = +=:(elem)
+
   /** Removes a number of elements provided by an iterator and returns
    *  the collection itself.
    *
@@ -333,8 +350,6 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
     for (elem <- iter) -=(elem)
     repr
   }
-
-  def readOnly: scala.collection.Seq[A] = toSeq
 }
 
 
diff --git a/src/library/scala/collection/mutable/Builder.scala b/src/library/scala/collection/mutable/Builder.scala
index 2af931d789..c7932ae344 100644
--- a/src/library/scala/collection/mutable/Builder.scala
+++ b/src/library/scala/collection/mutable/Builder.scala
@@ -18,32 +18,46 @@ import generic._
  *  elements to the builder with += and then converting to the required
  *  collection type with `result`.
  *
+ *  @tparam  Elem  the type of elements that get added to the builder.
+ *  @tparam  To    the type of collection that it produced.
+ *
  *  @since 2.8
  */
 trait Builder[-Elem, +To] extends Growable[Elem] {
 
   /** Adds a single element to the builder.
-   *  @param elem The element to be added
+   *  @param elem the element to be added.
+   *  @return the builder itself.
    */
   def +=(elem: Elem): this.type
 
-  /** Clear the contents of this builder
+  /** Clears the contents of this builder.
+   *  After execution of this method the builder will contain no elements.
    */
   def clear()
 
-  /** Returns collection resulting from this builder. The buffer's contents
-   *  are undefined afterwards.
+  /** Produces a collection from the added elements.
+   *  The builder's contents are undefined after this operation.
+   *  @return a collection containing the elements added to this builder.
    */
   def result(): To
 
-  /** Give a hint how many elements are expected to be added
-   *  when the next `result` is called.
+  /** Gives a hint how many elements are expected to be added
+   *  when the next `result` is called. Some builder classes
+   *  will optimize their representation based on the hint. However,
+   *  builder implementations are still required to work correctly even if the hint is
+   *  wrong, i.e. a different number of elements is added.
+   *
+   *  @size  the hint how many elements will be added.
    */
   def sizeHint(size: Int) {}
 
-  /** Create a new builder which is the same as the current builder except
-   *  that a given function is applied to the current builder's result.
-   *  @param  f   the function to apply to the builder's result
+  /** Creates a new builder by applying a transformation function to
+   *  the results of this builder.
+   *  @param  f     the transformation function.
+   *  @tparam NewTo the type of collection returned by `f`.
+   *  @return a new builder which is the same as the current builder except
+   *          that a transformation function is applied to this builder's result.
    */
   def mapResult[NewTo](f: To => NewTo): Builder[Elem, NewTo] =
     new Builder[Elem, NewTo] with Proxy {
diff --git a/src/library/scala/collection/mutable/IndexedSeqLike.scala b/src/library/scala/collection/mutable/IndexedSeqLike.scala
index ad94cc988e..a0f9205da2 100644
--- a/src/library/scala/collection/mutable/IndexedSeqLike.scala
+++ b/src/library/scala/collection/mutable/IndexedSeqLike.scala
@@ -23,6 +23,12 @@ trait IndexedSeqLike[A, +Repr] extends scala.collection.IndexedSeqLike[A, Repr]
   override protected[this] def thisCollection: IndexedSeq[A] = this.asInstanceOf[IndexedSeq[A]]
   override protected[this] def toCollection(repr: Repr): IndexedSeq[A] = repr.asInstanceOf[IndexedSeq[A]]
 
+  /** Replaces element at given index with a new value.
+   *
+   *  @param n       the index of the element to replace.
+   *  @param lem     the new value.
+   *  @throws   IndexOutofBoundsException if the index is not valid.
+   */
   def update(idx: Int, elem: A)
 
   /** Creates a view of this iterable @see Iterable.View
diff --git a/src/library/scala/collection/mutable/Map.scala b/src/library/scala/collection/mutable/Map.scala
index 020f7411c4..73688e3bee 100644
--- a/src/library/scala/collection/mutable/Map.scala
+++ b/src/library/scala/collection/mutable/Map.scala
@@ -14,8 +14,11 @@ package mutable
 
 import generic._
 
-/**
- * @since 1
+/** This trait represents mutable maps.
+ *  All implementations od mutable maps inherit from it.
+ *
+ *  @tparam A    the type of the keys of the map.
+ *  @tparam B    the type of associated values.
  */
 trait Map[A, B]
   extends Iterable[(A, B)]
@@ -36,8 +39,9 @@ trait Map[A, B]
   }
   */
 }
-/* Factory object for `Map` class
- * Currently this returns a HashMap.
+
+/* The standard factory for mutable maps.
+ * Currently this uses `HashMap` as the implementation class.
  */
 object Map extends MutableMapFactory[Map] {
   implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), Map[A, B]] = new MapCanBuildFrom[A, B]
diff --git a/src/library/scala/collection/mutable/MapLike.scala b/src/library/scala/collection/mutable/MapLike.scala
index a1e8e9b6d6..a1bb25910a 100644
--- a/src/library/scala/collection/mutable/MapLike.scala
+++ b/src/library/scala/collection/mutable/MapLike.scala
@@ -14,35 +14,41 @@ package mutable
 
 import generic._
 
-/** <p>
- *    A generic template for mutable maps from keys of type <code>A</code> to
- *    values of type <code>B</code>.
- *  </p>
- *  <p>
+/** A template trait for mutable maps of type `mutable.Map[A, B]` which
+ *  associate keys of type `A` with values of type `B`.
+ *
+ *  @tparam A    the type of the keys.
+ *  @tparam B    the type of associated values.
+ *  @tparam This the type of the `Map` itself.
+ *
+ * $mapnote
+ *
+ *  @author  Martin Odersky
+ *  @version 2.8
+ *  @since 2.8
+ *  @define mapnote
  *    To implement a concrete mutable map, you need to provide implementations
  *    of the following methods:
- *  </p><pre>
- *    <b>def</b> get(key: A): Option[B]
- *    <b>def</b> iterator: Iterator[(A, B)]
- *    <b>def</b> += (kv: (A, B)): <b>this.type</b>
- *    <b>def</b> -= (key: A): <b>this.type</b></pre>
- *  <p>
- *    If you wish that methods <code>like</code>, <code>take</code>,
- *    <code>drop</code>, <code>filter</code> return the same kind of map, you
+ *  {{{
+ *    def get(key: A): Option[B]
+ *    def iterator: Iterator[(A, B)]
+ *    def += (kv: (A, B)): this.type
+ *    def -= (key: A): this.type
+ *  }}}
+ *    If you wish that methods like `take`,
+ *    `drop`, `filter` return the same kind of map, you
  *    should also override:
- *  </p><pre>
- *   <b>def</b> empty: This</pre>
- *  <p>
- *    If you to avoid the unncessary construction of an <code>Option</code>
- *    object, you could also override <code>apply</code>, <code>update</code>,
- *    and <code>delete</code>.
- *  </p>
- *  <p>
- *    It is also good idea to override methods <code>foreach</code> and
- *    <code>size</code> for efficiency.
- *  </p>
- *
- *  @since 2.8
+ *  {{{
+ *    def> empty: This
+ *  }}}
+ *    If you wish to avoid the unncessary construction of an `Option`
+ *    object, you could also override `apply`, `update`,
+ *    and `delete`.
+
+ *    It is also good idea to override methods `foreach` and
+ *    `size` for efficiency.
+ *  @define coll mutable map
+ *  @define Coll mutable.Map
  */
 trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
   extends MapLikeBase[A, B, This]
@@ -54,22 +60,22 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
 
   import scala.collection.Traversable
 
-  /** <p>
-   *    A common implementation of <code>newBuilder</code> for all mutable maps
-   *    in terms of <code>empty</code>.
-   *  </p>
-   *  <p>
-   *    Overrides <code>MapLike</code> implementation for better efficiency.
-   *  </p>
+  /** A common implementation of `newBuilder` for all mutable maps
+   *    in terms of `empty`.
+   *
+   *    Overrides `MapLike` 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
-   *  mapping for <code>key</code>, it will be overridden.
+  /** Adds a new key/value pair to this map and optionally returns previously bound value.
+   *  If the map already contains a
+   *  mapping for the key, it will be overridden by the new value.
    *
-   * @param key    The key to update
-   * @param value  The new value
+   * @param key    the key to update
+   * @param value  the new value
+   * @return an option value containing the value associated with the key
+   *         before the `put` operation was executed, or `None` if `key`
+   *         was not defined in the map before.
    */
   def put(key: A, value: B): Option[B] = {
     val r = get(key)
@@ -77,29 +83,30 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
     r
   }
 
-  /** Adds a new mapping from <code>key</code>
-   *  to <code>value</code> to the map. If the map already contains a
-   *  mapping for <code>key</code>, it will be overridden.
+  /** Adds a new key/value pair to this map.
+   *  If the map already contains a
+   *  mapping for the key, it will be overridden by the new value.
    *
    *  @param key    The key to update
    *  @param value  The new value
-   *  @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, value: B) { this += ((key, value)) }
 
-  /** Add a new key/value mapping this map.
+  /** Adds a new key/value pair to this map.
+   *  If the map already contains a
+   *  mapping for the key, it will be overridden by the new value.
    *  @param    kv the key/value pair.
    *  @return   the map itself
    */
   def += (kv: (A, B)): this.type
 
-  /** Create a new map consisting of all elements of the current map
-   *  plus the given mapping from <code>key</code> to <code>value</code>.
+  /** Creates a new map consisting of all key/value pairs of the current map
+   *  plus a new pair of a guven key and value.
    *
-   *  @param key    The key to ad
+   *  @param key    The key to add
    *  @param value  The new value
-   *  @return       A fresh immutable map
+   *  @return       A fresh immutable map with the binding from `key` to
+   *                `value` added to this map.
    */
   override def updated[B1 >: B](key: A, value: B1): mutable.Map[A, B1] = this + ((key, value))
 
@@ -126,7 +133,7 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
     this += elem1 += elem2 ++= elems
 
   /** Adds a number of elements provided by a traversable object
-   *  via its <code>iterator</code> method and returns
+   *  via its `iterator` method and returns
    *  either the collection itself (if it is mutable), or a new collection
    *  with the added elements.
    *
@@ -138,7 +145,7 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
   def ++(iter: Traversable[(A, B)]): this.type = { for (elem <- iter) +=(elem); this }
 
   /** Adds a number of elements provided by an iterator
-   *  via its <code>iterator</code> method and returns
+   *  via its `iterator` method and returns
    *  the collection itself.
    *
    *  @param iter   the iterator
@@ -148,9 +155,11 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
               "to create a fresh map, you can use `clone() +=` to avoid a @deprecated warning.")
   def ++(iter: Iterator[(A, B)]): this.type = { for (elem <- iter) +=(elem); this }
 
-  /** If given key is defined in this map, remove it and return associated value as an Option.
-   *  If key is not present return None.
+  /** Removes a key from this map, returning the value associated previously
+   *  with that key as an option.
    *  @param    key the key to be removed
+   *  @return   an option value containing the value associated previously with `key`,
+   *            or `None` if `key` was not defined in the map before.
    */
   def remove(key: A): Option[B] = {
     val r = get(key)
@@ -158,9 +167,9 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
     r
   }
 
-  /** Delete a key from this map if it is present.
+  /** Removes a key from this map.
    *  @param    key the key to be removed
-   *  @note     same as `delete`.
+   *  @return   the map itself.
    */
   def -= (key: A): this.type
 
@@ -178,15 +187,19 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
    */
    @deprecated("Use `remove' instead") def removeKey(key: A): Option[B] = remove(key)
 
-
-  /** Removes all elements from the set. After this operation is completed,
-   *  the set will be empty.
+  /** Removes all bindings from the map. After this operation has completed,
+   *  the map will be empty.
    */
   def clear() { for ((k, v) <- this.iterator) -=(k) }
 
   /** If given key is already in this map, returns associated value
    *  Otherwise, computes value from given expression `op`, stores with key
    *  in map and returns that value.
+   *  @param  the key to test
+   *  @param  the computation yielding the value to associate with `key`, if
+   *          `key` is previosuly unbound.
+   *  @return the value associated with key (either previously or as a result
+   *          of executing the method).
    */
   def getOrElseUpdate(key: A, op: => B): B =
     get(key) match {
@@ -194,10 +207,12 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
       case None => val d = op; this(key) = d; d
     }
 
-  /** This function transforms all the values of mappings contained
-   *  in this map with function <code>f</code>.
+  /** Applies a transformation function to all values contained in this map.
+   *  The transformation function produces new values from existing keys
+   *  asssociated values.
    *
-   * @param f  The transformation to apply
+   * @param f  the transformation to apply
+   * @return   the map itself.
    */
   def transform(f: (A, B) => B): this.type = {
     this.iterator foreach {
@@ -206,8 +221,8 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
     this
   }
 
-  /** Retain only those mappings for which the predicate
-   *  <code>p</code> returns <code>true</code>.
+  /** Retains only those mappings for which the predicate
+   *  `p` returns `true`.
    *
    * @param p  The test predicate
    */
@@ -220,7 +235,9 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
   override def clone(): This =
     empty ++= repr
 
-  /** The result when this map is used as a builder */
+  /** The result when this map is used as a builder
+   *  @return  the map representation itself.
+   */
   def result: This = repr
 
   /** Removes two or more elements from this collection and returns
diff --git a/src/library/scala/collection/mutable/Seq.scala b/src/library/scala/collection/mutable/Seq.scala
index 9e54d3691f..a57d397275 100644
--- a/src/library/scala/collection/mutable/Seq.scala
+++ b/src/library/scala/collection/mutable/Seq.scala
@@ -26,6 +26,12 @@ trait Seq[A] extends Iterable[A]
                      with SeqLike[A, Seq[A]] {
   override def companion: GenericCompanion[Seq] = Seq
 
+  /** Replaces element at given index with a new value.
+   *
+   *  @param n       the index of the element to replace.
+   *  @param lem     the new value.
+   *  @throws   IndexOutofBoundsException if the index is not valid.
+   */
   def update(idx: Int, elem: A)
 }
 
diff --git a/src/library/scala/collection/mutable/SetLike.scala b/src/library/scala/collection/mutable/SetLike.scala
index dc4ccb2416..cb6eb293c1 100644
--- a/src/library/scala/collection/mutable/SetLike.scala
+++ b/src/library/scala/collection/mutable/SetLike.scala
@@ -15,27 +15,38 @@ package mutable
 import generic._
 import script._
 
-/** <p>
- *    A generic template for mutable sets of elements of type <code>A</code>.
+/** A template trait for mutable sets of type `mutable.Set[A]`.
+ *  @tparam A    the type of the elements of the set
+ *  @tparam This the type of the set itself.
+ *
+ *  $setnote
+ *
+ *  @author  Martin Odersky
+ *  @version 2.8
+ *  @since 2.8
+ *
+ *  @define setnote @note
+ *    This trait provides most of the operations of a `mutable.Set` independently of its representation.
+ *    It is typically inherited by concrete implementations of sets.
+ *
  *    To implement a concrete mutable set, you need to provide implementations
  *    of the following methods:
- *  </p><pre>
- *    <b>def</b> contains(elem: A): Boolean
- *    <b>def</b> iterator: Iterator[A]
- *    <b>def</b> += (elem: A): <b>this.type</b>
- *    <b>def</b> -= (elem: A): <b>this.type</b></pre>
- *  <p>
- *    If you wish that methods <code>like</code>, <code>take</code>,
- *    <code>drop</code>, <code>filter</code> return the same kind of map,
+ *    {{{
+ *       def contains(elem: A): Boolean
+ *       def iterator: Iterator[A]
+ *       def += (elem: A): this.type
+ *       def -= (elem: A): this.type</pre>
+ *    }}}
+ *    If you wish that methods like `take`,
+ *    `drop`, `filter` return the same kind of set,
  *    you should also override:
- *  </p><pre>
- *    <b>def</b> empty: This</pre>
- *  <p>
- *    It is also good idea to override methods <code>foreach</code> and
- *    <code>size</code> for efficiency.
- *  </p>
- *
- *  @since 2.8
+ *    {{{
+ *       def empty: This</pre>
+ *    }}}
+ *    It is also good idea to override methods `foreach` and
+ *    `size` for efficiency.
+ *  @define coll mutable set
+ *  @define Coll mutable.Set
  */
 trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
   extends scala.collection.SetLike[A, This]
@@ -46,16 +57,16 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
      with Cloneable[mutable.Set[A]]
 { self =>
 
-  /** A common implementation of <code>newBuilder</code> for all mutable sets
-   *  in terms of <code>empty</code>. Overrides <code>SetLike</code>
-   *  implementation for better efficiency.
+  /** A common implementation of `newBuilder` for all mutable sets
+   *  in terms of `empty`. Overrides the implementation in `collection.SetLike`
+   *  for better efficiency.
    */
   override protected[this] def newBuilder: Builder[A, This] = empty
 
-  /** Adds a new element to the set.
+  /** Adds an element to this $coll.
    *
    *  @param elem the element to be added
-   *  @return true if the element was not yet present in the set.
+   *  @return `true` if the element was not yet present in the set, `false` otherwise.
    */
   def add(elem: A): Boolean = {
     val r = contains(elem)
@@ -63,10 +74,10 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
     r
   }
 
-  /** Removes a single element from a set.
+  /** Removes an element from this set.
    *
    *  @param elem  The element to be removed.
-   *  @return  true if the element was already present in the set.
+   *  @return  `true` if the element was previously present in the set, `false` otherwise.
    */
   def remove(elem: A): Boolean = {
     val r = contains(elem)
@@ -74,29 +85,32 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
     r
   }
 
-  /** This method allows one to add or remove an element <code>elem</code>
-   *  from this set depending on the value of parameter <code>included</code>.
+  /** Updates the presence of a single element in this set.
+   *
+   * This method allows one to add or remove an element `elem`
+   *  from this set depending on the value of parameter `included`.
    *  Typically, one would use the following syntax:
-   *  <pre>set(elem) = true</pre>
+   *  {{{
+   *     set(elem) = true  // adds element
+   *     set(elem) = false // removes element
+   *  }}}
    *
+   *  @param elem     the element to be added or removed
+   *  @param included a flag indicating whether element should be included or excluded.
    */
   def update(elem: A, included: Boolean) {
     if (included) this += elem else this -= elem
   }
 
-  /** Adds a new element to the set.
-   *
-   *  @param elem the element to be added
-   */
-  def +=(elem: A): this.type
+  // abstract methods from Growable/Shrinkable
 
-  /** Removes a single element from a set.
-   *  @param elem  The element to be removed.
-   */
+  def +=(elem: A): this.type
   def -=(elem: A): this.type
 
-  /** Removes all elements from the set for which the predicate <code>p</code>
-   *  yields the value <code>false</code>.
+  /** Removes all elements from the set for which do not satisfy a predicate.
+   *  @param  p  the predicate used to test elements. Only elements for
+   *             while `p` returns `true` are retained in the set; all others
+   *             are removed.
    */
   def retain(p: A => Boolean): Unit = for (elem <- this.toList) if (!p(elem)) this -= elem
 
@@ -107,6 +121,9 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
 
   override def clone(): mutable.Set[A] = empty ++= repr
 
+  /** The result when this set is used as a builder
+   *  @return  the set representation itself.
+   */
   def result: This = repr
 
   /** Adds a single element to this collection and returns
@@ -144,7 +161,6 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
     repr
   }
 
-
   /** Adds a number of elements provided by an iterator and returns
    *  the collection itself.
    *
@@ -207,7 +223,7 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
   /** Send a message to this scriptable object.
    *
    *  @param cmd  the message to send.
-   *  @throws <code>Predef.UnsupportedOperationException</code>
+   *  @throws `Predef.UnsupportedOperationException`
    *  if the message was not understood.
    */
    def <<(cmd: Message[A]): Unit = cmd match {