Updated documentation

23 files changed, 107 insertions, 122 deletions

diff --git a/src/library/scala/collection/BitSetLike.scala b/src/library/scala/collection/BitSetLike.scala
index 8476ede7b5..7c5e2fb269 100644
--- a/src/library/scala/collection/BitSetLike.scala
+++ b/src/library/scala/collection/BitSetLike.scala
@@ -21,17 +21,17 @@ import mutable.StringBuilder
  * This trait provides most of the operations of a `BitSet` independently of its representation.
  * It is inherited by all concrete implementations of bitsets.
  *
- * @tparam  This the type of the bitset itself.
+ *  @tparam  This the type of the bitset itself.
  *
+ *  @define bitsetinfo
+ *  Bitsets are sets of non-negative integers which are represented as
+ *  variable-size arrays of bits packed into 64-bit words. The size of a bitset is
+ *  determined by the largest number stored in it.
  *  @author  Martin Odersky
  *  @version 2.8
  *  @since 2.8
  *  @define coll bitset
  *  @define Coll BitSet
- *  @define bitsetinfo
- *  Bitsets are sets of non-negative integers which are represented as
- *  variable-size arrays of bits packed into 64-bit words. The size of a bitset is
- *  determined by the largest number stored in it.
  */
 trait BitSetLike[+This <: BitSetLike[This] with Set[Int]] extends SetLike[Int, This] { self =>
 
diff --git a/src/library/scala/collection/IndexedSeq.scala b/src/library/scala/collection/IndexedSeq.scala
index 50a66e924c..72878a8ad6 100644
--- a/src/library/scala/collection/IndexedSeq.scala
+++ b/src/library/scala/collection/IndexedSeq.scala
@@ -16,10 +16,6 @@ import mutable.Builder
 
 /** A base trait for indexed sequences.
  *  $indexedSeqInfo
- *
- *  @author Martin Odersky
- *  @version 2.8
- *  @since   2.8
  */
 trait IndexedSeq[+A] extends Seq[A]
                     with GenericTraversableTemplate[A, IndexedSeq]
@@ -27,6 +23,10 @@ trait IndexedSeq[+A] extends Seq[A]
   override def companion: GenericCompanion[IndexedSeq] = IndexedSeq
 }
 
+/** $factoryInfo
+ *  @define coll indexed sequence
+ *  @define Coll IndexedSeq
+ */
 object IndexedSeq extends SeqFactory[IndexedSeq] {
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, IndexedSeq[A]] = new GenericCanBuildFrom[A]
   def newBuilder[A]: Builder[A, IndexedSeq[A]] = immutable.IndexedSeq.newBuilder[A]
diff --git a/src/library/scala/collection/IndexedSeqLike.scala b/src/library/scala/collection/IndexedSeqLike.scala
index ea6e1bb493..453b4384f7 100644
--- a/src/library/scala/collection/IndexedSeqLike.scala
+++ b/src/library/scala/collection/IndexedSeqLike.scala
@@ -23,21 +23,20 @@ import scala.annotation.tailrec
  *  However, see `IndexedSeqOptimized` for an implementation trait that overrides operations
  *  to make them run faster under the assumption of fast random access with `apply`.
  *
- *  @author Sean McDirmid
- *  @author Martin Odersky
- *  @version 2.8
- *  @since   2.8
  *  @define  Coll  IndexedSeq
  *  @define indexedSeqInfo
  *  Indexed sequences support constant-time or near constant-time element
  *  access and length computation. They are defined in terms of abstract methods
- *  `apply` fpor indexing and `length`.
+ *  `apply` for indexing and `length`.
  *
  *  Indexed sequences do not add any new methods wrt `Seq`, but promise
  *  efficient implementations of random access patterns.
  *
  *  @tparam A    the element type of the $coll
  *  @tparam Repr the type of the actual $coll containing the elements.
+ *  @author Martin Odersky
+ *  @version 2.8
+ *  @since   2.8
  *  @define willNotTerminateInf
  *  @define mayNotTerminateInf
  */
