More docs. No review.

25 files changed, 207 insertions, 74 deletions

diff --git a/src/library/scala/collection/generic/MapFactory.scala b/src/library/scala/collection/generic/MapFactory.scala
index 49fa692ebf..fc04f28f26 100644
--- a/src/library/scala/collection/generic/MapFactory.scala
+++ b/src/library/scala/collection/generic/MapFactory.scala
@@ -14,10 +14,22 @@ package generic
 
 import mutable.{Builder, MapBuilder}
 
-/** A template for companion objects of <code>mutable.Map</code> and
- *  subclasses thereof.
+/** 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 `$Coll` values.
+ *    @author Martin Odersky
+ *    @version 2.8
+ *  @define canBuildFromInfo
+ *    The standard `CanBuildFrom` instance for `$Coll` objects.
+ *    @see CanBuildFrom
+ *  @define mapCanBuildFromInfo
+ *    The standard `CanBuildFrom` instance for `$Coll` objects.
+ *    The created value is an instance of class `MapCanBuildFrom`.
+ *    @see CanBuildFrom
+ *    @see GenericCanBuildFrom
  */
 abstract class MapFactory[CC[A, B] <: Map[A, B] with MapLike[A, B, CC[A, B]]] {
 
diff --git a/src/library/scala/collection/generic/MutableMapFactory.scala b/src/library/scala/collection/generic/MutableMapFactory.scala
index 4ad9fb59e4..0f1608ee71 100644
--- a/src/library/scala/collection/generic/MutableMapFactory.scala
+++ b/src/library/scala/collection/generic/MutableMapFactory.scala
@@ -14,7 +14,7 @@ package generic
 
 import mutable.MapBuilder
 
-/** A template for companion objects of mutable.Map and subclasses thereof.
+/** A template for companion objects of `mutable.Map` and subclasses thereof.
  *
  *  @since 2.8
  */
diff --git a/src/library/scala/collection/generic/SetFactory.scala b/src/library/scala/collection/generic/SetFactory.scala
index de2baaa222..6a237d453c 100644
--- a/src/library/scala/collection/generic/SetFactory.scala
+++ b/src/library/scala/collection/generic/SetFactory.scala
@@ -17,7 +17,19 @@ import mutable.{Builder, AddingBuilder}
 /** A template for companion objects of <code>Set</code> and subclasses
  *  thereof.
  *
- *  @since 2.8
+ *  @define coll set
+ *  @define Coll Set
+ *  @define factoryInfo
+ *    This object provides a set of operations needed to create `$Coll` values.
+ *    @author Martin Odersky
+ *    @version 2.8
+ *  @define canBuildFromInfo
+ *    The standard `CanBuildFrom` instance for `$Coll` objects.
+ *    @see CanBuildFrom
+ *  @define setCanBuildFromInfo
+ *    The standard `CanBuildFrom` instance for `$Coll` objects.
+ *    @see CanBuildFrom
+ *    @see GenericCanBuildFrom
  */
 abstract class SetFactory[CC[X] <: Set[X] with SetLike[X, CC[X]]]
   extends GenericCompanion[CC] {
diff --git a/src/library/scala/collection/mutable/ArrayBuffer.scala b/src/library/scala/collection/mutable/ArrayBuffer.scala
index 7efa56f0a9..bee531221f 100644
--- a/src/library/scala/collection/mutable/ArrayBuffer.scala
+++ b/src/library/scala/collection/mutable/ArrayBuffer.scala
@@ -29,7 +29,7 @@ import generic._
  *  @define Coll ArrayBuffer
  *  @define coll arraybuffer
  *  @define thatinfo the class of the returned collection. In the standard library configuration,
- *    `That` is always `ArrayBuffer[B]` because an implicit of type `CanBuildFrom[ArrayBuffer, B, That]`
+ *    `That` is always `ArrayBuffer[B]` because an implicit of type `CanBuildFrom[ArrayBuffer, B, ArrayBuffer[B]]`
  *    is defined in object `ArrayBuffer`.
  *  @define $bfinfo an implicit value of class `CanBuildFrom` which determines the
  *    result class `That` from the current representation type `Repr`
diff --git a/src/library/scala/collection/mutable/ArraySeq.scala b/src/library/scala/collection/mutable/ArraySeq.scala
index c903dae55c..d59cf684b2 100644
--- a/src/library/scala/collection/mutable/ArraySeq.scala
+++ b/src/library/scala/collection/mutable/ArraySeq.scala
@@ -28,7 +28,7 @@ import generic._
  *  @define Coll ArraySeq
  *  @define coll array sequence
  *  @define thatinfo the class of the returned collection. In the standard library configuration,
- *    `That` is always `ArraySeq[B]` because an implicit of type `CanBuildFrom[ArraySeq, B, That]`
+ *    `That` is always `ArraySeq[B]` because an implicit of type `CanBuildFrom[ArraySeq, B, ArraySeq[B]]`
  *    is defined in object `ArraySeq`.
  *  @define $bfinfo an implicit value of class `CanBuildFrom` which determines the
  *    result class `That` from the current representation type `Repr`
diff --git a/src/library/scala/collection/mutable/Cloneable.scala b/src/library/scala/collection/mutable/Cloneable.scala
index 34e0548cb8..099c6a68b4 100644
--- a/src/library/scala/collection/mutable/Cloneable.scala
+++ b/src/library/scala/collection/mutable/Cloneable.scala
@@ -14,7 +14,9 @@ package mutable
 
 /** A trait for cloneable collections.
  *
- * @since 2.8
+ *  @since 2.8
+ *
+ *  @tparam A    Type of the elements contained in the collection, covariant and with reference types as upperbound.
  */
 @cloneable
 trait Cloneable[+A <: AnyRef]  {
diff --git a/src/library/scala/collection/mutable/CloneableCollection.scala b/src/library/scala/collection/mutable/CloneableCollection.scala
index f859b9e82b..a88d85965f 100644
--- a/src/library/scala/collection/mutable/CloneableCollection.scala
+++ b/src/library/scala/collection/mutable/CloneableCollection.scala
@@ -12,8 +12,8 @@
 package scala.collection
 package mutable
 
-/** The J2ME version of the library defined this trait with a <code>clone</code>
- *  method to substitute for the lack of <code>Object.clone</code> there.
+/** The J2ME version of the library defined this trait with a `clone`
+ *  method to substitute for the lack of `Object.clone` there.
  *
  *  @since 2.6
  */
diff --git a/src/library/scala/collection/mutable/ConcurrentMap.scala b/src/library/scala/collection/mutable/ConcurrentMap.scala
index 10c1f9223b..f9505f694b 100644
--- a/src/library/scala/collection/mutable/ConcurrentMap.scala
+++ b/src/library/scala/collection/mutable/ConcurrentMap.scala
@@ -1,24 +1,26 @@
 package scala.collection
 package mutable
 
-/**
- * A template trait for mutable maps that allow concurrent access.
+
+/** A template trait for mutable maps that allow concurrent access.
  *
- * $concurrentmapinfo
+ *  $concurrentmapinfo
  *
- * @tparam A  the key type of the map
- * @tparam B  the value type of the map
+ *  @since 2.8
  *
- * @define concurrentmapinfo
- * This is a base trait for all Scala concurrent map implementations. It
- * provides all of the methods a Map does, with the difference that all the
- * changes are atomic. It also describes methods specific to concurrent maps.
- * Note: The concurrent maps do not accept `null` for keys or values.
+ *  @tparam A  the key type of the map
+ *  @tparam B  the value type of the map
  *
- * @define atomicop
- * This is done atomically.
+ *  @define Coll ConcurrentMap
+ *  @define coll concurrent map
+ *  @define concurrentmapinfo
+ *  This is a base trait for all Scala concurrent map implementations. It
+ *  provides all of the methods a `Map` does, with the difference that all the
+ *  changes are atomic. It also describes methods specific to concurrent maps.
+ *  Note: The concurrent maps do not accept `null` for keys or values.
  *
- * @since 2.8
+ *  @define atomicop
+ *  This is done atomically.
  */
 trait ConcurrentMap[A, B] extends Map[A, B] {
 
diff --git a/src/library/scala/collection/mutable/DefaultEntry.scala b/src/library/scala/collection/mutable/DefaultEntry.scala
index 6071efcb9a..553fb3c678 100644
--- a/src/library/scala/collection/mutable/DefaultEntry.scala
+++ b/src/library/scala/collection/mutable/DefaultEntry.scala
@@ -12,8 +12,10 @@
 package scala.collection
 package mutable
 
-/**
- * @since 2.3
+
+
+/** Class used internally for default map model.
+ *  @since 2.3
  */
 @serializable
 final class DefaultEntry[A, B](val key: A, var value: B)
diff --git a/src/library/scala/collection/mutable/DefaultMapModel.scala b/src/library/scala/collection/mutable/DefaultMapModel.scala
index fbe46e2a72..d22b20e10c 100644
--- a/src/library/scala/collection/mutable/DefaultMapModel.scala
+++ b/src/library/scala/collection/mutable/DefaultMapModel.scala
@@ -12,9 +12,8 @@
 package scala.collection
 package mutable
 
-/** This class is used internally. It implements the mutable <code>Map</code>
- *  class in terms of three functions: <code>findEntry</code>,
- *  <code>addEntry</code>, and <code>entries</code>.
+/** This class is used internally. It implements the mutable `Map`
+ *  class in terms of three functions: `findEntry`, `addEntry`, and `entries`.
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 08/07/2003
diff --git a/src/library/scala/collection/mutable/DoubleLinkedList.scala b/src/library/scala/collection/mutable/DoubleLinkedList.scala
index 718d6aa35d..d76ee7fa72 100644
--- a/src/library/scala/collection/mutable/DoubleLinkedList.scala
+++ b/src/library/scala/collection/mutable/DoubleLinkedList.scala
@@ -14,13 +14,29 @@ package mutable
 
 import generic._
 
-/** This class implements double linked lists where both the head (<code>elem</code>)
- *  and the tail (<code>next</code>) are mutable.
+/** This class implements double linked lists where both the head (`elem`)
+ *  and the tail (`next`) are mutable.
  *
  *  @author Matthias Zenger
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   1
+ *
+ *  @tparam A     the type of the elements contained in this double linked list.
+ *
+ *  @define Coll DoubleLinkedList
+ *  @define coll double linked list
+ *  @define thatinfo the class of the returned collection. In the standard library configuration,
+ *    `That` is always `DoubleLinkedList[B]` because an implicit of type `CanBuildFrom[DoubleLinkedList, B, DoubleLinkedList[B]]`
+ *    is defined in object `DoubleLinkedList`.
+ *  @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 `DoubleLinkedList`.
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable @SerialVersionUID(-8144992287952814767L)
 class DoubleLinkedList[A]() extends LinearSeq[A]
@@ -28,6 +44,11 @@ class DoubleLinkedList[A]() extends LinearSeq[A]
                             with DoubleLinkedListLike[A, DoubleLinkedList[A]] {
   next = this
 
+  /** Creates a node for the double linked list.
+   *
+   *  @param elem    the element this node contains.
+   *  @param next    the next node in the double linked list.
+   */
   def this(elem: A, next: DoubleLinkedList[A]) {
     this()
     if (next != null) {
@@ -39,7 +60,12 @@ class DoubleLinkedList[A]() extends LinearSeq[A]
   override def companion: GenericCompanion[DoubleLinkedList] = DoubleLinkedList
 }
 
+/** $factoryInfo
+ *  @define coll double linked list
+ *  @define Coll DoubleLinkedList
+ */
 object DoubleLinkedList extends SeqFactory[DoubleLinkedList] {
+  /** $genericCanBuildFrom */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, DoubleLinkedList[A]] = new GenericCanBuildFrom[A]
   def newBuilder[A]: Builder[A, DoubleLinkedList[A]] =
     new Builder[A, DoubleLinkedList[A]] {
diff --git a/src/library/scala/collection/mutable/DoubleLinkedListLike.scala b/src/library/scala/collection/mutable/DoubleLinkedListLike.scala
index 269d1997d0..b908a1802b 100644
--- a/src/library/scala/collection/mutable/DoubleLinkedListLike.scala
+++ b/src/library/scala/collection/mutable/DoubleLinkedListLike.scala
@@ -13,16 +13,23 @@ package scala.collection
 package mutable
 
 /** This extensible class may be used as a basis for implementing double
- *  linked lists. Type variable <code>A</code> refers to the element type
- *  of the list, type variable <code>This</code> is used to model self
+ *  linked lists. Type variable `A` refers to the element type
+ *  of the list, type variable `This` is used to model self
  *  types of linked lists.
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 08/07/2003
  *  @since   2.8
+ *
+ *  @tparam A    type of the elements contained in the double linked list
+ *  @tparam This the type of the actual linked list holding the elements
+ *
+ *  @define Coll DoubleLinkedList
+ *  @define coll double linked list
  */
 trait DoubleLinkedListLike[A, This <: Seq[A] with DoubleLinkedListLike[A, This]] extends LinkedListLike[A, This] { self =>
 
+  /** A reference to the node in the linked list preceeding the current node. */
   var prev: This = _
 
   override def append(that: This): This =
diff --git a/src/library/scala/collection/mutable/FlatHashTable.scala b/src/library/scala/collection/mutable/FlatHashTable.scala
index ea4033d405..05eafbc811 100644
--- a/src/library/scala/collection/mutable/FlatHashTable.scala
+++ b/src/library/scala/collection/mutable/FlatHashTable.scala
@@ -11,8 +11,15 @@
 package scala.collection
 package mutable
 
-/** An implementation class backing a HashSet.
- * @since 2.3
+
+/** An implementation class backing a `HashSet`.
+ *
+ *  This trait is used internally. It can be mixed in with various collections relying on
+ *  hash table as an implementation.
+ *
+ *  @since 2.3
+ *
+ *  @tparam A   the type of the elements contained in the flat hash table.
  */
 trait FlatHashTable[A] {
 
@@ -85,6 +92,7 @@ trait FlatHashTable[A] {
     iterator.foreach(out.writeObject)
   }
 
+  /** Finds an entry in the hash table if such an element exists. */
   def findEntry(elem: A): Option[A] = {
     var h = index(elemHashCode(elem))
     var entry = table(h)
@@ -95,6 +103,7 @@ trait FlatHashTable[A] {
     if (null == entry) None else Some(entry.asInstanceOf[A])
   }
 
+  /** Checks whether an element is contained in the hash table. */
   def containsEntry(elem: A): Boolean = {
     var h = index(elemHashCode(elem))
     var entry = table(h)
@@ -105,8 +114,8 @@ trait FlatHashTable[A] {
     null != entry
   }
 
-  /** Add entry if not yet in table
-   *  Return whether a new entry was added
+  /** Add entry if not yet in table.
+   *  @return Returns `true` if a new entry was added, `false` otherwise.
    */
   def addEntry(elem: A) : Boolean = {
     var h = index(elemHashCode(elem))
@@ -122,6 +131,7 @@ trait FlatHashTable[A] {
     true
   }
 
+  /** Removes an entry from the hash table, returning an option value with the element, or `None` if it didn't exist. */
   def removeEntry(elem: A) : Option[A] = {
     if (tableDebug) checkConsistent()
     def precedes(i: Int, j: Int) = {
diff --git a/src/library/scala/collection/mutable/GrowingBuilder.scala b/src/library/scala/collection/mutable/GrowingBuilder.scala
index 445e9d4f3e..cd1c8bec8c 100644
--- a/src/library/scala/collection/mutable/GrowingBuilder.scala
+++ b/src/library/scala/collection/mutable/GrowingBuilder.scala
@@ -13,14 +13,17 @@ import generic._
 
 /** The canonical builder for collections that are growable, i.e. that support an
  *  efficient `+=` method which adds an element to the collection.  It is
- *  almost identical to AddingBuilder, but necessitated by the existence of
- *  classes which are Growable but not Addable, which is a result of covariance
- *  interacting surprisingly with any2stringadd thus driving '+' out of the Seq
+ *  almost identical to `AddingBuilder`, but necessitated by the existence of
+ *  classes which are `Growable` but not `Addable`, which is a result of covariance
+ *  interacting surprisingly with any2stringadd thus driving '+' out of the `Seq`
  *  hierarchy.  The tendrils of original sin should never be underestimated.
  *
  *  @author Paul Phillips
  *  @version 2.8
  *  @since 2.8
+ *
+ *  @define Coll GrowingBuilder
+ *  @define coll growing builder
  */
 class GrowingBuilder[Elem, To <: Growable[Elem]](empty: To) extends Builder[Elem, To] {
   protected var elems: To = empty
diff --git a/src/library/scala/collection/mutable/HashEntry.scala b/src/library/scala/collection/mutable/HashEntry.scala
index 3373913412..7c62dc6281 100644
--- a/src/library/scala/collection/mutable/HashEntry.scala
+++ b/src/library/scala/collection/mutable/HashEntry.scala
@@ -8,8 +8,8 @@
 package scala.collection
 package mutable
 
-/**
- * @since 2.8
+/** Class used internally.
+ *  @since 2.8
  */
 trait HashEntry [A, E] {
   val key: A
diff --git a/src/library/scala/collection/mutable/HashMap.scala b/src/library/scala/collection/mutable/HashMap.scala
index 2b5cad37d8..215e0323b3 100644
--- a/src/library/scala/collection/mutable/HashMap.scala
+++ b/src/library/scala/collection/mutable/HashMap.scala
@@ -14,8 +14,27 @@ package mutable
 
 import generic._
 
-/**
- * @since 1
+
+/** This class implements mutable maps using a hashtable.
+ *
+ *  @since 1
+ *
+ *  @tparam A    the type of the keys contained in this hash map.
+ *  @tparam B    the type of the values assigned to keys in this hash map.
+ *
+ *  @define Coll mutable.HashMap
+ *  @define coll mutable hash map
+ *  @define thatinfo the class of the returned collection. In the standard library configuration,
+ *    `That` is always `HashMap[A, B]` if the elements contained in the resulting collection are
+ *    pairs of type `(A, B)`. This is because an implicit of type `CanBuildFrom[HashMap, (A, B), HashMap[A, B]]`
+ *    is defined in object `HashMap`. 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 `HashMap`.
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable @SerialVersionUID(1L)
 class HashMap[A, B] extends Map[A, B]
@@ -94,11 +113,9 @@ class HashMap[A, B] extends Map[A, B]
   }
 }
 
-/** This class implements mutable maps using a hashtable.
- *
- *  @author  Matthias Zenger
- *  @author  Martin Odersky
- *  @version 2.8
+/** $factoryInfo
+ *  @define Coll mutable.HashMap
+ *  @define coll mutable hash map
  */
 object HashMap extends MutableMapFactory[HashMap] {
   implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), HashMap[A, B]] = new MapCanBuildFrom[A, B]
diff --git a/src/library/scala/collection/mutable/HashSet.scala b/src/library/scala/collection/mutable/HashSet.scala
index e985e717b0..3d9dc3e55d 100644
--- a/src/library/scala/collection/mutable/HashSet.scala
+++ b/src/library/scala/collection/mutable/HashSet.scala
@@ -20,6 +20,20 @@ import generic._
  *  @author  Martin Odersky
  *  @version 2.0, 31/12/2006
  *  @since   1
+ *
+ *  @tparam A     the type of the elements contained in this set.
+ *
+ *  @define Coll mutable.HashSet
+ *  @define coll mutable hash set
+ *  @define thatinfo the class of the returned collection. In the standard library configuration,
+ *    `That` is always `HashSet[B]` because an implicit of type `CanBuildFrom[HashSet, B, HashSet[B]]`
+ *    is defined in object `HashSet`.
+ *  @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 `HashSet`.
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable @SerialVersionUID(1L)
 class HashSet[A] extends Set[A]
@@ -61,7 +75,10 @@ class HashSet[A] extends Set[A]
   }
 }
 
-/** Factory object for `HashSet` class */
+/** $factoryInfo
+ *  @define Coll mutable.HashSet
+ *  @define coll mutable hash set
+ */
 object HashSet extends SetFactory[HashSet] {
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, HashSet[A]] = setCanBuildFrom[A]
   override def empty[A]: HashSet[A] = new HashSet[A]
diff --git a/src/library/scala/collection/mutable/HashTable.scala b/src/library/scala/collection/mutable/HashTable.scala
index 1f6b6152cb..04b5e5e3a1 100644
--- a/src/library/scala/collection/mutable/HashTable.scala
+++ b/src/library/scala/collection/mutable/HashTable.scala
@@ -13,22 +13,24 @@ package scala.collection
 package mutable
 
 /** This class can be used to construct data structures that are based
- *  on hashtables. Class <code>HashTable[A]</code> implements a hashtable
- *  that maps keys of type <code>A</code> to values of the fully abstract
- *  member type <code>Entry</code>. Classes that make use of <code>HashTable</code>
- *  have to provide an implementation for <code>Entry</code>
+ *  on hashtables. Class `HashTable[A]` implements a hashtable
+ *  that maps keys of type `A` to values of the fully abstract
+ *  member type `Entry`. Classes that make use of `HashTable`
+ *  have to provide an implementation for `Entry`.
  *
  *  There are mainly two parameters that affect the performance of a hashtable:
  *  the <i>initial size</i> and the <i>load factor</i>. The <i>size</i>
  *  refers to the number of <i>buckets</i> in the hashtable, and the <i>load
  *  factor</i> is a measure of how full the hashtable is allowed to get before
  *  its size is automatically doubled. Both parameters may be changed by
- *  overriding the corresponding values in class <code>HashTable</code>.
+ *  overriding the corresponding values in class `HashTable`.
  *
  *  @author  Matthias Zenger
  *  @author  Martin Odersky
  *  @version 2.0, 31/12/2006
  *  @since   1
+ *
+ *  @tparam A     type of the elements contained in this hash table.
  */
 trait HashTable[A] {
   import HashTable._
diff --git a/src/library/scala/collection/mutable/History.scala b/src/library/scala/collection/mutable/History.scala
index 40ebfe5fa5..ffa3d6481a 100644
--- a/src/library/scala/collection/mutable/History.scala
+++ b/src/library/scala/collection/mutable/History.scala
@@ -13,14 +13,17 @@ package scala.collection
 package mutable
 
 
-/** <code>History[A, B]</code> objects may subscribe to events of
- *  type <code>A</code> published by an object of type <code>B</code>.
+/** `History[A, B]` objects may subscribe to events of
+ *  type `A` published by an object of type `B`.
  *  The history subscriber object records all published events
- *  up to maximum number of <code>maxHistory</code> events.
+ *  up to maximum number of `maxHistory` events.
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 08/07/2003
  *  @since   1
+ *
+ *  @tparam Evt   Type of events.
+ *  @tparam Pub   Type of publishers.
  */
 @serializable
 @SerialVersionUID(5219213543849892588L)
@@ -29,9 +32,10 @@ class History[Evt, Pub] extends Subscriber[Evt, Pub] with Iterable[(Pub, Evt)]
   protected val log: Queue[(Pub, Evt)] = new Queue
   val maxHistory: Int = 1000
 
-  /**
-   *  @param pub   ...
-   *  @param event ...
+  /** Notifies this listener with an event by enqueuing it in the log.
+   *
+   *  @param pub   the publisher.
+   *  @param event the event.
    */
   def notify(pub: Pub, event: Evt) {
     if (log.length >= maxHistory)
diff --git a/src/library/scala/collection/mutable/ImmutableMapAdaptor.scala b/src/library/scala/collection/mutable/ImmutableMapAdaptor.scala
index fba28e7c2a..c2b7cfd2b8 100644
--- a/src/library/scala/collection/mutable/ImmutableMapAdaptor.scala
+++ b/src/library/scala/collection/mutable/ImmutableMapAdaptor.scala
@@ -15,9 +15,9 @@ package mutable
 import annotation.migration
 
 /** This class can be used as an adaptor to create mutable maps from
- *  immutable map implementations. Only method <code>empty</code> has
+ *  immutable map implementations. Only method `empty` has
  *  to be redefined if the immutable map on which this mutable map is
- *  originally based is not empty. <code>empty</code> is supposed to
+ *  originally based is not empty. `empty` is supposed to
  *  return the representation of an empty map.
  *
  *  @author  Matthias Zenger
diff --git a/src/library/scala/collection/mutable/ImmutableSetAdaptor.scala b/src/library/scala/collection/mutable/ImmutableSetAdaptor.scala
index 5b0ed17788..a56f65e379 100644
--- a/src/library/scala/collection/mutable/ImmutableSetAdaptor.scala
+++ b/src/library/scala/collection/mutable/ImmutableSetAdaptor.scala
@@ -14,9 +14,9 @@ package mutable
 
 
 /** This class can be used as an adaptor to create mutable sets from
- *  immutable set implementations. Only method <code>empty</code> has
+ *  immutable set implementations. Only method `empty` has
  *  to be redefined if the immutable set on which this mutable set is
- *  originally based is not empty. <code>empty</code> is supposed to
+ *  originally based is not empty. `empty` is supposed to
  *  return the representation of an empty set.
  *
  *  @author  Matthias Zenger
diff --git a/src/library/scala/collection/mutable/IndexedSeq.scala b/src/library/scala/collection/mutable/IndexedSeq.scala
index 631a4abfc9..14ee5afc9b 100644
--- a/src/library/scala/collection/mutable/IndexedSeq.scala
+++ b/src/library/scala/collection/mutable/IndexedSeq.scala
@@ -14,8 +14,9 @@ package mutable
 
 import generic._
 
-/** A subtrait of <code>collection.IndexedSeq</code> which represents sequences
+/** A subtrait of `collection.IndexedSeq` which represents sequences
  *  that can be mutated.
+ *
  *  $indexedSeqInfo
  */
 trait IndexedSeq[A] extends Seq[A]
diff --git a/src/library/scala/collection/mutable/IndexedSeqLike.scala b/src/library/scala/collection/mutable/IndexedSeqLike.scala
index a0f9205da2..0c2d3f17bb 100644
--- a/src/library/scala/collection/mutable/IndexedSeqLike.scala
+++ b/src/library/scala/collection/mutable/IndexedSeqLike.scala
@@ -16,7 +16,26 @@ import generic._
 /** A subtrait of scala.collection.IndexedSeq which represents sequences
  *  that can be mutated.
  *
- *  @since 2.8
+ *  It declares a method `update` which allows updating an element
+ *  at a specific index in the sequence.
+ *
+ *  This trait just implements `iterator` in terms of `apply` and `length`.
+ *  However, see `IndexedSeqOptimized` for an implementation trait that overrides operations
+ *  to make them run faster under the assumption of fast random access with `apply`.
+ *
+ *  $indexedSeqInfo
+ *
+ *  @tparam A    the element type of the $coll
+ *  @tparam Repr the type of the actual $coll containing the elements.
+ *
+ *  @define Coll IndexedSeq
+ *  @define coll mutable indexed sequence
+ *  @define indexedSeqInfo
+ *  @author Martin Odersky
+ *  @version 2.8
+ *  @since   2.8
+ *  @define willNotTerminateInf
+ *  @define mayNotTerminateInf
  */
 trait IndexedSeqLike[A, +Repr] extends scala.collection.IndexedSeqLike[A, Repr] { self =>
 
diff --git a/src/library/scala/collection/mutable/Iterable.scala b/src/library/scala/collection/mutable/Iterable.scala
index e2d0707a1c..85c6df6fb0 100644
--- a/src/library/scala/collection/mutable/Iterable.scala
+++ b/src/library/scala/collection/mutable/Iterable.scala
@@ -20,13 +20,9 @@ trait Iterable[A] extends Traversable[A]
   override def companion: GenericCompanion[Iterable] = Iterable
 }
 
-/** <p>
- *    A factory object for the trait <a href="Iterable.html"
- *    target="contentFrame"><code>Iterable</code></a>.
- *  </p>
- *
- *  @author   Martin Odersky
- *  @version 2.8
+/** $factoryInfo
+ *  @define coll indexed sequence
+ *  @define Coll IndexedSeq
  */
 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/SetLike.scala b/src/library/scala/collection/mutable/SetLike.scala
index 7004e52b8e..9dbfaf6d5e 100644
--- a/src/library/scala/collection/mutable/SetLike.scala
+++ b/src/library/scala/collection/mutable/SetLike.scala
@@ -26,7 +26,8 @@ import scala.annotation.migration
  *  @version 2.8
  *  @since 2.8
  *
- *  @define setnote @note
+ *  @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.
  *
@@ -108,6 +109,7 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
 
   // abstract methods from Growable/Shrinkable
 
+  /** Adds a single element to the set. */
   def +=(elem: A): this.type
   def -=(elem: A): this.type