more documentation

32 files changed, 191 insertions, 180 deletions

diff --git a/src/library/scala/collection/IndexedSeq.scala b/src/library/scala/collection/IndexedSeq.scala
index 72878a8ad6..78165cb242 100644
--- a/src/library/scala/collection/IndexedSeq.scala
+++ b/src/library/scala/collection/IndexedSeq.scala
@@ -24,6 +24,7 @@ trait IndexedSeq[+A] extends Seq[A]
 }
 
 /** $factoryInfo
+ *  The current default implementation of a $Coll is a `Vector`.
  *  @define coll indexed sequence
  *  @define Coll IndexedSeq
  */
diff --git a/src/library/scala/collection/Iterable.scala b/src/library/scala/collection/Iterable.scala
index 65d4dfcbe2..2baacec9f9 100644
--- a/src/library/scala/collection/Iterable.scala
+++ b/src/library/scala/collection/Iterable.scala
@@ -36,6 +36,7 @@ trait Iterable[+A] extends Traversable[A]
 }
 
 /** $factoryInfo
+ *  The current default implementation of a $Coll is a `Vector`.
  *  @define coll iterable collection
  *  @define Coll Iterable
  */
diff --git a/src/library/scala/collection/IterableView.scala b/src/library/scala/collection/IterableView.scala
index 436c000909..a6078bcdc8 100644
--- a/src/library/scala/collection/IterableView.scala
+++ b/src/library/scala/collection/IterableView.scala
@@ -14,14 +14,14 @@ package scala.collection
 import generic._
 import TraversableView.NoBuilder
 
-/** A base class for views of Iterables.
- *
- *  @author Martin Odersky
- *  @version 2.8
- *  @since   2.8
+/** A base trait for non-strict views of `Iterable`s.
+ *  $iterableViewInfo
  */
 trait IterableView[+A, +Coll] extends IterableViewLike[A, Coll, IterableView[A, Coll]]
 
+/** An object containing the necessary implicit definitions to make
+ *  `IterableView`s work. Its definitions are generally not accessed directly by clients.
+ */
 object IterableView {
   type Coll = TraversableView[_, C] forSome {type C <: Traversable[_]}
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, IterableView[A, Iterable[_]]] =
diff --git a/src/library/scala/collection/IterableViewLike.scala b/src/library/scala/collection/IterableViewLike.scala
index b8f0b65faf..49fcee842c 100644
--- a/src/library/scala/collection/IterableViewLike.scala
+++ b/src/library/scala/collection/IterableViewLike.scala
@@ -16,11 +16,11 @@ import collection.immutable.Stream
 import TraversableView.NoBuilder
 
 /** A template trait for non-strict views of iterable collections.
- *  $iterableviewInfo
+ *  $iterableViewInfo
  *
- *  @define iterableviewInfo
- *  $viewinfo
- *  All views for iterable collections are defined by creating a new `iterator` method.
+ *  @define iterableViewInfo
+ *  $viewInfo
+ *  All views for iterable collections are defined by re-interpreting the `iterator` method.
  *
  *  @author Martin Odersky
  *  @version 2.8
diff --git a/src/library/scala/collection/LinearSeq.scala b/src/library/scala/collection/LinearSeq.scala
index ef7d4c9390..ba0eb6a22d 100644
--- a/src/library/scala/collection/LinearSeq.scala
+++ b/src/library/scala/collection/LinearSeq.scala
@@ -24,6 +24,7 @@ trait LinearSeq[+A] extends Seq[A]
 }
 
 /** $factoryInfo
+ *  The current default implementation of a $Coll is a `Vector`.
  *  @define coll linear sequence
  *  @define Coll LinearSeq
  */
diff --git a/src/library/scala/collection/MapLike.scala b/src/library/scala/collection/MapLike.scala
index efbf9227d8..9bca2f09a0 100644
--- a/src/library/scala/collection/MapLike.scala
+++ b/src/library/scala/collection/MapLike.scala
@@ -15,21 +15,14 @@ import mutable.{Builder, StringBuilder, MapBuilder}
 import annotation.migration
 import PartialFunction._
 