diff --git a/src/library/scala/collection/IndexedSeqOptimized.scala b/src/library/scala/collection/IndexedSeqOptimized.scala
index 12b39c8b83..9702297a57 100755
--- a/src/library/scala/collection/IndexedSeqOptimized.scala
+++ b/src/library/scala/collection/IndexedSeqOptimized.scala
@@ -19,12 +19,7 @@ import scala.annotation.tailrec
  *  the implementation of several methods under the assumption of fast random access.
  *
  *  $indexedSeqInfo
- *  @author Martin Odersky
- *  @version 2.8
- *  @since   2.8
  *
- *  @tparam A    the element type of the $coll
- *  @tparam Repr the type of the actual $coll containing the elements.
  *  @define willNotTerminateInf
  *  @define mayNotTerminateInf
  */
diff --git a/src/library/scala/collection/Iterable.scala b/src/library/scala/collection/Iterable.scala
index ba5eb4c0a0..65d4dfcbe2 100644
--- a/src/library/scala/collection/Iterable.scala
+++ b/src/library/scala/collection/Iterable.scala
@@ -15,7 +15,8 @@ import generic._
 import scala.util.control.Breaks._
 import mutable.Builder
 
-/** $iterableInfo
+/** A base trait for iterable collections.
+ *  $iterableInfo
  */
 trait Iterable[+A] extends Traversable[A]
                       with GenericTraversableTemplate[A, Iterable]
@@ -35,6 +36,8 @@ trait Iterable[+A] extends Traversable[A]
 }
 
 /** $factoryInfo
+ *  @define coll iterable collection
+ *  @define Coll Iterable
  */
 object Iterable extends TraversableFactory[Iterable] {
 
diff --git a/src/library/scala/collection/IterableLike.scala b/src/library/scala/collection/IterableLike.scala
index e348ba12e5..0efc756b10 100644
--- a/src/library/scala/collection/IterableLike.scala
+++ b/src/library/scala/collection/IterableLike.scala
@@ -15,10 +15,8 @@ import annotation.unchecked.uncheckedVariance
 
 /** A template trait for iterable collections of type `Iterable[A]`.
  *  $iterableInfo
- *  @tparam A    the element type of the collection
- *  @tparam Repr the type of the actual collection containing the elements.
  *  @define iterableInfo
- *    This is a base trait for all scala collections that define an `iterator`
+ *    This is a base trait for all $mutability Scala collections that define an `iterator`
  *    method to step through one-by-one the collection's elements.
  *    Implementations of this trait need to provide a concrete method with
  *    signature:
@@ -44,6 +42,8 @@ import annotation.unchecked.uncheckedVariance
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   2.8
+ *  @tparam A    the element type of the collection
+ *  @tparam Repr the type of the actual collection containing the elements.
  *
  *  @define Coll Iterable
  *  @define coll iterable collection
diff --git a/src/library/scala/collection/IterableViewLike.scala b/src/library/scala/collection/IterableViewLike.scala
index 09f084d92c..b8f0b65faf 100644
--- a/src/library/scala/collection/IterableViewLike.scala
+++ b/src/library/scala/collection/IterableViewLike.scala
@@ -15,11 +15,19 @@ import generic._
 import collection.immutable.Stream
 import TraversableView.NoBuilder
 
-/** A template trait for a non-strict view of an iterable.
+/** A template trait for non-strict views of iterable collections.
+ *  $iterableviewInfo
+ *
+ *  @define iterableviewInfo
+ *  $viewinfo
+ *  All views for iterable collections are defined by creating a new `iterator` method.
  *
  *  @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 IterableViewLike[+A,
                        +Coll,
diff --git a/src/library/scala/collection/LinearSeq.scala b/src/library/scala/collection/LinearSeq.scala
index 1afb2fdb7f..ef7d4c9390 100644
--- a/src/library/scala/collection/LinearSeq.scala
+++ b/src/library/scala/collection/LinearSeq.scala
@@ -16,9 +16,6 @@ import mutable.Builder
 
 /** A base trait for linear sequences.
  *  $linearSeqInfo
- *
- *  @author  Martin Odersky
- *  @since   2.8
  */
 trait LinearSeq[+A] extends Seq[A]
                             with GenericTraversableTemplate[A, LinearSeq]
@@ -26,8 +23,9 @@ trait LinearSeq[+A] extends Seq[A]
   override def companion: GenericCompanion[LinearSeq] = LinearSeq
 }
 
