Documentation for mutable collections. No review.

33 files changed, 233 insertions, 109 deletions

diff --git a/src/library/scala/collection/mutable/ListBuffer.scala b/src/library/scala/collection/mutable/ListBuffer.scala
index a2611a8c0f..7ebbf7b4da 100644
--- a/src/library/scala/collection/mutable/ListBuffer.scala
+++ b/src/library/scala/collection/mutable/ListBuffer.scala
@@ -246,7 +246,7 @@ final class ListBuffer[A]
 // Overrides of methods in Buffer
 
   /** Removes the element on a given index position. May take time linear in
-   *  the buffer size
+   *  the buffer size.
    *
    *  @param  n  the index which refers to the element to delete.
    *  @return n  the element that was formerly at position `n`.
diff --git a/src/library/scala/collection/mutable/Map.scala b/src/library/scala/collection/mutable/Map.scala
index 73688e3bee..d26f6a7e30 100644
--- a/src/library/scala/collection/mutable/Map.scala
+++ b/src/library/scala/collection/mutable/Map.scala
@@ -17,6 +17,8 @@ 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.
  */
@@ -27,7 +29,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)
@@ -40,8 +42,9 @@ trait Map[A, B]
   */
 }
 
-/* The standard factory for mutable maps.
- * Currently this uses `HashMap` as the implementation class.
+/** $factoryInfo
+ *  @define Coll Map
+ *  @define coll map
  */
 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/MapBuilder.scala b/src/library/scala/collection/mutable/MapBuilder.scala
index 9ce3524d9e..75fb48abd6 100644
--- a/src/library/scala/collection/mutable/MapBuilder.scala
+++ b/src/library/scala/collection/mutable/MapBuilder.scala
@@ -14,6 +14,10 @@ package mutable
 /** The canonical builder for immutable maps, working with the map's `+` method
  *  to add new elements.
  *  Collections are built from their `empty` element using this + method.
+ *
+ *  @tparam A      Type of the keys for the map this builder creates.
+ *  @tparam B      Type of the values for the map this builder creates.
+ *  @tparam Coll   The type of the actual collection this builder builds.
  *  @param empty   The empty element of the collection.
  *
  *  @since 2.8
diff --git a/src/library/scala/collection/mutable/MapProxy.scala b/src/library/scala/collection/mutable/MapProxy.scala
index cb768f6778..7fbb016a57 100644
--- a/src/library/scala/collection/mutable/MapProxy.scala
+++ b/src/library/scala/collection/mutable/MapProxy.scala
@@ -12,20 +12,17 @@
 package scala.collection
 package mutable
 
-/** <p>
- *    This is a simple wrapper class for <a href="Map.html"
- *    target="contentFrame"><code>scala.collection.mutable.Map</code></a>.
- *  </p>
- *  <p>
- *    It is most useful for assembling customized map abstractions
- *    dynamically using object composition and forwarding.
- *  </p>
+/**
+ *  This trait implements a proxy for <a href="Map.html"
+ *  target="contentFrame"><code>scala.collection.mutable.Map</code></a>.
+ *
+ *  It is most useful for assembling customized map abstractions
+ *  dynamically using object composition and forwarding.
  *
  *  @author  Matthias Zenger, Martin Odersky
  *  @version 2.0, 31/12/2006
  *  @since   1
  */