-/** A template trait for maps of type `Map[A, B]` which associate keys of type `A`
- *  with values of type `B`.
+/** A template trait for maps, which associate keys with values.
  *
- *  $mapnote
+ *  $mapNote
+ *  $mapTags
+ *  @since 2.8
  *
- *  @tparam A    the type of the keys.
- *  @tparam B    the type of associated values.
- *  @tparam This the type of the map itself.
- *
- *
- *  @author  Martin Odersky
- *  @version 2.8
- *  @since   2.8
- *  @define $mapnote
- *    '''Note:'''
+ *  @define mapNote
+ *    '''Implementation note:'''
  *    This trait provides most of the operations of a `Map` independently of its representation.
  *    It is typically inherited by concrete implementations of maps.
  *
@@ -48,6 +41,15 @@ import PartialFunction._
  *    }}}
  *    It is also good idea to override methods `foreach` and
  *    `size` for efficiency.
+ *
+ *  @define mapTags
+ *  @tparam A    the type of the keys.
+ *  @tparam B    the type of associated values.
+ *  @tparam This the type of the map itself.
+ *
+ *  @author  Martin Odersky
+ *  @version 2.8
+ *
  *  @define coll map
  *  @define Coll Map
  *  @define willNotTerminateInf
diff --git a/src/library/scala/collection/Seq.scala b/src/library/scala/collection/Seq.scala
index baf2c0031e..f6b89b67b8 100644
--- a/src/library/scala/collection/Seq.scala
+++ b/src/library/scala/collection/Seq.scala
@@ -25,6 +25,7 @@ trait Seq[+A] extends PartialFunction[Int, A]
 }
 
 /** $factoryInfo
+ *  The current default implementation of a $Coll is a `Vector`.
  *  @define coll sequence
  *  @define Coll Seq
  */
diff --git a/src/library/scala/collection/SeqView.scala b/src/library/scala/collection/SeqView.scala
index 9a0025bd81..68819e899d 100644
--- a/src/library/scala/collection/SeqView.scala
+++ b/src/library/scala/collection/SeqView.scala
@@ -14,16 +14,13 @@ package scala.collection
 import generic._
 import TraversableView.NoBuilder
 
-/** A non-strict projection of an iterable.
- * @author Sean McDirmid
- * @author Martin Odersky
- * @version 2.8
+/** A base trait for non-strict views of sequences.
+ *  $seqViewInfo
  */
 trait SeqView[+A, +Coll] extends SeqViewLike[A, Coll, SeqView[A, Coll]]
 