-/**
- *  @since 2.8
+/** $factoryInfo
+ *  @define coll linear sequence
+ *  @define Coll 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/LinearSeqLike.scala b/src/library/scala/collection/LinearSeqLike.scala
index 1c99d4a3d9..208cbcdd50 100644
--- a/src/library/scala/collection/LinearSeqLike.scala
+++ b/src/library/scala/collection/LinearSeqLike.scala
@@ -25,10 +25,6 @@ import scala.util.control.Breaks._
  *  However, see `LinearSeqOptimized` for an implementation trait that overrides operations
  *  to make them run faster under the assumption of fast linear access with `head` and `tail`.
  *
- *  @author  Martin Odersky
- *  @version 2.8
- *  @since   2.8
- *
  *  @define  linearSeqInfo
  *  Linear sequences are defined in terms of three abstract methods, which are assumed
  *  to have efficient implementations. These are:
@@ -41,6 +37,9 @@ import scala.util.control.Breaks._
  *
  *  Linear sequences do not add any new methods to `Seq`, but promise efficient implementations
  *  of linear access patterns.
+ *  @author  Martin Odersky
+ *  @version 2.8
+ *  @since   2.8
  *
  *  @tparam A    the element type of the $coll
  *  @tparam Repr the type of the actual $coll containing the elements.
diff --git a/src/library/scala/collection/Seq.scala b/src/library/scala/collection/Seq.scala
index 1fac25d00d..baf2c0031e 100644
--- a/src/library/scala/collection/Seq.scala
+++ b/src/library/scala/collection/Seq.scala
@@ -16,7 +16,6 @@ import mutable.Builder
 
 /** A base trait for sequences.
  *  $seqInfo
- *  @tparam A    the element type of the $coll
  */
 trait Seq[+A] extends PartialFunction[Int, A]
                       with Iterable[A]
@@ -25,7 +24,10 @@ trait Seq[+A] extends PartialFunction[Int, A]
   override def companion: GenericCompanion[Seq] = Seq
 }
 
-/** $factoryInfo */
+/** $factoryInfo
+ *  @define coll sequence
+ *  @define Coll Seq
+ */
 object Seq extends SeqFactory[Seq] {
 
   private[collection] val hashSeed = "Seq".hashCode
diff --git a/src/library/scala/collection/SeqLike.scala b/src/library/scala/collection/SeqLike.scala
index c35039c520..b9ac28cb2d 100644
--- a/src/library/scala/collection/SeqLike.scala
+++ b/src/library/scala/collection/SeqLike.scala
@@ -99,13 +99,9 @@ object SeqLike {
     }
 }
 
-/** A template trait for sequences of type `Seq[A]`, representing
- *  sequences of elements of type <code>A</code>.
+/** A template trait for sequences of type `Seq[A]`
  *  $seqInfo
  *
- *  @tparam A    the element type of the collection
- *  @tparam Repr the type of the actual collection containing the elements.
- *
  *  @define seqInfo
  *  Sequences are special cases of iterable collections of class `Iterable`.
  *  Unlike iterables, sequences always have a defined order of elements.
@@ -121,11 +117,14 @@ object SeqLike {
  *  Sequences can be accessed in reverse order of their elements, using methods
  *  `reverse` and `reverseIterator`.
  *
- *  Sequences have two principle subtraits, `IndexedSeq` and `LinearSeq`, which give different guarantees for performance.
+ *  Sequences have two principal subtraits, `IndexedSeq` and `LinearSeq`, which give different guarantees for performance.
  *  An `IndexedSeq` provides fast random-access of elements and a fast `length` operation.
  *  A `LinearSeq` provides fast access only to the first element via `head`, but also
  *  has a fast `tail` operation.
  *
+ *  @tparam A    the element type of the collection
+ *  @tparam Repr the type of the actual collection containing the elements.
+ *
  *  @author  Martin Odersky
  *  @author  Matthias Zenger
  *  @version 1.0, 16/07/2003
diff --git a/src/library/scala/collection/Traversable.scala b/src/library/scala/collection/Traversable.scala
index 1cecec5227..4a1cd01af1 100644
--- a/src/library/scala/collection/Traversable.scala
+++ b/src/library/scala/collection/Traversable.scala
@@ -15,10 +15,8 @@ import generic._
 import mutable.{Builder, Buffer, ArrayBuffer, ListBuffer}
 import scala.util.control.Breaks
 
-/** A template trait for traversable collections.
- *  $traversableinfo
- *
- *  @tparam A    The element type of the collection
+/** A trait for traversable collections.
+ *  $traversableInfo
  */
 trait Traversable[+A] extends TraversableLike[A, Traversable[A]]
                          with GenericTraversableTemplate[A, Traversable] {
@@ -84,7 +82,8 @@ trait Traversable[+A] extends TraversableLike[A, Traversable[A]]
   */
 }
 