-
 trait MapProxy[A, B] extends Map[A, B] with MapProxyLike[A, B, Map[A, B]]
 {
   private def newProxy[B1 >: B](newSelf: Map[A, B1]): MapProxy[A, B1] =
diff --git a/src/library/scala/collection/mutable/MutableList.scala b/src/library/scala/collection/mutable/MutableList.scala
index 4324fa7ef9..4b6d727c34 100644
--- a/src/library/scala/collection/mutable/MutableList.scala
+++ b/src/library/scala/collection/mutable/MutableList.scala
@@ -16,11 +16,10 @@ import generic._
 import immutable.{List, Nil}
 
 // !!! todo: convert to LinkedListBuffer?
-/** <p>
- *    This class is used internally to represent mutable lists. It is the
- *     basis for the implementation of the classes
- *     <code>Stack</code>, and <code>Queue</code>.
- *  </p>
+/**
+ *  This class is used internally to represent mutable lists. It is the
+ *  basis for the implementation of the classes
+ *  `Stack`, and `Queue`.
  *
  *  @author  Matthias Zenger
  *  @author  Martin Odersky
diff --git a/src/library/scala/collection/mutable/ObservableBuffer.scala b/src/library/scala/collection/mutable/ObservableBuffer.scala
index d3bf49a5b4..8881e78ebc 100644
--- a/src/library/scala/collection/mutable/ObservableBuffer.scala
+++ b/src/library/scala/collection/mutable/ObservableBuffer.scala
@@ -15,9 +15,9 @@ package mutable
 import script._
 
 /** This class is typically used as a mixin. It adds a subscription
- *  mechanism to the <code>Buffer</code> class into which this abstract
- *  class is mixed in. Class <code>ObservableBuffer</code> publishes
- *  events of the type <code>Message</code>.
+ *  mechanism to the `Buffer` class into which this abstract
+ *  class is mixed in. Class `ObservableBuffer` publishes
+ *  events of the type `Message`.
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 08/07/2003
diff --git a/src/library/scala/collection/mutable/ObservableMap.scala b/src/library/scala/collection/mutable/ObservableMap.scala
index b15b2e54e9..0cde1b2288 100644
--- a/src/library/scala/collection/mutable/ObservableMap.scala
+++ b/src/library/scala/collection/mutable/ObservableMap.scala
@@ -16,9 +16,9 @@ import script._
 
 
 /** This class is typically used as a mixin. It adds a subscription
- *  mechanism to the <code>Map</code> class into which this abstract
- *  class is mixed in. Class <code>ObservableMap</code> publishes
- *  events of the type <code>Message</code>.
+ *  mechanism to the `Map` class into which this abstract
+ *  class is mixed in. Class `ObservableMap` publishes
+ *  events of the type `Message`.
  *
  *  @author  Matthias Zenger
  *  @author  Martin Odersky
diff --git a/src/library/scala/collection/mutable/ObservableSet.scala b/src/library/scala/collection/mutable/ObservableSet.scala
index 024c2415ce..1f2f1789f9 100644
--- a/src/library/scala/collection/mutable/ObservableSet.scala
+++ b/src/library/scala/collection/mutable/ObservableSet.scala
@@ -15,9 +15,9 @@ package mutable
 import script._
 
 /** This class is typically used as a mixin. It adds a subscription
- *  mechanism to the <code>Set</code> class into which this abstract
- *  class is mixed in. Class <code>ObservableSet</code> publishes
- *  events of the type <code>Message</code>.
+ *  mechanism to the `Set` class into which this abstract
+ *  class is mixed in. Class `ObservableSet` publishes
+ *  events of the type `Message`.
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 08/07/2003
diff --git a/src/library/scala/collection/mutable/OpenHashMap.scala b/src/library/scala/collection/mutable/OpenHashMap.scala
index cbcc19c3e8..4ecfe0e762 100644
--- a/src/library/scala/collection/mutable/OpenHashMap.scala
+++ b/src/library/scala/collection/mutable/OpenHashMap.scala
@@ -12,8 +12,12 @@
 package scala.collection
 package mutable
 
+
 /**
- * @since 2.7
+ *  @define Coll OpenHashMap
+ *  @define coll open hash map
+ *
+ *  @since 2.7
  */
 object OpenHashMap {
   def apply[K, V](elems : (K, V)*) = {
@@ -42,17 +46,26 @@ object OpenHashMap {
   private[mutable] def nextPowerOfTwo(i : Int) = highestOneBit(i) << 1;
 }
 
-/**
- * A mutable hash map based on an open hashing scheme. The precise scheme is undefined,
- * but it should make a reasonable effort to ensure that an insert with consecutive hash
- * codes is not unneccessarily penalised. In particular, mappings of consecutive integer
- * keys should work without significant performance loss.
+/** A mutable hash map based on an open hashing scheme. The precise scheme is undefined,
+ *  but it should make a reasonable effort to ensure that an insert with consecutive hash
+ *  codes is not unneccessarily penalised. In particular, mappings of consecutive integer
+ *  keys should work without significant performance loss.
+ *
+ *  @tparam Key          type of the keys in this map.
+ *  @tparam Value        type of the values in this map.
+ *  @param initialSize   the initial size of the internal hash table.
  *
- * @author David MacIver
- * @since  2.7
+ *  @author David MacIver
+ *  @since  2.7
+ *
+ *  @define Coll OpenHashMap
+ *  @define coll open hash map
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
-class OpenHashMap[Key, Value](initialSize : Int) extends Map[Key, Value]
-  with MapLike[Key, Value, OpenHashMap[Key, Value]] {
+class OpenHashMap[Key, Value](initialSize : Int)
+extends Map[Key, Value]
+   with MapLike[Key, Value, OpenHashMap[Key, Value]] {
 
   import OpenHashMap.OpenEntry
   type Entry = OpenEntry[Key, Value]
@@ -77,6 +90,7 @@ class OpenHashMap[Key, Value](initialSize : Int) extends Map[Key, Value]
   override def size = _size;
   private[this] def size_=(s : Int) = _size = s;
 
+  /** Returns a mangled hash code of the provided key. */
   protected def hashOf(key : Key) = {
     var h = key.hashCode;
     h ^= ((h >>> 20) ^ (h >>> 12));
@@ -173,9 +187,10 @@ class OpenHashMap[Key, Value](initialSize : Int) extends Map[Key, Value]
     None;
   }
 
-  /**
-   * An iterator over the elements of this map. Use of this iterator follows the same
-   * contract for concurrent modification as the foreach method.
+  /** An iterator over the elements of this map. Use of this iterator follows the same
+   *  contract for concurrent modification as the foreach method.
+   *
+   *  @return   the iterator
    */
   def iterator = new Iterator[(Key, Value)]{
     var index = 0;
@@ -203,19 +218,20 @@ class OpenHashMap[Key, Value](initialSize : Int) extends Map[Key, Value]
   }
 
   /**
-   * Loop over the key, value mappings of this map.
+   *  Loop over the key, value mappings of this map.
    *
-   * The behaviour of modifying the map during an iteration is as follows:
+   *  The behaviour of modifying the map during an iteration is as follows:
    *
-   * <ul>
-   *  <li>Deleting a mapping is always permitted.</li>
-   *  <li>Changing the value of mapping which is already present is permitted.</li>
-   *  <li>Anything else is not permitted. It will usually, but not always, throw an exception.</li>
-   * </ul>
+   *   <ul>
+   *    <li>Deleting a mapping is always permitted.</li>
+   *    <li>Changing the value of mapping which is already present is permitted.</li>
+   *    <li>Anything else is not permitted. It will usually, but not always, throw an exception.</li>
+   *   </ul>
    *
-   * @param  f The function to apply to each key, value mapping.
+   *  @tparam U  The return type of the specified function `f`, return result of which is ignored.
+   *  @param f   The function to apply to each key, value mapping.
    */
-  override def foreach[U](f : ((Key, Value)) =>  U) {
+  override def foreach[U](f : ((Key, Value)) => U) {
     val startModCount = modCount;
     foreachUndeletedEntry(entry => {
       if (modCount != startModCount) error("Concurrent Modification")
@@ -226,6 +242,7 @@ class OpenHashMap[Key, Value](initialSize : Int) extends Map[Key, Value]
   private[this] def foreachUndeletedEntry(f : Entry => Unit){
     table.foreach(entry => if (entry != null && entry.value != None) f(entry));
   }
+
   override def transform(f : (Key, Value) => Value) = {
     foreachUndeletedEntry(entry => entry.value = Some(f(entry.key, entry.value.get)));
     this
diff --git a/src/library/scala/collection/mutable/PriorityQueue.scala b/src/library/scala/collection/mutable/PriorityQueue.scala
index eade376abe..37e1b0ccae 100644
--- a/src/library/scala/collection/mutable/PriorityQueue.scala
+++ b/src/library/scala/collection/mutable/PriorityQueue.scala
@@ -19,11 +19,20 @@ import annotation.migration
  *  To prioritize elements of type T there must be an implicit
  *  Ordering[T] available at creation.
  *
+ *  @tparam A    type of the elements in this priority queue.
+ *  @param ord   implicit ordering used to compare the elements of type `A`.
+ *
  *  @author  Matthias Zenger
  *  @version 1.0, 03/05/2004
  *  @since   1
+ *
+ *  @define Coll PriorityQueue
+ *  @define coll priority queue
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
-
 @serializable @cloneable
 class PriorityQueue[A](implicit ord: Ordering[A])
       extends Seq[A]
@@ -98,6 +107,7 @@ class PriorityQueue[A](implicit ord: Ordering[A])
       k = k / 2
     }
   }
+
   protected def fixDown(as: Array[AnyRef], m: Int, n: Int): Unit = {
     var k: Int = m
     while (n >= 2 * k) {
@@ -134,7 +144,8 @@ class PriorityQueue[A](implicit ord: Ordering[A])
 
   /** Inserts a single element into the priority queue.
    *
-   *  @param  elem        the element to insert
+   *  @param  elem        the element to insert.
+   *  @return             this $coll.
    */
   def +=(elem: A): this.type = {
     resarr.p_ensureSize(resarr.p_size0 + 1)
@@ -147,7 +158,8 @@ class PriorityQueue[A](implicit ord: Ordering[A])
   /** Adds all elements provided by a `TraversableOnce` object
    *  into the priority queue.
    *
-   *  @param  xs    an iterable object
+   *  @param  xs    a traversable object.
+   *  @return       a new priority queue containing elements of both `xs` and `this`.
    */
   def ++(xs: TraversableOnce[A]) = { this.clone() ++= xs }
 
@@ -203,19 +215,19 @@ class PriorityQueue[A](implicit ord: Ordering[A])
     }
   }
 
-  /**
-   * Returns the reverse of this queue. The priority queue that gets
-   * returned will have an inversed ordering - if for some elements
-   * `x` and `y` the original queue's ordering
-   * had `compare` returning an integer ''w'', the new one will return ''-w'',
-   * assuming the original ordering abides its contract.
+
+  /** Returns the reverse of this queue. The priority queue that gets
+   *  returned will have an inversed ordering - if for some elements
+   *  `x` and `y` the original queue's ordering
+   *  had `compare` returning an integer ''w'', the new one will return ''-w'',
+   *  assuming the original ordering abides its contract.
    *
-   * Note that the order of the elements will be reversed unless the
-   * `compare` method returns 0. In this case, such elements
-   * will be subsequent, but their corresponding subinterval may be inappropriately
-   * reversed. However, due to the compare-equals contract, they will also be equal.
+   *  Note that the order of the elements will be reversed unless the
+   *  `compare` method returns 0. In this case, such elements
+   *  will be subsequent, but their corresponding subinterval may be inappropriately
+   *  reversed. However, due to the compare-equals contract, they will also be equal.
    *
-   * @return A reversed priority queue.
+   *  @return   A reversed priority queue.
    */
   override def reverse = {
     val revq = new PriorityQueue[A]()(new math.Ordering[A] {
diff --git a/src/library/scala/collection/mutable/PriorityQueueProxy.scala b/src/library/scala/collection/mutable/PriorityQueueProxy.scala
index 3f1ee5d217..f99755128f 100644
--- a/src/library/scala/collection/mutable/PriorityQueueProxy.scala
+++ b/src/library/scala/collection/mutable/PriorityQueueProxy.scala
@@ -13,7 +13,7 @@ package mutable
 
 /** This class servers as a proxy for priority queues. The
  *  elements of the queue have to be ordered in terms of the
- *  <code>Ordered[T]</code> class.
+ *  `Ordered[T]` class.
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 03/05/2004
@@ -22,7 +22,6 @@ package mutable
 abstract class PriorityQueueProxy[A](implicit ord: Ordering[A]) extends PriorityQueue[A]
          with Proxy
 {
-
   def self: PriorityQueue[A]
 
   /** Creates a new iterator over all elements contained in this
diff --git a/src/library/scala/collection/mutable/Publisher.scala b/src/library/scala/collection/mutable/Publisher.scala
index 58e4394ef7..f91864f974 100644
--- a/src/library/scala/collection/mutable/Publisher.scala
+++ b/src/library/scala/collection/mutable/Publisher.scala
@@ -13,12 +13,14 @@ package scala.collection
 package mutable
 
 
-/** <code>Publisher[A,This]</code> objects publish events of type <code>A</code>
+/** `Publisher[A,This]` objects publish events of type `A`
  *  to all registered subscribers. When subscribing, a subscriber may specify
  *  a filter which can be used to constrain the number of events sent to the
  *  subscriber. Subscribers may suspend their subscription, or reactivate a
- *  suspended subscription. Class <code>Publisher</code> is typically used
- *  as a mixin. The abstract type <code>Pub</code> models the type of the publisher itself.
+ *  suspended subscription. Class `Publisher` is typically used
+ *  as a mixin. The abstract type `Pub` models the type of the publisher itself.
+ *
+ *  @tparam Evt      type of the published event.
  *
  *  @author  Matthias Zenger
  *  @author  Martin Odersky
diff --git a/src/library/scala/collection/mutable/Queue.scala b/src/library/scala/collection/mutable/Queue.scala
index 3754dbc3f2..ef5583ab23 100644
--- a/src/library/scala/collection/mutable/Queue.scala
+++ b/src/library/scala/collection/mutable/Queue.scala
@@ -14,13 +14,20 @@ package mutable
 
 import generic._
 
-/** <code>Queue</code> objects implement data structures that allow to
+/** `Queue` objects implement data structures that allow to
  *  insert and retrieve elements in a first-in-first-out (FIFO) manner.
  *
  *  @author  Matthias Zenger
  *  @author  Martin Odersky
  *  @version 2.8
  *  @since   1
+ *
+ *  @define Coll Queue
+ *  @define coll queue
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable @cloneable
 class Queue[A] extends MutableList[A] with Cloneable[Queue[A]] {
diff --git a/src/library/scala/collection/mutable/QueueProxy.scala b/src/library/scala/collection/mutable/QueueProxy.scala
index b2548b26cc..6adb3d490b 100644
--- a/src/library/scala/collection/mutable/QueueProxy.scala
+++ b/src/library/scala/collection/mutable/QueueProxy.scala
@@ -12,9 +12,11 @@
 package scala.collection
 package mutable
 
-/** <code>Queue</code> objects implement data structures that allow to
+/** `Queue` objects implement data structures that allow to
  *  insert and retrieve elements in a first-in-first-out (FIFO) manner.
  *
+ *  @tparam A   type of the elements in this queue proxy.
+ *
  *  @author  Matthias Zenger
  *  @version 1.1, 03/05/2004
  *  @since   1
diff --git a/src/library/scala/collection/mutable/ResizableArray.scala b/src/library/scala/collection/mutable/ResizableArray.scala
index 80ab1cd559..96d24136cf 100644
--- a/src/library/scala/collection/mutable/ResizableArray.scala
+++ b/src/library/scala/collection/mutable/ResizableArray.scala
@@ -17,6 +17,8 @@ import generic._
 /** This class is used internally to implement data structures that
  *  are based on resizable arrays.
  *
+ *  @tparam A    type of the elements contained in this resizeable array.
+ *
  *  @author  Matthias Zenger, Burak Emir
  *  @author Martin Odersky
  *  @version 2.8
diff --git a/src/library/scala/collection/mutable/RevertibleHistory.scala b/src/library/scala/collection/mutable/RevertibleHistory.scala
index 62e1efba2f..b16577486a 100644
--- a/src/library/scala/collection/mutable/RevertibleHistory.scala
+++ b/src/library/scala/collection/mutable/RevertibleHistory.scala
@@ -13,10 +13,13 @@ package scala.collection
 package mutable
 
 
-/** A revertible history is a <code>History</code> object which supports
- *  an undo operation. Type variable <code>A</code> refers to the type
- *  of the published events, <code>B</code> denotes the publisher type.
- *  Type <code>B</code> is typically a subtype of <code>Publisher</code>.
+/** A revertible history is a `History` object which supports
+ *  an undo operation. Type variable `Evt` refers to the type
+ *  of the published events, `Pub` denotes the publisher type.
+ *  Type `Pub` is typically a subtype of `Publisher`.
+ *
+ *  @tparam Evt   type of the events
+ *  @tparam Pub   type of the publisher
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 08/07/2003
diff --git a/src/library/scala/collection/mutable/Seq.scala b/src/library/scala/collection/mutable/Seq.scala
index 8d11e14063..832e949931 100644
--- a/src/library/scala/collection/mutable/Seq.scala
+++ b/src/library/scala/collection/mutable/Seq.scala
@@ -14,17 +14,21 @@ package mutable
 
 import generic._
 
-/** A subtrait of <code>collection.Seq</code> which represents sequences
+
+/** A subtrait of `collection.Seq` which represents sequences
  *  that can be mutated.
  *
  *  $seqInfo
  *
- *  The class adds an <code>update</code> method to <code>collection.Seq</code>.
+ *  The class adds an `update` method to `collection.Seq`.
+ *
+ *  @define Coll mutable.Seq
+ *  @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.
@@ -36,13 +40,13 @@ trait Seq[A] extends Iterable[A]
   def update(idx: Int, elem: A)
 }
 
-/** A factory object for the trait <code>Seq</code>.
- *
- *  @author  Martin Odersky
- *  @version 2.8
- *  @since   2.8
+
+/** $factoryInfo
+ *  @define coll sequence
+ *  @define Coll 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 cca592b5a0..a816816846 100644
--- a/src/library/scala/collection/mutable/Set.scala
+++ b/src/library/scala/collection/mutable/Set.scala
@@ -17,14 +17,18 @@ 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.
  *
  *  @author Matthias Zenger
- *  @author Martin Odersky
- *  @version 2.8
  *  @since   1
  */
 trait Set[A] extends Iterable[A]
@@ -34,10 +38,12 @@ trait Set[A] extends Iterable[A]
   override def companion: GenericCompanion[Set] = Set
 }
 
-/** The canonical factory methods for <a href="Set.html">mutable sets</a>.
- *  Currently this returns a HashSet.
+/** $factoryInfo
+ *  @define coll set
+ *  @define Coll 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/SetBuilder.scala b/src/library/scala/collection/mutable/SetBuilder.scala
index 450d76463c..b8903372bd 100644
--- a/src/library/scala/collection/mutable/SetBuilder.scala
+++ b/src/library/scala/collection/mutable/SetBuilder.scala
@@ -15,6 +15,8 @@ import generic._
 
 /** The canonical builder for mutable Sets.
  *
+ *  @tparam A      The type of the elements that will be contained in this set.
+ *  @tparam Coll   The type of the actual collection this set builds.
  *  @param empty   The empty element of the collection.
  *  @since 2.8
  */
diff --git a/src/library/scala/collection/mutable/Stack.scala b/src/library/scala/collection/mutable/Stack.scala
index c224c030a4..72e2f928c8 100644
--- a/src/library/scala/collection/mutable/Stack.scala
+++ b/src/library/scala/collection/mutable/Stack.scala
@@ -20,10 +20,18 @@ import annotation.migration
 /** A stack implements a data structure which allows to store and retrieve
  *  objects in a last-in-first-out (LIFO) fashion.
  *
+ *  @tparam A    type of the elements contained in this stack.
+ *
  *  @author  Matthias Zenger
  *  @author  Martin Odersky
  *  @version 2.8
  *  @since   1
+ *  @define Coll Stack
+ *  @define coll stack
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable @cloneable
 class Stack[A] private (var elems: List[A]) extends scala.collection.Seq[A] with Cloneable[Stack[A]] {
diff --git a/src/library/scala/collection/mutable/StackProxy.scala b/src/library/scala/collection/mutable/StackProxy.scala
index d3810dd158..740afdfd7d 100644
--- a/src/library/scala/collection/mutable/StackProxy.scala
+++ b/src/library/scala/collection/mutable/StackProxy.scala
@@ -12,9 +12,12 @@
 package scala.collection
 package mutable
 
+
 /** A stack implements a data structure which allows to store and retrieve
  *  objects in a last-in-first-out (LIFO) fashion.
  *
+ *  @tparam A   type of the elements in this stack proxy.
+ *
  *  @author  Matthias Zenger
  *  @version 1.0, 10/05/2004
  *  @since   1
diff --git a/src/library/scala/collection/mutable/StringBuilder.scala b/src/library/scala/collection/mutable/StringBuilder.scala
index d622d15056..40e7e991ee 100644
--- a/src/library/scala/collection/mutable/StringBuilder.scala
+++ b/src/library/scala/collection/mutable/StringBuilder.scala
@@ -16,11 +16,8 @@ import generic._
 import compat.Platform.arraycopy
 import scala.reflect.Manifest
 
-/** <p>
- *    A mutable sequence of characters.  This class provides an API compatible
- *    with <a class="java/lang/StringBuilder" href="" target="_top">
- *    <code>java.lang.StringBuilder</code></a>.
- *  </p>generic/
+/** A builder for mutable sequence of characters.  This class provides an API compatible
+ *  with <a class="java/lang/StringBuilder" href="" target="_top">`java.lang.StringBuilder`</a>.
  *
  *  @author Stephane Micheloud
  *  @author Martin Odersky
diff --git a/src/library/scala/collection/mutable/SynchronizedBuffer.scala b/src/library/scala/collection/mutable/SynchronizedBuffer.scala
index 0fef1a6635..7bdbd5e520 100644
--- a/src/library/scala/collection/mutable/SynchronizedBuffer.scala
+++ b/src/library/scala/collection/mutable/SynchronizedBuffer.scala
@@ -14,12 +14,16 @@ package mutable
 
 import script._
 
-/** This class should be used as a mixin. It synchronizes the <code>Buffer</code>
+/** This class should be used as a mixin. It synchronizes the `Buffer`
  *  methods of the class into which it is mixed in.
  *
+ *  @tparam A    type of the elements contained in this buffer.
+ *
  *  @author  Matthias Zenger
  *  @version 1.0, 08/07/2003
  *  @since   1
+ *  @define Coll SynchronizedBuffer
+ *  @define coll synchronized buffer
  */
 trait SynchronizedBuffer[A] extends Buffer[A] {
 
diff --git a/src/library/scala/collection/mutable/SynchronizedMap.scala b/src/library/scala/collection/mutable/SynchronizedMap.scala
index dabcaa7e1c..08c370ce90 100644
--- a/src/library/scala/collection/mutable/SynchronizedMap.scala
+++ b/src/library/scala/collection/mutable/SynchronizedMap.scala
@@ -14,12 +14,17 @@ package mutable
 
 import annotation.migration
 
-/** This class should be used as a mixin. It synchronizes the <code>Map</code>
+/** This class should be used as a mixin. It synchronizes the `Map`
  *  functions of the class into which it is mixed in.
  *
+ *  @tparam A     type of the keys contained in this map.
+ *  @tparam B     type of the values associated with keys.
+ *
  *  @author  Matthias Zenger, Martin Odersky
  *  @version 2.0, 31/12/2006
  *  @since   1
+ *  @define Coll SynchronizedMap
+ *  @define coll synchronized map
  */
 trait SynchronizedMap[A, B] extends Map[A, B] {
 
diff --git a/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala b/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala
index 933b3b41a4..bc70e35993 100644
--- a/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala
+++ b/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala
@@ -13,12 +13,16 @@ package scala.collection
 package mutable
 
 /** This class implements synchronized priority queues using a binary heap.
- *  The elements of the queue have to be ordered in terms of the
- *  <code>Ordered[T]</code> class.
+ *  The elements of the queue have to be ordered in terms of the `Ordered[T]` class.
+ *
+ *  @tparam A    type of the elements contained in this synchronized priority queue
+ *  @param ord   implicit ordering used to compared elements of type `A`
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 03/05/2004
  *  @since   1
+ *  @define Coll SynchronizedPriorityQueue
+ *  @define coll synchronized priority queue
  */
 class SynchronizedPriorityQueue[A](implicit ord: Ordering[A]) extends PriorityQueue[A] {
 
diff --git a/src/library/scala/collection/mutable/SynchronizedQueue.scala b/src/library/scala/collection/mutable/SynchronizedQueue.scala
index b09687a78e..7a0f9f5f6f 100644
--- a/src/library/scala/collection/mutable/SynchronizedQueue.scala
+++ b/src/library/scala/collection/mutable/SynchronizedQueue.scala
@@ -13,13 +13,17 @@ package scala.collection
 package mutable
 
 
-/** This is a synchronized version of the <code>Queue[T]</code> class. It
+/** This is a synchronized version of the `Queue[T]` class. It
  *  implements a data structure that allows one to insert and retrieve
  *  elements in a first-in-first-out (FIFO) manner.
  *
+ *  @tparam A     type of elements contained in this synchronized queue.
+ *
  *  @author  Matthias Zenger
  *  @version 1.0, 03/05/2004
  *  @since   1
+ *  @define Coll SynchronizedQueue
+ *  @define coll synchronized queue
  */
 class SynchronizedQueue[A] extends Queue[A] {
   import scala.collection.Traversable
diff --git a/src/library/scala/collection/mutable/SynchronizedSet.scala b/src/library/scala/collection/mutable/SynchronizedSet.scala
index d3023b9136..904da541c2 100644
--- a/src/library/scala/collection/mutable/SynchronizedSet.scala
+++ b/src/library/scala/collection/mutable/SynchronizedSet.scala
@@ -13,12 +13,16 @@ package mutable
 
 import script._
 
-/** This class should be used as a mixin. It synchronizes the <code>Set</code>
+/** This class should be used as a mixin. It synchronizes the `Set`
  *  functions of the class into which it is mixed in.
  *
+ *  @tparam A    type of the elements contained in this synchronized set.
+ *
  *  @author  Matthias Zenger
  *  @version 1.0, 08/07/2003
  *  @since   1
+ *  @define Coll SynchronizedSet
+ *  @define coll synchronized set
  */
 trait SynchronizedSet[A] extends Set[A] {
   import scala.collection.Traversable
diff --git a/src/library/scala/collection/mutable/SynchronizedStack.scala b/src/library/scala/collection/mutable/SynchronizedStack.scala
index 4940884302..9109d2ef5d 100644
--- a/src/library/scala/collection/mutable/SynchronizedStack.scala
+++ b/src/library/scala/collection/mutable/SynchronizedStack.scala
@@ -13,13 +13,17 @@ package scala.collection
 package mutable
 
 
-/** This is a synchronized version of the <code>Stack[T]</code> class. It
+/** This is a synchronized version of the `Stack[T]` class. It
  *  implements a data structure which allows to store and retrieve
  *  objects in a last-in-first-out (LIFO) fashion.
  *
+ *  @tparam A    type of the elements contained in this stack.
+ *
  *  @author  Matthias Zenger
  *  @version 1.0, 03/05/2004
  *  @since   1
+ *  @define Coll SynchronizedStack
+ *  @define coll synchronized stack
  */
 class SynchronizedStack[A] extends Stack[A] {
   import scala.collection.Traversable
diff --git a/src/library/scala/collection/mutable/Traversable.scala b/src/library/scala/collection/mutable/Traversable.scala
index 89c8868314..9a7153235a 100644
--- a/src/library/scala/collection/mutable/Traversable.scala
+++ b/src/library/scala/collection/mutable/Traversable.scala
@@ -25,10 +25,9 @@ trait Traversable[A] extends scala.collection.Traversable[A]
   override def companion: GenericCompanion[Traversable] = Traversable
 }
 
-/** A factory object for the trait <code>Traversable</code>.
- *
- *  @author  Martin Odersky
- *  @version 2.8
+/** $factoryInfo
+ *  @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]
diff --git a/src/library/scala/collection/mutable/Undoable.scala b/src/library/scala/collection/mutable/Undoable.scala
index 782e407843..45d3121bd3 100644
--- a/src/library/scala/collection/mutable/Undoable.scala
+++ b/src/library/scala/collection/mutable/Undoable.scala
@@ -13,8 +13,8 @@ package scala.collection
 package mutable
 
 
-/** Classes that mix in the <code>Undoable</code> class provide an operation
- *  <code>undo</code> which can be used to undo the last operation.
+/** Classes that mix in the `Undoable` class provide an operation
+ *  `undo` which can be used to undo the last operation.
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 08/07/2003
diff --git a/src/library/scala/collection/mutable/WeakHashMap.scala b/src/library/scala/collection/mutable/WeakHashMap.scala
index 8f496add1e..929c3f8fed 100644
--- a/src/library/scala/collection/mutable/WeakHashMap.scala
+++ b/src/library/scala/collection/mutable/WeakHashMap.scala
@@ -16,15 +16,35 @@ import JavaConversions._
 import generic._
 
 
-/** A hash map with weak references to entries which are weakly reachable.
+/** A hash map with references to entries which are weakly reachable.
+ *
+ *  @tparam A      type of keys contained in this map
+ *  @tparam B      type of values associated with the keys
  *
  *  @since 2.8
+ *  @define Coll WeakHashMap
+ *  @define coll weak hash map
+ *  @define thatinfo the class of the returned collection. In the standard library configuration,
+ *    `That` is always `WeakHashMap[A, B]` if the elements contained in the resulting collection are
+ *    pairs of type `(A, B)`. This is because an implicit of type `CanBuildFrom[WeakHashMap, (A, B), WeakHashMap[A, B]]`
+ *    is defined in object `WeakHashMap`. Otherwise, `That` resolves to the most specific type that doesn't have
+ *    to contain pairs of type `(A, B)`, which is `Iterable`.
+ *  @define $bfinfo an implicit value of class `CanBuildFrom` which determines the
+ *    result class `That` from the current representation type `Repr`
+ *    and the new element type `B`. This is usually the `canBuildFrom` value
+ *    defined in object `WeakHashMap`.
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 class WeakHashMap[A, B] extends JMapWrapper[A, B](new java.util.WeakHashMap)
 			   with JMapWrapperLike[A, B, WeakHashMap[A, B]] {
   override def empty = new WeakHashMap[A, B]
 }
 
+/** $factoryInfo
+ *  @define Coll WeakHashMap
+ *  @define coll weak hash map
+ */
 object WeakHashMap extends MutableMapFactory[WeakHashMap] {
   implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), WeakHashMap[A, B]] = new MapCanBuildFrom[A, B]
   def empty[A, B]: WeakHashMap[A, B] = new WeakHashMap[A, B]
diff --git a/src/library/scala/collection/mutable/WrappedArray.scala b/src/library/scala/collection/mutable/WrappedArray.scala
index 10117a1086..b9e803d8dc 100644
--- a/src/library/scala/collection/mutable/WrappedArray.scala
+++ b/src/library/scala/collection/mutable/WrappedArray.scala
@@ -16,11 +16,19 @@ import scala.reflect.ClassManifest
 import scala.collection.generic._
 
 /**
- *  <p>A class representing <code>Array[T]</code></p>
+ *  A class representing `Array[T]`.
+ *
+ *  @tparam T    type of the elements in this wrapped array.
  *
  *  @author  Martin Odersky, Stephane Micheloud
  *  @version 1.0
  *  @since 2.8
+ *  @define Coll WrappedArray
+ *  @define coll wrapped array
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 abstract class WrappedArray[T] extends IndexedSeq[T] with ArrayLike[T, WrappedArray[T]] {
 
@@ -59,6 +67,8 @@ abstract class WrappedArray[T] extends IndexedSeq[T] with ArrayLike[T, WrappedAr
     new WrappedArrayBuilder[T](elemManifest)
 }
 
+/** A companion object used to create instances of `WrappedArray`.
+ */
 object WrappedArray {
   def make[T](x: AnyRef): WrappedArray[T] = x match {
     case x: Array[AnyRef] => wrapRefArray[AnyRef](x).asInstanceOf[WrappedArray[T]]
diff --git a/src/library/scala/collection/mutable/WrappedArrayBuilder.scala b/src/library/scala/collection/mutable/WrappedArrayBuilder.scala
index 7f1e4b3254..012a0be862 100644
--- a/src/library/scala/collection/mutable/WrappedArrayBuilder.scala
+++ b/src/library/scala/collection/mutable/WrappedArrayBuilder.scala
@@ -15,7 +15,10 @@ package mutable
 import generic._
 import scala.reflect.ClassManifest
 
-/** A builder class for arrays
+/** A builder class for arrays.
+ *
+ *  @tparam A         type of elements that can be added to this builder.
+ *  @param manifest   class manifest for objects of type `A`.
  *
  *  @since 2.8
  */