-/** $factoryInfo
- *  @define coll sequence view
- *  @define Coll SeqView
+/** An object containing the necessary implicit definitions to make
+ *  `SeqView`s work. Its definitions are generally not accessed directly by clients.
  */
 object SeqView {
   type Coll = TraversableView[_, C] forSome {type C <: Traversable[_]}
diff --git a/src/library/scala/collection/SeqViewLike.scala b/src/library/scala/collection/SeqViewLike.scala
index 7014833a46..6f1f29f536 100644
--- a/src/library/scala/collection/SeqViewLike.scala
+++ b/src/library/scala/collection/SeqViewLike.scala
@@ -15,10 +15,19 @@ import generic._
 import Seq.fill
 import TraversableView.NoBuilder
 
-/** A template trait for a non-strict view of a sequence.
- * @author Sean McDirmid
- * @author Martin Odersky
- * @version 2.8
+/** A template trait for non-strict views of sequences.
+ *  $seqViewInfo
+ *
+ *  @define seqViewInfo
+ *  $viewInfo
+ *  All views for sequences are defined by re-interpreting the `length` and `apply` methods.
+ *
+ *  @author Martin Odersky
+ *  @version 2.8
+ *  @since   2.8
+ *  @tparam A    the element type of the view
+ *  @tparam Coll the type of the underlying collection containing the elements.
+ *  @tparam This the type of the view itself
  */
 trait SeqViewLike[+A,
                   +Coll,
diff --git a/src/library/scala/collection/Set.scala b/src/library/scala/collection/Set.scala
index 3a6313a187..034d9f1705 100644
--- a/src/library/scala/collection/Set.scala
+++ b/src/library/scala/collection/Set.scala
@@ -12,14 +12,16 @@ package scala.collection
 
 import generic._
 
-/** <p>
- *    A set is a collection that includes at most one of any object.
- *  </p>
+/** A base trait for all sets, mutable as well as immutable.
  *
- *  @author  Matthias Zenger
- *  @author  Martin Odersky
- *  @version 2.8
- *  @since   1
+ * $setNote
+ * $setNote2
+ * $setTags
+ * @since 1.0
+ * @author Matthias Zenger
+ * @define setNote2
+ * '''Implementation note:''' If your additions and mutations return the same kind of set as the set
+ *       you are defining, you should inherit from `SetLike` as well.
  */
 trait Set[A] extends (A => Boolean)
                 with Iterable[A]
@@ -28,11 +30,11 @@ trait Set[A] extends (A => Boolean)
   override def companion: GenericCompanion[Set] = Set
 }
 
-/** Factory object for <code>Set</code> class.
- *
- *  @author  Martin Odersky
- *  @version 2.8
- *  @since   2.8
+/** $factoryInfo
+ *  The current default implementation of a $Coll is one of `EmptySet`, `Set1`, `Set2`, `Set3`, `Set4` in
+ *  class `immutable.Set` for sets of sizes up to 4, and a `immutable.HashSet` for sets of larger sizes.
+ *  @define coll set
+ *  @define Coll Set
  */
 object Set extends SetFactory[Set] {
   override def empty[A]: Set[A] = immutable.Set.empty[A]
diff --git a/src/library/scala/collection/SetLike.scala b/src/library/scala/collection/SetLike.scala
index 15e3ef43ca..5a16b975df 100644
--- a/src/library/scala/collection/SetLike.scala
+++ b/src/library/scala/collection/SetLike.scala
@@ -14,20 +14,21 @@ import generic._
 import mutable.{Builder, AddingBuilder}
 import PartialFunction._
 
-/** A template trait for sets of type `Set[A]`.
+/** A template trait for sets.
  *
- * This trait provides most of the operations of a `Set` independently of its representation.
- * It is typically inherited by concrete implementations of sets.
+ *  $setNote
+ *  $setTags
+ *  @since 2.8
  *
- * $setnote
+ *  @define setNote
  *
- *  @tparam A    the type of the elements of the set
- *  @tparam This the type of the set itself.
+ *  A set is a collection that contains no duplicate elements.
  *
- *  @author  Martin Odersky
- *  @version 2.8
- *  @define setnote
- *    To implement a concrete set, you need  to provide implementations of the
+ *    '''Implementation note:'''
+ *    This trait provides most of the operations of a `Set` independently of its representation.
+ *    It is typically inherited by concrete implementations of sets.
+ *
+ *    To implement a concrete set, you need to provide implementations of the
  *    following methods:
  *    {{{
  *       def contains(key: A): Boolean
@@ -42,10 +43,18 @@ import PartialFunction._
  *    }}}
  *    It is also good idea to override methods `foreach` and
  *    `size` for efficiency.
- *   @define coll set
- *   @define Coll Set
- *   @define willNotTerminateInf
- *   @define mayNotTerminateInf
+ *
+ * @define setTags
+ *  @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 coll set
+ *  @define Coll Set
+ *  @define willNotTerminateInf
+ *  @define mayNotTerminateInf
  */
 trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
 extends IterableLike[A, This]
diff --git a/src/library/scala/collection/Traversable.scala b/src/library/scala/collection/Traversable.scala
index 4a1cd01af1..b3383ba802 100644
--- a/src/library/scala/collection/Traversable.scala
+++ b/src/library/scala/collection/Traversable.scala
@@ -83,6 +83,7 @@ trait Traversable[+A] extends TraversableLike[A, Traversable[A]]
 }
 
 /** $factoryInfo
+ *  The current default implementation of a $Coll is a `Vector`.
  */
 object Traversable extends TraversableFactory[Traversable] { self =>
 
diff --git a/src/library/scala/collection/TraversableView.scala b/src/library/scala/collection/TraversableView.scala
index ccc33a495d..6d7fa70968 100644
--- a/src/library/scala/collection/TraversableView.scala
+++ b/src/library/scala/collection/TraversableView.scala
@@ -15,10 +15,14 @@ import generic._
 import mutable.Builder
 import TraversableView.NoBuilder
 
-/** $traversableviewinfo
+/** A base trait for non-strict views of traversable collections.
+ *  $traversableViewInfo
  */
 trait TraversableView[+A, +Coll] extends TraversableViewLike[A, Coll, TraversableView[A, Coll]]
 
+/** An object containing the necessary implicit definitions to make
+ *  `TraversableView`s work. Its definitions are generally not accessed directly by clients.
+ */
 object TraversableView {
   class NoBuilder[A] extends Builder[A, Nothing] {
     def +=(elem: A): this.type = this
diff --git a/src/library/scala/collection/generic/GenericCompanion.scala b/src/library/scala/collection/generic/GenericCompanion.scala
index 1004f4f15a..2a87f8d913 100644
--- a/src/library/scala/collection/generic/GenericCompanion.scala
+++ b/src/library/scala/collection/generic/GenericCompanion.scala
@@ -14,7 +14,7 @@ package generic
 
 import mutable.Builder
 
-/** A template class for companion objects of ''regular'' collection classes
+/** 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.
@@ -28,13 +28,18 @@ abstract class GenericCompanion[+CC[X] <: Traversable[X]] {
   /** The underlying collection type with unknown element type */
   type Coll = CC[_]
 
-  /** The default builder for `$Coll` objects. */
+  /** The default builder for `$Coll` objects.
+   *  @tparam A      the type of the ${coll}'s elements
+   */
   def newBuilder[A]: Builder[A, CC[A]]
 
-  /** The empty collection of type `$Coll[A]` */
+  /** An empty collection of type `$Coll[A]`
+   *  @tparam A      the type of the ${coll}'s elements
+   */
   def empty[A]: CC[A] = newBuilder[A].result
 
   /** Creates a $coll with the specified elements.
+   *  @tparam A      the type of the ${coll}'s elements
    *  @param elems  the elements of the created $coll
    *  @return a new $coll with elements `elems`
    */
diff --git a/src/library/scala/collection/generic/ImmutableMapFactory.scala b/src/library/scala/collection/generic/ImmutableMapFactory.scala
index 6096a3184d..512014ba09 100644
--- a/src/library/scala/collection/generic/ImmutableMapFactory.scala
+++ b/src/library/scala/collection/generic/ImmutableMapFactory.scala
@@ -11,17 +11,9 @@
 package scala.collection
 package generic
 
-/** A template for companion objects of `Map` and
- *  subclasses thereof.
- *
- *  @since 2.8
- *  @define Coll Map
- *  @define coll map
- *  @define factoryInfo
- *    This object provides a set of operations needed to create maps of type `$Coll`.
+/** A template for companion objects of `immutable.Map` and subclasses thereof.
  *    @author Martin Odersky
  *    @version 2.8
- *  @define mapCanBuildFromInfo
- *    The standard `CanBuildFrom` instance for maps.
+ *    @since 2.8
  */
 abstract class ImmutableMapFactory[CC[A, +B] <: immutable.Map[A, B] with immutable.MapLike[A, B, CC[A, B]]] extends MapFactory[CC]
diff --git a/src/library/scala/collection/generic/MapFactory.scala b/src/library/scala/collection/generic/MapFactory.scala
index fc04f28f26..163c289e23 100644
--- a/src/library/scala/collection/generic/MapFactory.scala
+++ b/src/library/scala/collection/generic/MapFactory.scala
@@ -22,6 +22,7 @@ import mutable.{Builder, MapBuilder}
  *    This object provides a set of operations needed to create `$Coll` values.
  *    @author Martin Odersky
  *    @version 2.8
+ *    @since 2.8
  *  @define canBuildFromInfo
  *    The standard `CanBuildFrom` instance for `$Coll` objects.
  *    @see CanBuildFrom
@@ -33,14 +34,28 @@ import mutable.{Builder, MapBuilder}
  */
 abstract class MapFactory[CC[A, B] <: Map[A, B] with MapLike[A, B, CC[A, B]]] {
 
+  /** The type constructor of the collection that can be built by this factory */
   type Coll = CC[_, _]
 
+  /** An empty $Coll */
   def empty[A, B]: CC[A, B]
 
+  /** A collection of type $Coll that contains given key/value bindings.
+   *  @param elems   the key/value pairs that make up the $coll
+   *  @tparam A      the type of the keys
+   *  @tparam B      the type of the associated values
+   *  @return        a new $coll consisting key/value pairs given by `elems`.
+   */
   def apply[A, B](elems: (A, B)*): CC[A, B] = (newBuilder[A, B] ++= elems).result
 
+  /** The default builder for $Coll objects.
+   *  @tparam A      the type of the keys
+   *  @tparam B      the type of the associated values
+   */
   def newBuilder[A, B]: Builder[(A, B), CC[A, B]] = new MapBuilder[A, B, CC[A, B]](empty[A, B])
 
+  /** The standard `CanBuildFrom` class for maps.
+   */
   class MapCanBuildFrom[A, B] extends CanBuildFrom[Coll, (A, B), CC[A, B]] {
     def apply(from: Coll) = newBuilder[A, B]
     def apply() = newBuilder
diff --git a/src/library/scala/collection/generic/MutableMapFactory.scala b/src/library/scala/collection/generic/MutableMapFactory.scala
index 0f1608ee71..2fdb827d05 100644
--- a/src/library/scala/collection/generic/MutableMapFactory.scala
+++ b/src/library/scala/collection/generic/MutableMapFactory.scala
@@ -14,9 +14,10 @@ package generic
 
 import mutable.MapBuilder
 
-/** A template for companion objects of `mutable.Map` and subclasses thereof.
- *
- *  @since 2.8
+/** A template for companion objects of `immutable.Map` and subclasses thereof.
+ *    @author Martin Odersky
+ *    @version 2.8
+ *    @since 2.8
  */
 abstract class MutableMapFactory[CC[A, B] <: mutable.Map[A, B] with mutable.MapLike[A, B, CC[A, B]]]
   extends MapFactory[CC]
diff --git a/src/library/scala/collection/generic/SetFactory.scala b/src/library/scala/collection/generic/SetFactory.scala
index 87de1cec32..1c4ec3e7e3 100644
--- a/src/library/scala/collection/generic/SetFactory.scala
+++ b/src/library/scala/collection/generic/SetFactory.scala
@@ -14,8 +14,7 @@ package generic
 
 import mutable.{Builder, AddingBuilder}
 
-/** A template for companion objects of `Set` and subclasses
- *  thereof.
+/** A template for companion objects of `Set` and subclasses thereof.
  *
  *  @define coll set
  *  @define Coll Set
@@ -23,6 +22,7 @@ import mutable.{Builder, AddingBuilder}
  *    This object provides a set of operations needed to create `$Coll` values.
  *    @author Martin Odersky
  *    @version 2.8
+ *    @since 2.8
  *  @define canBuildFromInfo
  *    The standard `CanBuildFrom` instance for `$Coll` objects.
  *    @see CanBuildFrom
@@ -36,6 +36,8 @@ abstract class SetFactory[CC[X] <: Set[X] with SetLike[X, CC[X]]]
 
   def newBuilder[A]: Builder[A, CC[A]] = new AddingBuilder[A, CC[A]](empty[A])
 
+  /** $setCanBuildFromInfo
+   */
   def setCanBuildFrom[A] = new CanBuildFrom[CC[_], A, CC[A]] {
     def apply(from: CC[_]) = newBuilder[A]
     def apply() = newBuilder[A]
diff --git a/src/library/scala/collection/immutable/IndexedSeq.scala b/src/library/scala/collection/immutable/IndexedSeq.scala
index 4064e9e3a9..d3223fd106 100644
--- a/src/library/scala/collection/immutable/IndexedSeq.scala
+++ b/src/library/scala/collection/immutable/IndexedSeq.scala
@@ -26,6 +26,7 @@ trait IndexedSeq[+A] extends Seq[A]
 }
 
 /** $factoryInfo
+ *  The current default implementation of a $Coll is a `Vector`.
  *  @define coll indexed sequence
  *  @define Coll IndexedSeq
  */
diff --git a/src/library/scala/collection/immutable/LinearSeq.scala b/src/library/scala/collection/immutable/LinearSeq.scala
index 1ffe96310e..180844ce79 100644
--- a/src/library/scala/collection/immutable/LinearSeq.scala
+++ b/src/library/scala/collection/immutable/LinearSeq.scala
@@ -27,8 +27,9 @@ trait LinearSeq[+A] extends Seq[A]
 }
 
 /** $factoryInfo
- *  @define coll linear sequence
- *  @define Coll LinearSeq
+ *  The current default implementation of a $Coll is a `List`.
+ *  @define coll immutable linear sequence
+ *  @define Coll immutable.LinearSeq
  */
 object LinearSeq extends SeqFactory[LinearSeq] {
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, LinearSeq[A]] = new GenericCanBuildFrom[A]
diff --git a/src/library/scala/collection/immutable/Traversable.scala b/src/library/scala/collection/immutable/Traversable.scala
index 61a7f3ebd1..8fdb5c7568 100644
--- a/src/library/scala/collection/immutable/Traversable.scala
+++ b/src/library/scala/collection/immutable/Traversable.scala
@@ -27,8 +27,9 @@ trait Traversable[+A] extends scala.collection.Traversable[A]
 }
 
 /** $factoryInfo
- *  @define Coll immutable.Travesable
- *  @define coll immutable traversable object
+ *  The current default implementation of a $Coll is a `Vector`.
+ *  @define coll immutable traversable collection
+ *  @define Coll immutable.Traversable
  */
 object Traversable extends TraversableFactory[Traversable] {
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Traversable[A]] = new GenericCanBuildFrom[A]
diff --git a/src/library/scala/collection/mutable/ArrayBuffer.scala b/src/library/scala/collection/mutable/ArrayBuffer.scala
index bee531221f..ae656d4e09 100644
--- a/src/library/scala/collection/mutable/ArrayBuffer.scala
+++ b/src/library/scala/collection/mutable/ArrayBuffer.scala
@@ -177,8 +177,8 @@ class ArrayBuffer[A](override protected val initialSize: Int)
 /** Factory object for the `ArrayBuffer` class.
  *
  *  $factoryInfo
- *  @define coll list
- *  @define Coll List
+ *  @define coll array buffer
+ *  @define Coll ArrayBuffer
  */
 object ArrayBuffer extends SeqFactory[ArrayBuffer] {
   /** $genericCanBuildFromInfo */
diff --git a/src/library/scala/collection/mutable/ArrayLike.scala b/src/library/scala/collection/mutable/ArrayLike.scala
index b3bd0fbe25..15cafa6ee7 100644
--- a/src/library/scala/collection/mutable/ArrayLike.scala
+++ b/src/library/scala/collection/mutable/ArrayLike.scala
@@ -13,15 +13,15 @@ package scala.collection
 package mutable
 import generic._
 
-/** A subtrait of `collection.IndexedSeq` which represents sequences
- *  that can be mutated.
- *
- *  @since 2.8
+/** A common supertrait of `ArrayOps` and `WrappedArray` that factors out most
+ *  operations on arrays and wrapped arrays.
  *
  *  @tparam A     type of the elements contained in the array like object.
  *  @tparam Repr  the type of the actual collection containing the elements.
  *
  *  @define Coll ArrayLike
+ *  @version 2.8
+ *  @since   2.8
  */
 trait ArrayLike[A, +Repr] extends IndexedSeqOptimized[A, Repr] { self =>
 
diff --git a/src/library/scala/collection/mutable/IndexedSeq.scala b/src/library/scala/collection/mutable/IndexedSeq.scala
index a0b90f63df..06a6230c6b 100644
--- a/src/library/scala/collection/mutable/IndexedSeq.scala
+++ b/src/library/scala/collection/mutable/IndexedSeq.scala
@@ -16,6 +16,7 @@ import generic._
 
 /** A subtrait of `collection.IndexedSeq` which represents sequences
  *  that can be mutated.
+ *
  *  $indexedSeqInfo
  */
 trait IndexedSeq[A] extends Seq[A]
@@ -26,8 +27,9 @@ trait IndexedSeq[A] extends Seq[A]
 }
 
 /** $factoryInfo
- *  @define coll indexed sequence
- *  @define Coll IndexedSeq
+ *  The current default implementation of a $Coll is an `ArrayBuffer`.
+ *  @define coll mutable indexed sequence
+ *  @define Coll mutable.IndexedSeq
  */
 object IndexedSeq extends SeqFactory[IndexedSeq] {
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, IndexedSeq[A]] = new GenericCanBuildFrom[A]
diff --git a/src/library/scala/collection/mutable/IndexedSeqView.scala b/src/library/scala/collection/mutable/IndexedSeqView.scala
index 9a0e7a4010..8d72ac2c49 100644
--- a/src/library/scala/collection/mutable/IndexedSeqView.scala
+++ b/src/library/scala/collection/mutable/IndexedSeqView.scala
@@ -16,14 +16,16 @@ import generic._
 
 import TraversableView.NoBuilder
 
-/** A non-strict view of a mutable IndexedSeq.
- *  This is a leaf class which mixes methods returning a plain IndexedSeq view
- *  and methods returning a mutable IndexedSeq view.
- *  There is no associated `Like' class.
- * @author Sean McDirmid
- * @author Martin Odersky
- * @version 2.8
- * @since   2.8
+/** A non-strict view of a mutable `IndexedSeq`.
+ *  $viewinfo
+ *  Some of the operations of this class will yield again a mutable indexed sequence,
+ *  others will just yield a plain indexed sequence of type `collection.IndexedSeq`.
+ *  Because this is a leaf class there is no associated `Like' class.
+ *  @author Martin Odersky
+ *  @version 2.8
+ *  @since   2.8
+ *  @tparam A    the element type of the view
+ *  @tparam Coll the type of the underlying collection containing the elements.
  */
 trait IndexedSeqView[A, +Coll] extends IndexedSeq[A]
                                   with IndexedSeqOptimized[A, IndexedSeqView[A, Coll]]
@@ -91,13 +93,13 @@ self =>
   override def reverse: IndexedSeqView[A, Coll] = newReversed.asInstanceOf[IndexedSeqView[A, Coll]]
 }
 
-/** $factoryInfo
- * @define coll indexed sequence view
- * @define Coll IndexedSeqView
- * Note that the canBuildFrom factories yield SeqViews, not IndexedSewqViews.
- * This is intentional, because not all operations yield again a mutable.IndexedSeqView.
- * For instance, map just gives a SeqView, which reflects the fact that
- * map cannot do its work and maintain a pointer into the original indexed sequence.
+/** An object containing the necessary implicit definitions to make
+ *  `SeqView`s work. Its definitions are generally not accessed directly by clients.
+ *
+ * Note that the `canBuildFrom` factories yield `SeqView`s, not `IndexedSewqView`s.
+ * This is intentional, because not all operations yield again a `mutable.IndexedSeqView`.
+ * For instance, `map` just gives a `SeqView`, which reflects the fact that
+ * `map` cannot do its work and maintain a pointer into the original indexed sequence.
  */
 object IndexedSeqView {
   type Coll = TraversableView[_, C] forSome {type C <: Traversable[_]}
diff --git a/src/library/scala/collection/mutable/Iterable.scala b/src/library/scala/collection/mutable/Iterable.scala
index 85c6df6fb0..71143f74e3 100644
--- a/src/library/scala/collection/mutable/Iterable.scala
+++ b/src/library/scala/collection/mutable/Iterable.scala
@@ -21,8 +21,9 @@ trait Iterable[A] extends Traversable[A]
 }
 
 /** $factoryInfo
- *  @define coll indexed sequence
- *  @define Coll IndexedSeq
+ *  The current default implementation of a $Coll is an `ArrayBuffer`.
+ *  @define coll mutable iterable collection
+ *  @define Coll mutable.Iterable
  */
 object Iterable extends TraversableFactory[Iterable] {
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Iterable[A]] = new GenericCanBuildFrom[A]
diff --git a/src/library/scala/collection/mutable/LinearSeq.scala b/src/library/scala/collection/mutable/LinearSeq.scala
index 185b8c97a3..7567504890 100644
--- a/src/library/scala/collection/mutable/LinearSeq.scala
+++ b/src/library/scala/collection/mutable/LinearSeq.scala
@@ -29,8 +29,9 @@ trait LinearSeq[A] extends Seq[A]
 }
 
 /** $factoryInfo
- *  @define coll linear sequence
- *  @define Coll LinearSeq
+ *  The current default implementation of a $Coll is a `MutableList`.
+ *  @define coll mutable linear sequence
+ *  @define Coll mutable.LinearSeq
  */
 object LinearSeq extends SeqFactory[LinearSeq] {
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, LinearSeq[A]] = new GenericCanBuildFrom[A]
diff --git a/src/library/scala/collection/mutable/Map.scala b/src/library/scala/collection/mutable/Map.scala
index d26f6a7e30..6c42bad0e9 100644
--- a/src/library/scala/collection/mutable/Map.scala
+++ b/src/library/scala/collection/mutable/Map.scala
@@ -14,13 +14,11 @@ package mutable
 
 import generic._
 
-/** This trait represents mutable maps.
- *  All implementations od mutable maps inherit from it.
- *
- *  $mapnote
- *
- *  @tparam A    the type of the keys of the map.
- *  @tparam B    the type of associated values.
+/** A base trait for maps that can be mutated.
+ *  $mapNote
+ *  $mapTags
+ *  @since 1.0
+ *  @author  Matthias Zenger
  */
 trait Map[A, B]
   extends Iterable[(A, B)]
@@ -29,7 +27,7 @@ trait Map[A, B]
 
   override def empty: Map[A, B] = Map.empty
 
-  /* Return a read-only projection of this map.  !!! or just use an (immutable) MapProxy?
+  /** Return a read-only projection of this map.  !!! or just use an (immutable) MapProxy?
   def readOnly : scala.collection.Map[A, B] = new scala.collection.Map[A, B] {
     override def size = self.size
     override def update(key: A, value: B) = self.update(key, value)
@@ -43,11 +41,14 @@ trait Map[A, B]
 }
 
 /** $factoryInfo
- *  @define Coll Map
- *  @define coll map
+ *  The current default implementation of a $Coll is a `HashMap`.
+ *  @define coll mutable map
+ *  @define Coll mutable.Map
  */
 object Map extends MutableMapFactory[Map] {
+  /** $canBuildFromInfo */
   implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), Map[A, B]] = new MapCanBuildFrom[A, B]
+
   def empty[A, B]: Map[A, B] = new HashMap[A, B]
 }
 
diff --git a/src/library/scala/collection/mutable/MapLike.scala b/src/library/scala/collection/mutable/MapLike.scala
index 19e67a6731..676a325c9b 100644
--- a/src/library/scala/collection/mutable/MapLike.scala
+++ b/src/library/scala/collection/mutable/MapLike.scala
@@ -15,41 +15,10 @@ package mutable
 import generic._
 import annotation.migration
 
-/** 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:
- *  {{{
- *    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:
- *  {{{
- *    def empty: This
- *  }}}
- *    If you wish to avoid the unnecessary 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
+/** A template trait for mutable maps.
+ *  $mapNote
+ *  $mapTags
+ *  @since   2.8
  */
 trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
   extends scala.collection.MapLike[A, B, This]
diff --git a/src/library/scala/collection/mutable/Seq.scala b/src/library/scala/collection/mutable/Seq.scala
index 832e949931..679cc24389 100644
--- a/src/library/scala/collection/mutable/Seq.scala
+++ b/src/library/scala/collection/mutable/Seq.scala
@@ -26,9 +26,9 @@ import generic._
  *  @define coll mutable sequence
  */
 trait Seq[A] extends Iterable[A]
-                with scala.collection.Seq[A]
-                with GenericTraversableTemplate[A, Seq]
-                with SeqLike[A, Seq[A]] {
+                     with scala.collection.Seq[A]
+                     with GenericTraversableTemplate[A, Seq]
+                     with SeqLike[A, Seq[A]] {
   override def companion: GenericCompanion[Seq] = Seq
 
   /** Replaces element at given index with a new value.
@@ -40,13 +40,12 @@ trait Seq[A] extends Iterable[A]
   def update(idx: Int, elem: A)
 }
 
-
 /** $factoryInfo
- *  @define coll sequence
- *  @define Coll Seq
+ *  The current default implementation of a $Coll is an `ArrayBuffer`.
+ *  @define coll mutable sequence
+ *  @define Coll mutable.Seq
  */
 object Seq extends SeqFactory[Seq] {
-  /** $genericCanBuildFromInfo */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Seq[A]] = new GenericCanBuildFrom[A]
   def newBuilder[A]: Builder[A, Seq[A]] = new ArrayBuffer
 }
diff --git a/src/library/scala/collection/mutable/Set.scala b/src/library/scala/collection/mutable/Set.scala
index a816816846..2e7f1cbc6b 100644
--- a/src/library/scala/collection/mutable/Set.scala
+++ b/src/library/scala/collection/mutable/Set.scala
@@ -14,22 +14,11 @@ package mutable
 
 import generic._
 
-/** A generic trait for mutable sets. Concrete set implementations
- *  have to provide functionality for the abstract methods in Set:
- *
- *  {{{
- *  def contains(elem: A): Boolean
- *  def iterator: Iterator[A]
- *  def += (elem: A): this.type
- *  def -= (elem: A): this.type
- *  }}}
- *
- *  $setnote
- *
- *  @tparam A    type of the elements contained in this set.
- *
+/** A base trait for sets that can be mutated.
+ *  $setNote
+ *  $setTags
+ *  @since 1.0
  *  @author Matthias Zenger
- *  @since   1
  */
 trait Set[A] extends Iterable[A]
                 with scala.collection.Set[A]
@@ -39,11 +28,11 @@ trait Set[A] extends Iterable[A]
 }
 
 /** $factoryInfo
- *  @define coll set
- *  @define Coll Set
+ *  The current default implementation of a $Coll is a `HashSet`.
+ *  @define coll mutable set
+ *  @define Coll mutable.Set
  */
 object Set extends SetFactory[Set] {
-  /** $setCanBuildFromInfo */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Set[A]] = setCanBuildFrom[A]
   override def empty[A]: Set[A] = HashSet.empty[A]
 }
diff --git a/src/library/scala/collection/mutable/Traversable.scala b/src/library/scala/collection/mutable/Traversable.scala
index 9a7153235a..871e3a825d 100644
--- a/src/library/scala/collection/mutable/Traversable.scala
+++ b/src/library/scala/collection/mutable/Traversable.scala
@@ -26,8 +26,9 @@ trait Traversable[A] extends scala.collection.Traversable[A]
 }
 
 /** $factoryInfo
+ *  The current default implementation of a $Coll is an `ArrayBuffer`.
+ *  @define coll mutable traversable collection
  *  @define Coll mutable.Traversable
- *  @define coll mutable traversable
  */
 object Traversable extends TraversableFactory[Traversable] {
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Traversable[A]] = new GenericCanBuildFrom[A]