-/** $factoryInfo */
+/** $factoryInfo
+ */
 object Traversable extends TraversableFactory[Traversable] { self =>
 
   /** Provides break functionality separate from client code */
diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index c5db41005e..4c8d34622e 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -17,18 +17,15 @@ import mutable.{Builder, StringBuilder, Buffer, ArrayBuffer, ListBuffer}
 import immutable.{List, Stream, Nil, ::}
 
 /** A template trait for traversable collections of type `Traversable[A]`.
- *  $traversableinfo
- *
- *  @tparam A    the element type of the collection
- *  @tparam Repr the type of the actual collection containing the elements.
- *
- *  @define traversableinfo
- *  This is a base trait of all kinds of Scala collections. It implements
+ *  $traversableInfo
+ *  @define mutability
+ *  @define traversableInfo
+ *  This is a base trait of all kinds of $mutability Scala collections. It implements
  *  the behavior common to all collections, in terms of a method
  *  `foreach` with signature:
- *  {{{
- *     def foreach[U](f: Elem => U): Unit</pre>
- *  }}}
+ * {{{
+ *     def foreach[U](f: Elem => U): Unit
+ * }}}
  *  Collection classes mixing in this trait provide a concrete
  *  `foreach` method which traverses all the
  *  elements contained in the collection, applying a given function to each.
@@ -63,7 +60,9 @@ import immutable.{List, Stream, Nil, ::}
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   2.8
-
+ *  @tparam A    the element type of the collection
+ *  @tparam Repr the type of the actual collection containing the elements.
+ *
  *  @define Coll Traversable
  *  @define coll traversable collection
  *  @define thatinfo the class of the returned collection. Where possible, `That` is
@@ -178,10 +177,10 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr] with Traversable
    *  @return       a new $coll which contains all elements of this $coll
    *                followed by all elements of `that`.
    */
-  def ++[B >: A, That](xs: TraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = {
+  def ++[B >: A, That](that: TraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = {
     val b = bf(repr)
     b ++= thisCollection
-    b ++= xs
+    b ++= that
     b.result
   }
 
diff --git a/src/library/scala/collection/TraversableOnce.scala b/src/library/scala/collection/TraversableOnce.scala
index ad3a8c6198..54efa62ef3 100644
--- a/src/library/scala/collection/TraversableOnce.scala
+++ b/src/library/scala/collection/TraversableOnce.scala
@@ -10,8 +10,8 @@ package scala.collection
 
 import mutable.{ Buffer, ListBuffer, ArrayBuffer }
 
-/** A template trait for collections which can be traversed one
- *  or more times.
+/** A template trait for collections which can be traversed either once only
+ *  or one or more times.
  *  $traversableonceinfo
  *
  *  @tparam A    the element type of the collection
diff --git a/src/library/scala/collection/TraversableView.scala b/src/library/scala/collection/TraversableView.scala
index e9332097e7..ccc33a495d 100644
--- a/src/library/scala/collection/TraversableView.scala
+++ b/src/library/scala/collection/TraversableView.scala
@@ -15,15 +15,7 @@ import generic._
 import mutable.Builder
 import TraversableView.NoBuilder
 
-/** <p>
- *    A base class for views of <a href="../Traversable.html"
- *    target="ContentFrame"><code>Traversable<code></a>.<br/>
- *    Every subclass has to implement the <code>foreach</code> method.
- *  </p>
- *
- *  @author Martin Odersky
- *  @version 2.8
- *  @since   2.8
+/** $traversableviewinfo
  */
 trait TraversableView[+A, +Coll] extends TraversableViewLike[A, Coll, TraversableView[A, Coll]]
 
diff --git a/src/library/scala/collection/TraversableViewLike.scala b/src/library/scala/collection/TraversableViewLike.scala
index 09e6a65158..96fc55497d 100644
--- a/src/library/scala/collection/TraversableViewLike.scala
+++ b/src/library/scala/collection/TraversableViewLike.scala
@@ -15,20 +15,32 @@ import generic._
 import mutable.{Builder, ArrayBuffer}
 import TraversableView.NoBuilder
 
-/** <p>
- *    A template trait for views of <a href="../Traversable.html"
- *    target="contentFrame"><code>Traversable</code></a>.<br/>
- *    Every subclass has to implement the <code>foreach</code> method.
- *  </p>
- *  @note Methods such as map/flatMap on this will not invoke the implicitly passed
- *        Builder factory, but will return a new view directly, to preserve by-name behavior.
- *        The new view is then cast to the factory's result type.
- *        This means that every CanBuildFrom that takes a
- *        View as its From type parameter must yield the same view (or a generic superclass of it)
- *        as its result parameter. If that assumption is broken, cast errors might result.
+/** A template trait for non-strict views of traversable collections.
+ *  $traversableviewinfo
  *
+ *  Implementation note: Methods such as `map` or `flatMap` on this view will not invoke the implicitly passed
+ *  `Builder` factory, but will return a new view directly, to preserve by-name behavior.
+ *  The new view is then cast to the factory's result type. This means that every `CanBuildFrom`
+ *  that takes a `View` as its `From` type parameter must yield the same view (or a generic
+ *  superclass of it) as its result parameter. If that assumption is broken, cast errors might result.
+ *
+ * @define viewinfo
+ *  A view is a lazy version of some collection. Collection transformers such as
+ *  `map` or `filter` or `++` do not traverse any elements when applied on a view.
+ *  Instead they create a new view which simply records that fact that the operation
+ *  needs to be applied. The collection elements are accessed, and the view operations are applied,
+ *  when a non-view result is needed, or when the `force` method is called on a view.
+ * @define traversableviewinfo
+ *  $viewinfo
+ *
+ *  All views for traversable collections are defined by creating a new `foreach` method.
+
  *  @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 TraversableViewLike[+A,
                           +Coll,
diff --git a/src/library/scala/collection/immutable/IndexedSeq.scala b/src/library/scala/collection/immutable/IndexedSeq.scala
index 3f29052808..268bd56a85 100644
--- a/src/library/scala/collection/immutable/IndexedSeq.scala
+++ b/src/library/scala/collection/immutable/IndexedSeq.scala
@@ -15,10 +15,8 @@ import generic._
 import mutable.{ArrayBuffer, Builder}
 
 /** A subtrait of <code>collection.IndexedSeq</code> which represents indexed sequences
- *  that cannot be mutated.
+ *  that are guaranteed immutable.
  *  $indexedSeqInfo
- *
- *  @since 2.8
  */
 trait IndexedSeq[+A] extends Seq[A]
                     with scala.collection.IndexedSeq[A]
@@ -27,8 +25,9 @@ trait IndexedSeq[+A] extends Seq[A]
   override def companion: GenericCompanion[IndexedSeq] = IndexedSeq
 }
 
-/**
- * @since 2.8
+/** $factoryInfo
+ *  @define coll indexed sequence
+ *  @define Coll IndexedSeq
  */
 object IndexedSeq extends SeqFactory[IndexedSeq] {
   @serializable
diff --git a/src/library/scala/collection/immutable/Iterable.scala b/src/library/scala/collection/immutable/Iterable.scala
index 77e16a6509..795fc2fa92 100644
--- a/src/library/scala/collection/immutable/Iterable.scala
+++ b/src/library/scala/collection/immutable/Iterable.scala
@@ -15,13 +15,8 @@ package immutable
 import generic._
 import mutable.Builder
 
-/** A subtrait of scala.collection.Iterable which represents iterables
- *  that cannot be mutated.
- *
- *  @author  Matthias Zenger
- *  @author   Martin Odersky
- *  @version 2.8
- *  @since   2.8
+/** A base trait for iterable collections that are guaranteed immutable.
+ *  $iterableInfo
  */
 trait Iterable[+A] extends Traversable[A]
                       with scala.collection.Iterable[A]
diff --git a/src/library/scala/collection/immutable/LinearSeq.scala b/src/library/scala/collection/immutable/LinearSeq.scala
index 016afd4508..9cb35dced5 100644
--- a/src/library/scala/collection/immutable/LinearSeq.scala
+++ b/src/library/scala/collection/immutable/LinearSeq.scala
@@ -15,10 +15,9 @@ package immutable
 import generic._
 import mutable.Builder
 
-/** A subtrait of <code>collection.LinearSeq</code> which represents sequences
- *  that cannot be mutated.
+/** A subtrait of <code>collection.LinearSeq</code> which represents sequences that
+ *  are guaranteed immutable.
  *  $linearSeqInfo
- *  @since 2.8
  */
 trait LinearSeq[+A] extends Seq[A]
                             with scala.collection.LinearSeq[A]
@@ -27,8 +26,9 @@ trait LinearSeq[+A] extends Seq[A]
   override def companion: GenericCompanion[LinearSeq] = LinearSeq
 }
 
-/**
- * @since 2.8
+/** $factoryInfo
+ *  @define coll linear sequence
+ *  @define Coll 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/Seq.scala b/src/library/scala/collection/immutable/Seq.scala
index a3059000e8..de7804a95c 100644
--- a/src/library/scala/collection/immutable/Seq.scala
+++ b/src/library/scala/collection/immutable/Seq.scala
@@ -16,9 +16,9 @@ import generic._
 import mutable.Builder
 
 /** A subtrait of `collection.Seq` which represents sequences
- *  that cannot be mutated.
+ *  that are guaranteed immutable.
  *
- *  @since 2.8
+ *  $seqInfo
  */
 trait Seq[+A] extends Iterable[A]
                       with scala.collection.Seq[A]
diff --git a/src/library/scala/collection/immutable/Traversable.scala b/src/library/scala/collection/immutable/Traversable.scala
index b0934ece85..af7f6979c9 100644
--- a/src/library/scala/collection/immutable/Traversable.scala
+++ b/src/library/scala/collection/immutable/Traversable.scala
@@ -15,13 +15,9 @@ package immutable
 import generic._
 import mutable.Builder
 
-/** A subtrait of <code>collection.Traversable</code> which represents
- *  traversables that cannot be mutated.
- *
- *  @author  Matthias Zenger
- *  @author  Martin Odersky
- *  @version 2.8
- *  @since   2.8
+/** A trait for traversable collections that are guaranteed immutable.
+ *  $traversableInfo
+ *  @define mutability immutable
  */
 trait Traversable[+A] extends scala.collection.Traversable[A]
                          with GenericTraversableTemplate[A, Traversable]
diff --git a/src/library/scala/collection/mutable/Iterable.scala b/src/library/scala/collection/mutable/Iterable.scala
index 347ee3c8ac..e2d0707a1c 100644
--- a/src/library/scala/collection/mutable/Iterable.scala
+++ b/src/library/scala/collection/mutable/Iterable.scala
@@ -10,15 +10,8 @@ package mutable
 
 import generic._
 
-/** <p>
- *    A subtrait of <a href="../Iterable.html" target="contentFrame">
- *    <code>collection.Iterable</code></a> which represents iterables
- *    that can be mutated.
- *  </p>
- *
- *  @author   Martin Odersky
- *  @version 2.8
- *  @since   2.8
+/** A base trait for iterable collections that can be mutated.
+ *  $iterableInfo
  */
 trait Iterable[A] extends Traversable[A]
                      with scala.collection.Iterable[A]
diff --git a/src/library/scala/collection/mutable/Traversable.scala b/src/library/scala/collection/mutable/Traversable.scala
index bdbcb9d97e..89c8868314 100644
--- a/src/library/scala/collection/mutable/Traversable.scala
+++ b/src/library/scala/collection/mutable/Traversable.scala
@@ -14,12 +14,9 @@ package mutable
 
 import generic._
 
-/** A subtrait of <code>collection.Traversable</code> which represents
- *  traversables that can be mutated.
- *
- *  @author  Martin Odersky
- *  @version 2.8
- *  @since   2.8
+/** A trait for traversable collections that can be mutated.
+ *  $traversableInfo
+ *  @define mutability mutable
  */
 trait Traversable[A] extends scala.collection.Traversable[A]
                         with GenericTraversableTemplate[A, Traversable]