Merged revisions 21396,21401-21439,21441-21448,...

Merged revisions 21396,21401-21439,21441-21448,21450-21453,21455-21456,21459 via svnmerge from https://lampsvn.epfl.ch/svn-repos/scala/scala/trunk ........ r21396 | rytz | 2010-04-09 11:51:00 +0200 (Fri, 09 Apr 2010) | 1 line close #3207. review by odersky ........ r21401 | rytz | 2010-04-09 14:05:11 +0200 (Fri, 09 Apr 2010) | 1 line minor cleanup in build script. no review ........ r21402 | prokopec | 2010-04-09 14:25:37 +0200 (Fri, 09 Apr 2010) | 1 line Changes to docs of collections in the `immutable` package. Review by odersky. ........ r21403 | dragos | 2010-04-09 17:41:19 +0200 (Fri, 09 Apr 2010) | 1 line Implemented specialized subclassing for traits ........ r21404 | dragos | 2010-04-09 17:41:51 +0200 (Fri, 09 Apr 2010) | 2 lines More information on type skolems when browsing trees and logged normalized member. ........ r21405 | dragos | 2010-04-09 17:41:59 +0200 (Fri, 09 Apr 2010) | 1 line Special-cased 'isHigherKinded' for ThisTypes, in order to get around a CircularReference error. Reviewed by martin ........ r21406 | dragos | 2010-04-09 17:42:08 +0200 (Fri, 09 Apr 2010) | 1 line Made 'specialized' a printable flag. No review. ........ r21407 | dragos | 2010-04-09 17:42:16 +0200 (Fri, 09 Apr 2010) | 3 lines Fixed a cyclic error when specializing Option. Improved the term transformer to transitively rewrite specialized calls. ........ r21408 | dragos | 2010-04-09 17:42:24 +0200 (Fri, 09 Apr 2010) | 7 lines Companion objects of primitive types are now values. Term 'scala.Int' resolves in bytecode to an instance of 'scala.runtime.Int'. This is the first step towards replacing strings in @specialized with a proper list of types, so instead of @specialized("Int, Float") one will write @specialized(Int, Float). Review by odersky. ........ r21409 | dragos | 2010-04-09 17:42:34 +0200 (Fri, 09 Apr 2010) | 5 lines Changed the syntax of the specialized annotation: instead of a flaky string, it now takes a repeated parameter list of primitive types: @specialized("Int, Double") becomes @specialized(Int, Double). No review. ........ r21410 | dragos | 2010-04-09 17:42:53 +0200 (Fri, 09 Apr 2010) | 1 line New starr for primitive companion objects ........ r21411 | dragos | 2010-04-09 17:43:10 +0200 (Fri, 09 Apr 2010) | 3 lines Fixed retyping of singleton types, replacing invalid symbols by their updated symbols, as was done for type refs. ........ r21412 | dragos | 2010-04-09 17:43:18 +0200 (Fri, 09 Apr 2010) | 3 lines Changed default of 'keepsTypeParams' to true. All phases that may change type parameters have to explicitly override this method. ........ r21413 | dragos | 2010-04-09 17:43:27 +0200 (Fri, 09 Apr 2010) | 5 lines Changed TreeSymSubstituter from a traverser to transformer. It now aligns tree nodes that contain names to the symbol name that was substituted. Before this change identifiers may refer to one symbol, while the name they carry would resovlve to another one. ........ r21414 | dragos | 2010-04-09 17:43:35 +0200 (Fri, 09 Apr 2010) | 1 line Less logging unless '-Ydebug', refactorings. ........ r21415 | dragos | 2010-04-09 17:43:44 +0200 (Fri, 09 Apr 2010) | 4 lines Added a cast for alias replacement that caused code to be untypable. The optimization that replaced an overriding param field with its super field now downcasts when they don't have the same type. ........ r21416 | dragos | 2010-04-09 17:43:52 +0200 (Fri, 09 Apr 2010) | 3 lines Brought back stack traces in TypeError. This is essential when debugging any transformer. Review by extempore. ........ r21417 | dragos | 2010-04-09 17:44:03 +0200 (Fri, 09 Apr 2010) | 1 line New starr with the latest fixes to specialization. ........ r21418 | odersky | 2010-04-09 17:56:35 +0200 (Fri, 09 Apr 2010) | 1 line Fixed problem in scaladoc which did not expand variables in top-level classes. ........ r21419 | dragos | 2010-04-09 18:15:45 +0200 (Fri, 09 Apr 2010) | 1 line Fixed weird character that made its way while fixing merge conflicts. Sorry 'bout that. No review. ........ r21420 | odersky | 2010-04-09 18:22:02 +0200 (Fri, 09 Apr 2010) | 1 line Interrupted attempt to fix #2897. I am committing what I have because the refactorings improve things a little bit. To fix the ticket a frightening lot more has to be done. ........ r21421 | odersky | 2010-04-09 18:22:40 +0200 (Fri, 09 Apr 2010) | 1 line @inlined auxiliary typed methods to reduce stack pressure. ........ r21422 | dragos | 2010-04-09 19:10:33 +0200 (Fri, 09 Apr 2010) | 1 line Turn on specialization by default. No review. ........ r21423 | dubochet | 2010-04-09 19:17:47 +0200 (Fri, 09 Apr 2010) | 1 line [scaladoc] FIxed issue with wiki parser that prevented parsing of code blocks. Review by pedrofurla. ........ r21424 | prokopec | 2010-04-09 19:22:58 +0200 (Fri, 09 Apr 2010) | 1 line Work on mutable collections docs. Review by odersky. ........ r21425 | odersky | 2010-04-09 19:25:34 +0200 (Fri, 09 Apr 2010) | 1 line Updated documentation ........ r21426 | odersky | 2010-04-09 19:28:31 +0200 (Fri, 09 Apr 2010) | 1 line more docs ........ r21427 | odersky | 2010-04-09 19:29:00 +0200 (Fri, 09 Apr 2010) | 1 line fixed one more issue that prevented variables in companion objects to be expanded. ........ r21428 | dragos | 2010-04-09 19:36:33 +0200 (Fri, 09 Apr 2010) | 1 line Turn on specialization by default. No review. ........ r21429 | prokopec | 2010-04-09 19:41:15 +0200 (Fri, 09 Apr 2010) | 1 line MultiMap and WeakHashMap docs. no review ........ r21430 | extempore | 2010-04-09 21:07:40 +0200 (Fri, 09 Apr 2010) | 1 line Some tweaks to process to see if it'll fix auxjvm. No review. ........ r21431 | extempore | 2010-04-09 21:26:39 +0200 (Fri, 09 Apr 2010) | 1 line Fix test with new specialized output, no review. ........ r21432 | prokopec | 2010-04-09 23:00:41 +0200 (Fri, 09 Apr 2010) | 1 line Docs for MultiMap done. Review by community.p ........ r21433 | prokopec | 2010-04-10 00:09:47 +0200 (Sat, 10 Apr 2010) | 1 line Docs. No review. ........ r21434 | prokopec | 2010-04-10 14:39:48 +0200 (Sat, 10 Apr 2010) | 1 line docs. no review ........ r21435 | prokopec | 2010-04-10 17:20:46 +0200 (Sat, 10 Apr 2010) | 1 line More docs. No review. ........ r21436 | plocinic | 2010-04-10 22:56:07 +0200 (Sat, 10 Apr 2010) | 1 line Fix windows build. In partest we use UNIX file separators to verify the results. No review. ........ r21437 | prokopec | 2010-04-10 23:29:20 +0200 (Sat, 10 Apr 2010) | 1 line Docs. No review. ........ r21438 | extempore | 2010-04-11 02:32:00 +0200 (Sun, 11 Apr 2010) | 14 lines Introduces scala.tools.cmd providing command line tool infrastructure. For a quick look at what can be done, see scala.tools.cmd.Demo For a more involved, potentially eye-straining look, see scala.tools.partest.PartestSpec To experience it through the eyes of Joe Partest User, run test/partest Review by community. ........ r21439 | extempore | 2010-04-11 02:32:20 +0200 (Sun, 11 Apr 2010) | 6 lines Restores the passing of scalac.args and javac.args from ant to partest for use on all tests, which rytz had astutely pointed out I made disappear. Long term I think one ought to be able to specify different arguments for building the compiler and for partest, but now is not the moment for such grand ambition. No review. ........ r21441 | extempore | 2010-04-11 07:58:32 +0200 (Sun, 11 Apr 2010) | 2 lines Temporarily reverted r21421 so the build will build again and hopefully the auxjvm nightly will run. Review by odersky. ........ r21442 | extempore | 2010-04-11 17:45:08 +0200 (Sun, 11 Apr 2010) | 1 line Some overdue cleanups on Exception. Review by community. ........ r21443 | ilyas | 2010-04-11 17:56:55 +0200 (Sun, 11 Apr 2010) | 1 line ScalaSigPrinter fixed for multiline string values in annotations ........ r21444 | dubochet | 2010-04-11 18:28:16 +0200 (Sun, 11 Apr 2010) | 1 line [scaladoc] Refactors Paul's refactorings from r21353 to fit Scaladoc's design. No review. ........ r21445 | dubochet | 2010-04-11 18:28:39 +0200 (Sun, 11 Apr 2010) | 1 line [scaladoc] UI tweak: definition classes list is separated by a different arrow. No review. ........ r21446 | phaller | 2010-04-11 18:30:56 +0200 (Sun, 11 Apr 2010) | 1 line Completed scaladoc for Reactor and Combinators. ........ r21447 | dubochet | 2010-04-11 18:38:58 +0200 (Sun, 11 Apr 2010) | 1 line [scaladoc] Fixes efficiency issue in the way pages are generated. This issue can lead to the same page being generated a very large number of times and probably explains why building Scaladoc had been so slow previously. Donna helped identifying the issue, review by malayeri. ........ r21448 | phaller | 2010-04-11 19:43:54 +0200 (Sun, 11 Apr 2010) | 1 line Scaladoc clean-ups for various actor and channel types. Actor now extends InputChannel. Channel now extends CanReply. Review by plocinic. ........ r21450 | phaller | 2010-04-11 20:09:46 +0200 (Sun, 11 Apr 2010) | 1 line Made use of random number generator in ForkJoinScheduler's fair mode thread safe. Review by plocinic. ........ r21451 | dragos | 2010-04-11 20:51:45 +0200 (Sun, 11 Apr 2010) | 1 line Fixed some position issues and build manager test. No review. ........ r21452 | rytz | 2010-04-11 21:11:40 +0200 (Sun, 11 Apr 2010) | 1 line moved plugin folder back to 'misc/scala-devel/plugins'. moved bash completion to scala-tool-support (see r21449). include continuations in compiler sbaz package. replaced some tabs by spaces. review by extempore. ........ r21453 | extempore | 2010-04-11 21:45:08 +0200 (Sun, 11 Apr 2010) | 16 lines Added --update-check option to partest. Now you can automatically update all the checkfiles with whatever output the tests are producing. I suppose it goes without saying that this would be easy to misuse, so let the record show that I accept no responsibility when someone overwrites all the checkfiles in trunk with their shopping list and checks it in. Recommended usage: See some tests fail. Run partest --failed --show-diff Verify that all output differs in the expected fashion. Then run partest --failed --update-check Mission accomplished. No review. ........ r21455 | extempore | 2010-04-12 00:24:21 +0200 (Mon, 12 Apr 2010) | 2 lines Reverting r21442 the Exception patch because I think it is the cause of the deadlocking. Not my greatest weekend. No review. ........ r21456 | extempore | 2010-04-12 05:30:26 +0200 (Mon, 12 Apr 2010) | 1 line Disabled the test which is hanging the -optimise run. No review. ........ r21459 | extempore | 2010-04-12 08:46:53 +0200 (Mon, 12 Apr 2010) | 1 line Disabling some more tests which crash under -optimise. No review. ........
author: Antonio Cunei <antonio.cunei@epfl.ch> 2010-04-12 07:44:39 +0000
committer: Antonio Cunei <antonio.cunei@epfl.ch> 2010-04-12 07:44:39 +0000
commit: f31eaf606f2f1f524621dacd280abfccb9110f59 (patch)
tree: cb7aa7c227e526571a74b92b6b9471032dce4ba5 /src/library
parent: 8ff235f9491a4a90969b494a32c1f55c69e2e0a8 (diff)
download: scala-f31eaf606f2f1f524621dacd280abfccb9110f59.tar.gz
scala-f31eaf606f2f1f524621dacd280abfccb9110f59.tar.bz2
scala-f31eaf606f2f1f524621dacd280abfccb9110f59.zip
115 files changed, 1131 insertions, 549 deletions
diff --git a/src/library/scala/Function1.scala b/src/library/scala/Function1.scala
index 75110d7d4e..afc19417a2 100644
--- a/src/library/scala/Function1.scala
+++ b/src/library/scala/Function1.scala
@@ -35,7 +35,7 @@ package scala
  *    println(anonfun1(0))
  *  }</pre>
  */
-trait Function1[-T1, +R] extends AnyRef { self =>
+trait Function1[@specialized(Int, Long, Double) -T1, @specialized(Unit, Int, Long, Double) +R] extends AnyRef { self =>
   def apply(v1:T1): R
   override def toString() = "<function1>"
 
diff --git a/src/library/scala/Function2.scala b/src/library/scala/Function2.scala
index 99c4ed1d2a..46023a9b3b 100644
--- a/src/library/scala/Function2.scala
+++ b/src/library/scala/Function2.scala
@@ -35,7 +35,9 @@ package scala
  *    println(anonfun2(0, 1))
  *  }</pre>
  */
-trait Function2[-T1, -T2, +R] extends AnyRef { self =>
+trait Function2[@specialized(Int, Long, Double) -T1,
+                @specialized(Int, Long, Double) -T2,
+                @specialized(Unit, Int, Long, Double) +R] extends AnyRef { self =>
   def apply(v1:T1,v2:T2): R
   override def toString() = "<function2>"
 
diff --git a/src/library/scala/Product1.scala b/src/library/scala/Product1.scala
index 2cca5fe7d5..0e93065e5a 100644
--- a/src/library/scala/Product1.scala
+++ b/src/library/scala/Product1.scala
@@ -22,7 +22,7 @@ object Product1 {
  *
  *  @since 2.3
  */
-trait Product1[+T1] extends Product {
+trait Product1[@specialized(Int, Long, Double) +T1] extends Product {
   /**
    *  The arity of this product.
    *  @return 1
diff --git a/src/library/scala/Product2.scala b/src/library/scala/Product2.scala
index 27580f8658..436de41a01 100644
--- a/src/library/scala/Product2.scala
+++ b/src/library/scala/Product2.scala
@@ -22,7 +22,8 @@ object Product2 {
  *
  *  @since 2.3
  */
-trait Product2[+T1, +T2] extends Product {
+trait Product2[@specialized(Int, Long, Double) +T1,
+               @specialized(Int, Long, Double) +T2] extends Product {
   /**
    *  The arity of this product.
    *  @return 2
diff --git a/src/library/scala/Tuple1.scala b/src/library/scala/Tuple1.scala
index d57c58fe78..5d25cc5abb 100644
--- a/src/library/scala/Tuple1.scala
+++ b/src/library/scala/Tuple1.scala
@@ -17,7 +17,7 @@ package scala
 /** Tuple1 is the canonical representation of a @see Product1
  *
  */
-case class Tuple1[+T1](_1:T1)
+case class Tuple1[@specialized(Int, Long, Double) +T1](_1:T1)
   extends Product1[T1]
 {
   override def toString() = "(" + _1 + ")"
diff --git a/src/library/scala/Tuple2.scala b/src/library/scala/Tuple2.scala
index 8c4e5973c5..7fea22410d 100644
--- a/src/library/scala/Tuple2.scala
+++ b/src/library/scala/Tuple2.scala
@@ -19,7 +19,8 @@ import scala.collection.generic.CanBuildFrom
 /** Tuple2 is the canonical representation of a @see Product2
  *
  */
-case class Tuple2[+T1, +T2](_1:T1,_2:T2)
+case class Tuple2[@specialized(Int, Long, Double) +T1,
+                  @specialized(Int, Long, Double) +T2](_1:T1,_2:T2)
   extends Product2[T1, T2]
 {
   override def toString() = "(" + _1 + "," + _2 + ")"
diff --git a/src/library/scala/collection/BitSet.scala b/src/library/scala/collection/BitSet.scala
index abb4856bcd..b43b681888 100644
--- a/src/library/scala/collection/BitSet.scala
+++ b/src/library/scala/collection/BitSet.scala
@@ -15,17 +15,16 @@ import generic._
 
 /** A common base class for mutable and immutable bitsets.
  *  $bitsetinfo
-
- *  @author Martin Odersky
- *  @version 2.8
- *  @since 1
  */
 trait BitSet extends Set[Int]
                 with BitSetLike[BitSet] {
   override def empty: BitSet = BitSet.empty
 }
 
-/** $factoryInfo */
+/** $factoryInfo
+ *  @define coll bitset
+ *  @define Coll BitSet
+ */
 object BitSet extends BitSetFactory[BitSet] {
   val empty: BitSet = immutable.BitSet.empty
   /** $canBuildFromInfo */
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/LinearSeqOptimized.scala b/src/library/scala/collection/LinearSeqOptimized.scala
index 7d3c58ad85..2add28d7c3 100755
--- a/src/library/scala/collection/LinearSeqOptimized.scala
+++ b/src/library/scala/collection/LinearSeqOptimized.scala
@@ -20,12 +20,6 @@ import scala.util.control.Breaks._
  *  the implementation of several methods under the assumption of fast linear access.
  *
  *  $linearSeqInfo
- *  @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.
  */
 trait LinearSeqOptimized[+A, +Repr <: LinearSeqOptimized[A, Repr]] extends LinearSeqLike[A, Repr] { self: Repr =>
 
diff --git a/src/library/scala/collection/MapLike.scala b/src/library/scala/collection/MapLike.scala
index 6a9fffe3e1..057224a705 100644
--- a/src/library/scala/collection/MapLike.scala
+++ b/src/library/scala/collection/MapLike.scala
@@ -233,13 +233,10 @@ self =>
   }
 
   /** Transforms this map by applying a function to every retrieved value.
-   *  @param  d   the function used to transform values of this map.
-   *  @return an immutable map which maps every key of this map
+   *  @param  f   the function used to transform values of this map.
+   *  @return a map view which maps every key of this map
    *          to `f(this(key))`. The resulting map wraps the original map without copying any elements.
    */
-  /** A map view resulting from applying a given function `f` to each value
-   *  associated with a key in this map.
-   */
   def mapValues[C](f: B => C): Map[A, C] = new DefaultMap[A, C] {
     override def foreach[D](g: ((A, C)) => D): Unit = for ((k, v) <- self) g((k, f(v)))
     def iterator = for ((k, v) <- self.iterator) yield (k, f(v))
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/SeqView.scala b/src/library/scala/collection/SeqView.scala
index 79d50f1de6..9a0025bd81 100644
--- a/src/library/scala/collection/SeqView.scala
+++ b/src/library/scala/collection/SeqView.scala
@@ -22,6 +22,8 @@ import TraversableView.NoBuilder
 trait SeqView[+A, +Coll] extends SeqViewLike[A, Coll, SeqView[A, Coll]]
 
 /** $factoryInfo
+ *  @define coll sequence view
+ *  @define Coll SeqView
  */
 object SeqView {
   type Coll = TraversableView[_, C] forSome {type C <: Traversable[_]}
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/generic/BitSetFactory.scala b/src/library/scala/collection/generic/BitSetFactory.scala
index cd26dc14b5..5679b25351 100644
--- a/src/library/scala/collection/generic/BitSetFactory.scala
+++ b/src/library/scala/collection/generic/BitSetFactory.scala
@@ -15,8 +15,17 @@ package generic
 import scala.collection._
 import mutable.{Builder, AddingBuilder}
 
-/**
- * @since 2.8
+/** @define coll collection
+ *  @define Coll Traversable
+ *  @define factoryInfo
+ *    This object provides a set of operations to create `$Coll` values.
+ *    @author Martin Odersky
+ *    @version 2.8
+ *  @define canBuildFromInfo
+ *    The standard `CanBuildFrom` instance for $Coll objects.
+ *    @see CanBuildFrom
+ *  @define bitsetCanBuildFrom
+ *    The standard `CanBuildFrom` instance for bitsets.
  */
 trait BitSetFactory[Coll <: BitSet with BitSetLike[Coll]] {
   def newBuilder: Builder[Int, Coll] = new AddingBuilder[Int, Coll](empty)
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/generic/TraversableFactory.scala b/src/library/scala/collection/generic/TraversableFactory.scala
index c2668b48a2..b7fda70922 100644
--- a/src/library/scala/collection/generic/TraversableFactory.scala
+++ b/src/library/scala/collection/generic/TraversableFactory.scala
@@ -17,8 +17,8 @@ package generic
  *
  *  @since 2.8
  *
- *  @define $coll collection
- *  @define @Coll Traversable
+ *  @define coll collection
+ *  @define Coll Traversable
  *  @define factoryInfo
  *    This object provides a set of operations to create `$Coll` values.
  *    @author Martin Odersky
diff --git a/src/library/scala/collection/immutable/BitSet.scala b/src/library/scala/collection/immutable/BitSet.scala
index e06218ff92..857b537904 100644
--- a/src/library/scala/collection/immutable/BitSet.scala
+++ b/src/library/scala/collection/immutable/BitSet.scala
@@ -15,12 +15,8 @@ package immutable
 import generic._
 import BitSetLike.{LogWL, updateArray}
 
-/** A base class for immutable bit sets.
+/** A class for immutable bitsets.
  *  $bitsetinfo
- *
- *  @author Martin Odersky
- *  @version 2.8
- *  @since 1
  */
 @serializable @SerialVersionUID(1611436763290191562L)
 abstract class BitSet extends Set[Int]
diff --git a/src/library/scala/collection/immutable/DefaultMap.scala b/src/library/scala/collection/immutable/DefaultMap.scala
index 7ee8197150..a19b35aff0 100755
--- a/src/library/scala/collection/immutable/DefaultMap.scala
+++ b/src/library/scala/collection/immutable/DefaultMap.scala
@@ -19,7 +19,8 @@ import generic._
  *    methods of maps.<br/>
  *    Instances that inherit from <code>DefaultMap[A, B]</code> still have to
  *    define:
- *  </p><pre>
+ *  </p>
+ *  <pre>
  *    <b>def</b> get(key: A): Option[B]
  *    <b>def</b> iterator: Iterator[(A, B)]</pre>
  *  <p>
diff --git a/src/library/scala/collection/immutable/HashSet.scala b/src/library/scala/collection/immutable/HashSet.scala
index 16d4473de1..e79b456a2f 100644
--- a/src/library/scala/collection/immutable/HashSet.scala
+++ b/src/library/scala/collection/immutable/HashSet.scala
@@ -15,12 +15,11 @@ package immutable
 import generic._
 import annotation.unchecked.uncheckedVariance
 
-/** <p>
- *    This class implements immutable sets using a hash trie.
- *  </p>
+/**
+ *  This class implements immutable sets using a hash trie.
  *
- * @note the builder of a hash set returns specialized representations EmptySet,Set1,..., Set4
- * for sets of size <= 4.
+ * @note the builder of a hash set returns specialized representations `EmptySet`,`Set1`,..., `Set4`
+ * for sets of `size <= 4`.
  *
  *  @author  Martin Odersky
  *  @author  Tiark Rompf
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/IntMap.scala b/src/library/scala/collection/immutable/IntMap.scala
index 62309a9f48..75a25e0223 100644
--- a/src/library/scala/collection/immutable/IntMap.scala
+++ b/src/library/scala/collection/immutable/IntMap.scala
@@ -167,6 +167,8 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
 
   /**
    * Iterator over key, value pairs of the map in unsigned order of the keys.
+   *
+   * @return an iterator over pairs of integer keys and corresponding values.
    */
   def iterator : Iterator[(Int, T)] = this match {
     case IntMap.Nil => Iterator.empty;
@@ -278,15 +280,20 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
 
   /**
    * Updates the map, using the provided function to resolve conflicts if the key is already present.
-   * Equivalent to
-   * <pre>this.get(key) match {
-   *         case None => this.update(key, value);
-   *         case Some(oldvalue) => this.update(key, f(oldvalue, value) }
-   * </pre>
    *
-   * @param key The key to update
-   * @param value The value to use if there is no conflict
-   * @param f The function used to resolve conflicts.
+   * Equivalent to:
+   * {{{
+   *   this.get(key) match {
+   *     case None => this.update(key, value);
+   *     case Some(oldvalue) => this.update(key, f(oldvalue, value)
+   *   }
+   * }}}
+   *
+   * @tparam S     The supertype of values in this `LongMap`.
+   * @param key    The key to update
+   * @param value  The value to use if there is no conflict
+   * @param f      The function used to resolve conflicts.
+   * @return       The updated map.
    */
   def updateWith[S >: T](key : Int, value : S, f : (T, S) => S) : IntMap[S] = this match {
     case IntMap.Bin(prefix, mask, left, right) => if (!hasMatch(key, prefix, mask)) join(key, IntMap.Tip(key, value), prefix, this);
@@ -312,7 +319,9 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
    * A combined transform and filter function. Returns an IntMap such that for each (key, value) mapping
    * in this map, if f(key, value) == None the map contains no mapping for key, and if <code>f(key, value)
    *
-   * @param f The transforming function.
+   * @tparam S  The type of the values in the resulting `LongMap`.
+   * @param f   The transforming function.
+   * @return    The modified map.
    */
   def modifyOrRemove[S](f : (Int, T) => Option[S]) : IntMap[S] = this match {
       case IntMap.Bin(prefix, mask, left, right) => {
@@ -335,8 +344,10 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
   /**
    * Forms a union map with that map, using the combining function to resolve conflicts.
    *
-   * @param that the map to form a union with.
-   * @param f the function used to resolve conflicts between two mappings.
+   * @tparam S      The type of values in `that`, a supertype of values in `this`.
+   * @param that    The map to form a union with.
+   * @param f       The function used to resolve conflicts between two mappings.
+   * @return        Union of `this` and `that`, with identical key conflicts resolved using the function `f`.
    */
   def unionWith[S >: T](that : IntMap[S], f : (Int, S, S) => S) : IntMap[S] = (this, that) match{
     case (IntMap.Bin(p1, m1, l1, r1), that@(IntMap.Bin(p2, m2, l2, r2))) =>
@@ -364,8 +375,11 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
    * a map that has only keys present in both maps and has values produced from the original mappings
    * by combining them with f.
    *
-   * @param that The map to intersect with.
-   * @param f The combining function.
+   * @tparam S      The type of values in `that`.
+   * @tparam R      The type of values in the resulting `LongMap`.
+   * @param that    The map to intersect with.
+   * @param f       The combining function.
+   * @return        Intersection of `this` and `that`, with values for identical keys produced by function `f`.
    */
   def intersectionWith[S, R](that : IntMap[S], f : (Int, T, S) => R) : IntMap[R] = (this, that) match {
     case (IntMap.Bin(p1, m1, l1, r1), that@IntMap.Bin(p2, m2, l2, r2)) =>
@@ -394,7 +408,9 @@ sealed abstract class IntMap[+T] extends Map[Int, T] with MapLike[Int, T, IntMap
    * Left biased intersection. Returns the map that has all the same mappings as this but only for keys
    * which are present in the other map.
    *
-   * @param that The map to intersect with.
+   * @tparam R      The type of values in `that`.
+   * @param that    The map to intersect with.
+   * @return        A map with all the keys both in `this` and `that`, mapped to corresponding values from `this`.
    */
   def intersection[R](that : IntMap[R]) : IntMap[T] = this.intersectionWith(that, (key : Int, value : T, value2 : R) => value);
 
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/List.scala b/src/library/scala/collection/immutable/List.scala
index 2b91ab8852..4ce441ca55 100644
--- a/src/library/scala/collection/immutable/List.scala
+++ b/src/library/scala/collection/immutable/List.scala
@@ -433,7 +433,10 @@ final case class ::[B](private var hd: B, private[scala] var tl: List[B]) extend
   }
 }
 
-/** $factoryInfo */
+/** $factoryInfo
+ *  @define coll list
+ *  @define Coll List
+ */
 object List extends SeqFactory[List] {
 
   import scala.collection.{Iterable, Seq, IndexedSeq}
diff --git a/src/library/scala/collection/immutable/ListMap.scala b/src/library/scala/collection/immutable/ListMap.scala
index d8e3e0856b..4342e54a9d 100644
--- a/src/library/scala/collection/immutable/ListMap.scala
+++ b/src/library/scala/collection/immutable/ListMap.scala
@@ -104,6 +104,8 @@ class ListMap[A, +B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] {
   protected def value: B = throw new NoSuchElementException("empty map")
   protected def next: ListMap[A, B] = throw new NoSuchElementException("empty map")
 
+  /** This class represents an entry in the `ListMap`.
+   */
   @serializable @SerialVersionUID(-6453056603889598734L)
   protected class Node[B1 >: B](override protected val key: A,
                                 override protected val value: B1) extends ListMap[A, B1] {
diff --git a/src/library/scala/collection/immutable/ListSet.scala b/src/library/scala/collection/immutable/ListSet.scala
index 3863c16591..f7b76d2317 100644
--- a/src/library/scala/collection/immutable/ListSet.scala
+++ b/src/library/scala/collection/immutable/ListSet.scala
@@ -85,6 +85,8 @@ class ListSet[A] extends Set[A]
    */
   protected def next: ListSet[A] = throw new NoSuchElementException("Next of an empty set");
 
+  /** Represents an entry in the `ListSet`.
+   */
   @serializable
   protected class Node(override protected val elem: A) extends ListSet[A] {
 
diff --git a/src/library/scala/collection/immutable/LongMap.scala b/src/library/scala/collection/immutable/LongMap.scala
index 0d74e41cec..24afb65b99 100644
--- a/src/library/scala/collection/immutable/LongMap.scala
+++ b/src/library/scala/collection/immutable/LongMap.scala
@@ -153,6 +153,8 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
 
   /**
    * Iterator over key, value pairs of the map in unsigned order of the keys.
+   *
+   * @return an iterator over pairs of long keys and corresponding values.
    */
   def iterator: Iterator[(Long, T)] = this match {
     case LongMap.Nil => Iterator.empty;
@@ -264,15 +266,20 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
 
   /**
    * Updates the map, using the provided function to resolve conflicts if the key is already present.
+   *
    * Equivalent to
-   * <pre>this.get(key) match {
-   *         case None => this.update(key, value);
-   *         case Some(oldvalue) => this.update(key, f(oldvalue, value) }
-   * </pre>
+   * {{{
+   *   this.get(key) match {
+   *     case None => this.update(key, value);
+   *     case Some(oldvalue) => this.update(key, f(oldvalue, value)
+   *   }
+   * }}}
    *
-   * @param key The key to update
-   * @param value The value to use if there is no conflict
-   * @param f The function used to resolve conflicts.
+   * @tparam S     The supertype of values in this `LongMap`.
+   * @param key    The key to update.
+   * @param value  The value to use if there is no conflict.
+   * @param f      The function used to resolve conflicts.
+   * @return       The updated map.
    */
   def updateWith[S >: T](key : Long, value : S, f : (T, S) => S) : LongMap[S] = this match {
     case LongMap.Bin(prefix, mask, left, right) => if (!hasMatch(key, prefix, mask)) join(key, LongMap.Tip(key, value), prefix, this);
@@ -298,7 +305,9 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
    * A combined transform and filter function. Returns an LongMap such that for each (key, value) mapping
    * in this map, if f(key, value) == None the map contains no mapping for key, and if <code>f(key, value)
    *
-   * @param f The transforming function.
+   * @tparam S    The type of the values in the resulting `LongMap`.
+   * @param f     The transforming function.
+   * @return      The modified map.
    */
   def modifyOrRemove[S](f : (Long, T) => Option[S]) : LongMap[S] = this match {
       case LongMap.Bin(prefix, mask, left, right) => {
@@ -321,8 +330,10 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
   /**
    * Forms a union map with that map, using the combining function to resolve conflicts.
    *
-   * @param that the map to form a union with.
-   * @param f the function used to resolve conflicts between two mappings.
+   * @tparam S      The type of values in `that`, a supertype of values in `this`.
+   * @param that    The map to form a union with.
+   * @param f       The function used to resolve conflicts between two mappings.
+   * @return        Union of `this` and `that`, with identical key conflicts resolved using the function `f`.
    */
   def unionWith[S >: T](that : LongMap[S], f : (Long, S, S) => S) : LongMap[S] = (this, that) match{
     case (LongMap.Bin(p1, m1, l1, r1), that@(LongMap.Bin(p2, m2, l2, r2))) =>
@@ -350,8 +361,11 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
    * a map that has only keys present in both maps and has values produced from the original mappings
    * by combining them with f.
    *
-   * @param that The map to intersect with.
-   * @param f The combining function.
+   * @tparam S      The type of values in `that`.
+   * @tparam R      The type of values in the resulting `LongMap`.
+   * @param that    The map to intersect with.
+   * @param f       The combining function.
+   * @return        Intersection of `this` and `that`, with values for identical keys produced by function `f`.
    */
   def intersectionWith[S, R](that : LongMap[S], f : (Long, T, S) => R) : LongMap[R] = (this, that) match {
     case (LongMap.Bin(p1, m1, l1, r1), that@LongMap.Bin(p2, m2, l2, r2)) =>
@@ -380,7 +394,9 @@ sealed abstract class LongMap[+T] extends Map[Long, T] with MapLike[Long, T, Lon
    * Left biased intersection. Returns the map that has all the same mappings as this but only for keys
    * which are present in the other map.
    *
-   * @param that The map to intersect with.
+   * @tparam R      The type of values in `that`.
+   * @param that    The map to intersect with.
+   * @return        A map with all the keys both in `this` and `that`, mapped to corresponding values from `this`.
    */
   def intersection[R](that : LongMap[R]) : LongMap[T] = this.intersectionWith(that, (key : Long, value : T, value2 : R) => value);
 
diff --git a/src/library/scala/collection/immutable/Map.scala b/src/library/scala/collection/immutable/Map.scala
index b5a852683a..e3469099b8 100644
--- a/src/library/scala/collection/immutable/Map.scala
+++ b/src/library/scala/collection/immutable/Map.scala
@@ -15,6 +15,16 @@ package immutable
 import generic._
 
 /**
+ * A generic trait for immutable maps. Concrete classes have to provide
+ * functionality for the abstract methods in `Map`:
+ *
+ * {{{
+ *    def get(key: A): Option[B]
+ *    def iterator: Iterator[(A, B)]
+ *    def + [B1 >: B](kv: (A, B1)): Map[A, B1]
+ *    def -(key: A): Map[A, B]
+ * }}}
+ *
  * @since 1
  */
 trait Map[A, +B] extends Iterable[(A, B)]
@@ -39,6 +49,8 @@ trait Map[A, +B] extends Iterable[(A, B)]
 }
 
 /**
+ * A companion object for immutable maps.
+ *
  * @since 1
  */
 object Map extends ImmutableMapFactory[Map] {
diff --git a/src/library/scala/collection/immutable/MapLike.scala b/src/library/scala/collection/immutable/MapLike.scala
index 662321bb0c..6f816ffa52 100644
--- a/src/library/scala/collection/immutable/MapLike.scala
+++ b/src/library/scala/collection/immutable/MapLike.scala
@@ -91,13 +91,10 @@ trait MapLike[A, +B, +This <: MapLike[A, B, This] with Map[A, B]]
   }
 
   /** Transforms this map by applying a function to every retrieved value.
-   *  @param  d   the function used to transform values of this map.
-   *  @return an immutable map which maps every key of this map
+   *  @param  f   the function used to transform values of this map.
+   *  @return a map view which maps every key of this map
    *          to `f(this(key))`. The resulting map wraps the original map without copying any elements.
    */
-  /** A map view resulting from applying a given function `f` to each value
-   *  associated with a key in this map.
-   */
   override def mapValues[C](f: B => C): Map[A, C] = new DefaultMap[A, C] {
     override def foreach[D](g: ((A, C)) => D): Unit = for ((k, v) <- self) g((k, f(v)))
     def iterator = for ((k, v) <- self.iterator) yield (k, f(v))
diff --git a/src/library/scala/collection/immutable/NumericRange.scala b/src/library/scala/collection/immutable/NumericRange.scala
index d3e4558884..645c5fed24 100644
--- a/src/library/scala/collection/immutable/NumericRange.scala
+++ b/src/library/scala/collection/immutable/NumericRange.scala
@@ -17,12 +17,12 @@ import generic._
 /** <p>
  *    <code>NumericRange</code> is a more generic version of the
  *    <code>Range</code> class which works with arbitrary types.
- *    It must be supplied with an Integral implementation of the
+ *    It must be supplied with an `Integral` implementation of the
  *    range type.
  *
- *    Factories for likely types include Range.BigInt, Range.Long,
- *    and Range.BigDecimal.  Range.Int exists for completeness, but
- *    the Int-based scala.Range should be more performant.
+ *    Factories for likely types include `Range.BigInt`, `Range.Long`,
+ *    and `Range.BigDecimal`.  `Range.Int` exists for completeness, but
+ *    the `Int`-based `scala.Range` should be more performant.
  *  </p><pre>
  *     <b>val</b> r1 = new Range(0, 100, 1)
  *     <b>val</b> veryBig = Int.MaxValue.toLong + 1
diff --git a/src/library/scala/collection/immutable/Range.scala b/src/library/scala/collection/immutable/Range.scala
index 43b11b67be..5424a7afcb 100644
--- a/src/library/scala/collection/immutable/Range.scala
+++ b/src/library/scala/collection/immutable/Range.scala
@@ -32,14 +32,14 @@ class Range(val start: Int, val end: Int, val step: Int) extends IndexedSeq[Int]
 
   protected def copy(start: Int, end: Int, step: Int): Range = new Range(start, end, step)
 
-  /** Create a new range with the start and end values of this range and
+  /** Create a new range with the `start` and `end` values of this range and
    *  a new <code>step</code>.
    */
   def by(step: Int): Range = copy(start, end, step)
 
   def isInclusive = false
 
-  override def foreach[U](f: Int => U) {
+  override def foreach[@specialized(Unit) U](f: Int => U) {
     if (fullLength > 0) {
       val last = this.last
       var i = start
@@ -191,7 +191,7 @@ object Range {
   def inclusive(start: Int, end: Int): Range.Inclusive with ByOne = new Inclusive(start, end, 1) with ByOne
 
   trait ByOne extends Range {
-    override final def foreach[U](f: Int => U) {
+    override final def foreach[@specialized(Unit) U](f: Int => U) {
       if (length > 0) {
         val last = this.last
         var i = start
diff --git a/src/library/scala/collection/immutable/RedBlack.scala b/src/library/scala/collection/immutable/RedBlack.scala
index e7b4f3c978..ffa6194838 100644
--- a/src/library/scala/collection/immutable/RedBlack.scala
+++ b/src/library/scala/collection/immutable/RedBlack.scala
@@ -12,7 +12,7 @@
 package scala.collection
 package immutable
 
-/** An base class containing the implementations for TreeMaps and TreeSets
+/** A base class containing the implementations for TreeMaps and TreeSets
  *
  * @since 2.3
  */
diff --git a/src/library/scala/collection/immutable/Seq.scala b/src/library/scala/collection/immutable/Seq.scala
index 9bd7084675..de7804a95c 100644
--- a/src/library/scala/collection/immutable/Seq.scala
+++ b/src/library/scala/collection/immutable/Seq.scala
@@ -15,10 +15,10 @@ package immutable
 import generic._
 import mutable.Builder
 
-/** A subtrait of collection.Seq which represents sequences
- *  that cannot be mutated.
+/** A subtrait of `collection.Seq` which represents sequences
+ *  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/Set.scala b/src/library/scala/collection/immutable/Set.scala
index 1bec1b9a48..77f16c0d14 100644
--- a/src/library/scala/collection/immutable/Set.scala
+++ b/src/library/scala/collection/immutable/Set.scala
@@ -39,6 +39,9 @@ trait Set[A] extends Iterable[A]
   override def companion: GenericCompanion[Set] = Set
 }
 
+/**
+ * A companion object for immutable sets.
+ */
 object Set extends SetFactory[Set] {
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Set[A]] = setCanBuildFrom[A]
   override def empty[A]: Set[A] = EmptySet.asInstanceOf[Set[A]]
diff --git a/src/library/scala/collection/immutable/SortedSet.scala b/src/library/scala/collection/immutable/SortedSet.scala
index 9d0b1882fa..10ff466ff8 100644
--- a/src/library/scala/collection/immutable/SortedSet.scala
+++ b/src/library/scala/collection/immutable/SortedSet.scala
@@ -15,7 +15,8 @@ package immutable
 import generic._
 import mutable.Builder
 
-/** A sorted set.
+/** A subtrait of `collection.SortedSet` which represents sorted sets
+ *  which cannot be mutated.
  *
  *  @author Sean McDirmid
  *  @author Martin Odersky
@@ -28,6 +29,8 @@ trait SortedSet[A] extends Set[A] with scala.collection.SortedSet[A] with Sorted
 }
 
 /**
+ * A companion object for immutable sorted sets.
+ *
  * @since 2.4
  */
 object SortedSet extends ImmutableSortedSetFactory[SortedSet] {
diff --git a/src/library/scala/collection/immutable/Stack.scala b/src/library/scala/collection/immutable/Stack.scala
index 640fb39af5..7d3c8c040b 100644
--- a/src/library/scala/collection/immutable/Stack.scala
+++ b/src/library/scala/collection/immutable/Stack.scala
@@ -67,8 +67,8 @@ class Stack[+A] protected (protected val elems: List[A]) extends LinearSeq[A]
   def push[B >: A](elem1: B, elem2: B, elems: B*): Stack[B] =
     this.push(elem1).push(elem2).pushAll(elems)
 
-  /** Push all elements provided by the given iterator object onto
-   *  the stack. The last element returned by the iterable object
+  /** Push all elements provided by the given traversable object onto
+   *  the stack. The last element returned by the traversable object
    *  will be on top of the new stack.
    *
    *  @param   elems      the iterator object.
diff --git a/src/library/scala/collection/immutable/StringLike.scala b/src/library/scala/collection/immutable/StringLike.scala
index 5b5a627cfe..8068267dd2 100644
--- a/src/library/scala/collection/immutable/StringLike.scala
+++ b/src/library/scala/collection/immutable/StringLike.scala
@@ -49,7 +49,7 @@ self =>
 
   override def mkString = toString
 
-  /** return n times the current string
+  /** Return the current string concatenated `n` times.
    */
   def * (n: Int): String = {
     val buf = new StringBuilder
@@ -61,18 +61,16 @@ self =>
 
   private def isLineBreak(c: Char) = c == LF || c == FF
 
-  /** <p>
+  /**
    *    Strip trailing line end character from this string if it has one.
+   *
    *    A line end character is one of
-   *  </p>
-   *  <ul style="list-style-type: none;">
-   *    <li>LF - line feed   (0x0A hex)</li>
-   *    <li>FF - form feed   (0x0C hex)</li>
-   *  </ul>
-   *  <p>
+   *    <ul style="list-style-type: none;">
+   *      <li>LF - line feed   (0x0A hex)</li>
+   *      <li>FF - form feed   (0x0C hex)</li>
+   *    </ul>
    *    If a line feed character LF is preceded by a carriage return CR
    *    (0x0D hex), the CR character is also stripped (Windows convention).
-   *  </p>
    */
   def stripLineEnd: String = {
     val len = toString.length
@@ -86,19 +84,18 @@ self =>
     }
   }
 
-  /** <p>
+  /**
    *    Return all lines in this string in an iterator, including trailing
    *    line end characters.
-   *  </p>
-   *  <p>
+   *
    *    The number of strings returned is one greater than the number of line
    *    end characters in this string. For an empty string, a single empty
    *    line is returned. A line end character is one of
-   *  </p>
-   *  <ul style="list-style-type: none;">
-   *    <li>LF - line feed   (0x0A hex)</li>
-   *    <li>FF - form feed   (0x0C hex)</li>
-   *  </ul>
+   *
+   *    <ul style="list-style-type: none;">
+   *      <li>LF - line feed   (0x0A hex)</li>
+   *      <li>FF - form feed   (0x0C hex)</li>
+   *    </ul>
    */
   def linesWithSeparators: Iterator[String] = new Iterator[String] {
     val str = self.toString
@@ -148,13 +145,13 @@ self =>
     if (toString.endsWith(suffix)) toString.substring(0, toString.length() - suffix.length)
     else toString
 
-  /** <p>
+  /**
    *    For every line in this string:
-   *  </p>
-   *  <blockquote>
-   *     Strip a leading prefix consisting of blanks or control characters
-   *     followed by <code>marginChar</code> from the line.
-   *  </blockquote>
+   *
+   *    <blockquote>
+   *       Strip a leading prefix consisting of blanks or control characters
+   *       followed by <code>marginChar</code> from the line.
+   *    </blockquote>
    */
   def stripMargin(marginChar: Char): String = {
     val buf = new StringBuilder
@@ -168,13 +165,13 @@ self =>
     buf.toString
   }
 
-  /** <p>
+  /**
    *    For every line in this string:
-   *  </p>
-   *  <blockquote>
-   *     Strip a leading prefix consisting of blanks or control characters
-   *     followed by <code>|</code> from the line.
-   *  </blockquote>
+   *
+   *    <blockquote>
+   *       Strip a leading prefix consisting of blanks or control characters
+   *       followed by <code>|</code> from the line.
+   *    </blockquote>
    */
   def stripMargin: String = stripMargin('|')
 
@@ -226,19 +223,18 @@ self =>
     case x              => x.asInstanceOf[AnyRef]
   }
 
-  /** <p>
+  /**
    *  Uses the underlying string as a pattern (in a fashion similar to
    *  printf in C), and uses the supplied arguments to fill in the
    *  holes.
-   *  </p>
-   *  <p>
+   *
    *    The interpretation of the formatting patterns is described in
    *    <a href="" target="contentFrame" class="java/util/Formatter">
    *    <code>java.util.Formatter</code></a>, with the addition that
-   *    classes deriving from ScalaNumber (such as scala.BigInt and
-   *    scala.BigDecimal) are unwrapped to pass a type which Formatter
+   *    classes deriving from `ScalaNumber` (such as `scala.BigInt` and
+   *    `scala.BigDecimal`) are unwrapped to pass a type which `Formatter`
    *    understands.
-   *  </p>
+   *
    *
    *  @param args the arguments used to instantiating the pattern.
    *  @throws java.lang.IllegalArgumentException
@@ -246,20 +242,20 @@ self =>
   def format(args : Any*): String =
     java.lang.String.format(toString, args map unwrapArg: _*)
 
-  /** <p>
-   *  Like format(args*) but takes an initial Locale parameter
-   *  which influences formatting as in java.lang.String's format.
-   *  </p>
-   *  <p>
+  /**
+   *  Like `format(args*)` but takes an initial `Locale` parameter
+   *  which influences formatting as in `java.lang.String`'s format.
+   *
+   *
    *    The interpretation of the formatting patterns is described in
    *    <a href="" target="contentFrame" class="java/util/Formatter">
    *    <code>java.util.Formatter</code></a>, with the addition that
-   *    classes deriving from ScalaNumber (such as scala.BigInt and
-   *    scala.BigDecimal) are unwrapped to pass a type which Formatter
+   *    classes deriving from `ScalaNumber` (such as `scala.BigInt` and
+   *    `scala.BigDecimal`) are unwrapped to pass a type which `Formatter`
    *    understands.
-   *  </p>
    *
-   *  @param locale an instance of java.util.Locale
+   *
+   *  @param locale an instance of `java.util.Locale`
    *  @param args the arguments used to instantiating the pattern.
    *  @throws java.lang.IllegalArgumentException
    */
diff --git a/src/library/scala/collection/immutable/StringOps.scala b/src/library/scala/collection/immutable/StringOps.scala
index 95509ab9d6..4949eb7056 100644
--- a/src/library/scala/collection/immutable/StringOps.scala
+++ b/src/library/scala/collection/immutable/StringOps.scala
@@ -15,6 +15,14 @@ package immutable
 import mutable.StringBuilder
 
 /**
+ * This class serves as a wrapper providing `String`s with all the operations
+ * found in indexed sequences. Where needed, instances of `String` object
+ * are implicitly converted into this class.
+ *
+ * The difference between this class and `WrappedString` is that calling transformer
+ * methods such as `filter` and `map` will yield a `String` object, whereas a
+ * `WrappedString` will remain a `WrappedString`.
+ *
  * @since 2.8
  */
 final class StringOps(override val repr: String) extends StringLike[String] {
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/immutable/WrappedString.scala b/src/library/scala/collection/immutable/WrappedString.scala
index e10b3ab0ee..cefbd96b5c 100644
--- a/src/library/scala/collection/immutable/WrappedString.scala
+++ b/src/library/scala/collection/immutable/WrappedString.scala
@@ -17,6 +17,13 @@ import mutable.{Builder, StringBuilder}
 import scala.util.matching.Regex
 
 /**
+ * This class serves as a wrapper augmenting `String`s with all the operations
+ * found in indexed sequences.
+ *
+ * The difference between this class and `StringOps` is that calling transformer
+ * methods such as `filter` and `map` will yield an object of type `WrappedString`
+ * rather than a `String`.
+ *
  * @since 2.8
  */
 class WrappedString(override val self: String) extends IndexedSeq[Char] with StringLike[WrappedString] with Proxy {
diff --git a/src/library/scala/collection/mutable/AddingBuilder.scala b/src/library/scala/collection/mutable/AddingBuilder.scala
index d16a4a71f3..14636c9feb 100644
--- a/src/library/scala/collection/mutable/AddingBuilder.scala
+++ b/src/library/scala/collection/mutable/AddingBuilder.scala
@@ -15,6 +15,7 @@ import generic._
 
 /** The canonical builder for collections that are addable, i.e. that support an efficient `+` method
  *  which adds an element to the collection.
+ *
  *  Collections are built from their empty element using this `+` method.
  *  @param empty  the empty element of the collection.
  *  @tparam Elem  the type of elements that get added to the builder.
diff --git a/src/library/scala/collection/mutable/ArrayBuffer.scala b/src/library/scala/collection/mutable/ArrayBuffer.scala
index 0c6aa9ce0c..bee531221f 100644
--- a/src/library/scala/collection/mutable/ArrayBuffer.scala
+++ b/src/library/scala/collection/mutable/ArrayBuffer.scala
@@ -14,7 +14,7 @@ package mutable
 
 import generic._
 
-/** An implementation of the <code>Buffer</code> class using an array to
+/** An implementation of the `Buffer` class using an array to
  *  represent the assembled sequence internally. Append, update and random
  *  access take constant time (amortized time). Prepends and removes are
  *  linear in the buffer size.
@@ -23,6 +23,22 @@ import generic._
  *  @author  Martin Odersky
  *  @version 2.8
  *  @since   1
+ *
+ *  @tparam A    the type of this arraybuffer's elements.
+ *
+ *  @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, 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`
+ *    and the new element type `B`. This is usually the `canBuildFrom` value
+ *    defined in object `ArrayBuffer`.
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable @SerialVersionUID(1529165946227428979L)
 class ArrayBuffer[A](override protected val initialSize: Int)
@@ -50,9 +66,10 @@ class ArrayBuffer[A](override protected val initialSize: Int)
   }
 
   /** Appends a single element to this buffer and returns
-   *  the identity of the buffer. It takes constant time.
+   *  the identity of the buffer. It takes constant amortized time.
    *
    *  @param elem  the element to append.
+   *  @return      the updated buffer.
    */
   def +=(elem: A): this.type = {
     ensureSize(size0 + 1)
@@ -61,11 +78,10 @@ class ArrayBuffer[A](override protected val initialSize: Int)
     this
   }
 
-  /** Appends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method. The identity of the
-   *  buffer is returned.
+  /** Appends a number of elements provided by a traversable object.
+   *  The identity of the buffer is returned.
    *
-   *  @param iter  the iterable object.
+   *  @param xs    the traversable object.
    *  @return      the updated buffer.
    */
   override def ++=(xs: TraversableOnce[A]): this.type = xs match {
@@ -79,7 +95,7 @@ class ArrayBuffer[A](override protected val initialSize: Int)
       super.++=(xs)
   }
 
-  /** Prepends a single element to this buffer and return
+  /** Prepends a single element to this buffer and returns
    *  the identity of the buffer. It takes time linear in
    *  the buffer size.
    *
@@ -94,22 +110,21 @@ class ArrayBuffer[A](override protected val initialSize: Int)
     this
   }
 
-  /** Prepends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method. The identity of the
-   *  buffer is returned.
+  /** Prepends a number of elements provided by a traversable object.
+   *  The identity of the buffer is returned.
    *
-   *  @param iter  the iterable object.
+   *  @param xs    the traversable object.
    *  @return      the updated buffer.
    */
   override def ++=:(xs: TraversableOnce[A]): this.type = { insertAll(0, xs.toTraversable); this }
 
-  /** Inserts new elements at the index <code>n</code>. Opposed to method
-   *  <code>update</code>, this method will not replace an element with a
-   *  one. Instead, it will insert a new element at index <code>n</code>.
+  /** Inserts new elements at the index `n`. Opposed to method
+   *  `update`, this method will not replace an element with a
+   *  one. Instead, it will insert a new element at index `n`.
    *
    *  @param n     the index where a new element will be inserted.
-   *  @param iter  the iterable object providing all elements to insert.
-   *  @throws Predef.IndexOutOfBoundsException if <code>n</code> is out of bounds.
+   *  @param seq   the traversable object providing all elements to insert.
+   *  @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
    */
   def insertAll(n: Int, seq: Traversable[A]) {
     if (n < 0 || n > size0) throw new IndexOutOfBoundsException(n.toString)
@@ -124,9 +139,9 @@ class ArrayBuffer[A](override protected val initialSize: Int)
   /** Removes the element on a given index position. It takes time linear in
    *  the buffer size.
    *
-   *  @param n  the index which refers to the first element to delete.
+   *  @param n       the index which refers to the first element to delete.
    *  @param count   the number of elements to delete
-   *  @throws Predef.IndexOutOfBoundsException if <code>n</code> is out of bounds.
+   *  @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
    */
   override def remove(n: Int, count: Int) {
     require(count >= 0, "removing negative number of elements")
@@ -135,10 +150,10 @@ class ArrayBuffer[A](override protected val initialSize: Int)
     reduceToSize(size0 - count)
   }
 
-  /** Removes the element on a given index position
+  /** Removes the element at a given index position.
    *
    *  @param n  the index which refers to the element to delete.
-   *  @return  The element that was formerly at position `n`
+   *  @return   the element that was formerly at position `n`.
    */
   def remove(n: Int): A = {
     val result = apply(n)
@@ -148,7 +163,7 @@ class ArrayBuffer[A](override protected val initialSize: Int)
 
   /** Return a clone of this buffer.
    *
-   *  @return an <code>ArrayBuffer</code> with the same elements.
+   *  @return an `ArrayBuffer` with the same elements.
    */
   override def clone(): ArrayBuffer[A] = new ArrayBuffer[A] ++= this
 
@@ -159,13 +174,14 @@ class ArrayBuffer[A](override protected val initialSize: Int)
   override def stringPrefix: String = "ArrayBuffer"
 }
 
-/** Factory object for <code>ArrayBuffer</code> class.
+/** Factory object for the `ArrayBuffer` class.
  *
- *  @author  Martin Odersky
- *  @version 2.8
- *  @since   2.8
+ *  $factoryInfo
+ *  @define coll list
+ *  @define Coll List
  */
 object ArrayBuffer extends SeqFactory[ArrayBuffer] {
+  /** $genericCanBuildFromInfo */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, ArrayBuffer[A]] = new GenericCanBuildFrom[A]
   def newBuilder[A]: Builder[A, ArrayBuffer[A]] = new ArrayBuffer[A]
 }
diff --git a/src/library/scala/collection/mutable/ArrayBuilder.scala b/src/library/scala/collection/mutable/ArrayBuilder.scala
index 7e4bab353b..0ddd089852 100644
--- a/src/library/scala/collection/mutable/ArrayBuilder.scala
+++ b/src/library/scala/collection/mutable/ArrayBuilder.scala
@@ -15,21 +15,33 @@ package mutable
 import generic._
 import scala.reflect.ClassManifest
 
-/** A builder class for arrays
+/** A builder class for arrays.
  *
- * @since 2.8
+ *  @since 2.8
+ *
+ *  @tparam T    the type of the elements for the builder.
  */
 @serializable
 abstract class ArrayBuilder[T] extends Builder[T, Array[T]]
 
-/**
- * @since 2.8
+/** A companion object for array builders.
+ *
+ *  @since 2.8
  */
 object ArrayBuilder {
 
+  /** Creates a new arraybuilder of type `T`.
+   *
+   *  @tparam T     type of the elements for the array builder, with a `ClassManifest` context bound.
+   *  @return       a new empty array builder.
+   */
   def make[T: ClassManifest](): ArrayBuilder[T] =
     implicitly[ClassManifest[T]].newArrayBuilder()
 
+  /** A class for array builders for arrays of reference types.
+   *
+   *  @tparam T     type of elements for the array builder, subtype of `AnyRef` with a `ClassManifest` context bound.
+   */
   class ofRef[T <: AnyRef : ClassManifest] extends ArrayBuilder[T] {
 
     private var elems: Array[T] = _
@@ -94,6 +106,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofRef"
   }
 
+  /** A class for array builders for arrays of `byte`s. */
   class ofByte extends ArrayBuilder[Byte] {
 
     private var elems: Array[Byte] = _
@@ -158,6 +171,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofByte"
   }
 
+  /** A class for array builders for arrays of `short`s. */
   class ofShort extends ArrayBuilder[Short] {
 
     private var elems: Array[Short] = _
@@ -222,6 +236,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofShort"
   }
 
+  /** A class for array builders for arrays of `char`s. */
   class ofChar extends ArrayBuilder[Char] {
 
     private var elems: Array[Char] = _
@@ -286,6 +301,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofChar"
   }
 
+  /** A class for array builders for arrays of `int`s. */
   class ofInt extends ArrayBuilder[Int] {
 
     private var elems: Array[Int] = _
@@ -350,6 +366,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofInt"
   }
 
+  /** A class for array builders for arrays of `long`s. */
   class ofLong extends ArrayBuilder[Long] {
 
     private var elems: Array[Long] = _
@@ -414,6 +431,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofLong"
   }
 
+  /** A class for array builders for arrays of `float`s. */
   class ofFloat extends ArrayBuilder[Float] {
 
     private var elems: Array[Float] = _
@@ -478,6 +496,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofFloat"
   }
 
+  /** A class for array builders for arrays of `double`s. */
   class ofDouble extends ArrayBuilder[Double] {
 
     private var elems: Array[Double] = _
@@ -542,6 +561,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofDouble"
   }
 
+  /** A class for array builders for arrays of `boolean`s. */
   class ofBoolean extends ArrayBuilder[Boolean] {
 
     private var elems: Array[Boolean] = _
@@ -606,6 +626,7 @@ object ArrayBuilder {
     override def toString = "ArrayBuilder.ofBoolean"
   }
 
+  /** A class for array builders for arrays of `Unit` type. */
   class ofUnit extends ArrayBuilder[Unit] {
 
     private var elems: Array[Unit] = _
diff --git a/src/library/scala/collection/mutable/ArrayLike.scala b/src/library/scala/collection/mutable/ArrayLike.scala
index 0b64f1255e..b3bd0fbe25 100644
--- a/src/library/scala/collection/mutable/ArrayLike.scala
+++ b/src/library/scala/collection/mutable/ArrayLike.scala
@@ -13,21 +13,31 @@ package scala.collection
 package mutable
 import generic._
 
-/** A subtrait of collection.IndexedSeq which represents sequences
+/** A subtrait of `collection.IndexedSeq` which represents sequences
  *  that can be mutated.
  *
  *  @since 2.8
+ *
+ *  @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
  */
 trait ArrayLike[A, +Repr] extends IndexedSeqOptimized[A, Repr] { self =>
 
-  /** Creates a possible nested IndexedSeq which consists of all the elements
-   *  of this array. If the elements are arrays themselves, the `deep' transformation
-   *  is applied recursively to them. The stringPrefix of the IndexedSeq is
-   *  "Array", hence the IndexedSeq prints like an array with all its
+  /** Creates a possible nested `IndexedSeq` which consists of all the elements
+   *  of this array. If the elements are arrays themselves, the `deep` transformation
+   *  is applied recursively to them. The `stringPrefix` of the `IndexedSeq` is
+   *  "Array", hence the `IndexedSeq` prints like an array with all its
    *  elements shown, and the same recursively for any subarrays.
    *
-   *  Example:   Array(Array(1, 2), Array(3, 4)).deep.toString
-   *  prints:    Array(Array(1, 2), Array(3, 4))
+   *  Example:
+   *  {{{
+   *  Array(Array(1, 2), Array(3, 4)).deep.toString
+   *  }}}
+   *  prints: `Array(Array(1, 2), Array(3, 4))`
+   *
+   *  @return    An possibly nested indexed sequence of consisting of all the elements of the array.
    */
   def deep: scala.collection.IndexedSeq[Any] = new scala.collection.IndexedSeq[Any] {
     def length = self.length
diff --git a/src/library/scala/collection/mutable/ArrayOps.scala b/src/library/scala/collection/mutable/ArrayOps.scala
index 553461c805..971709ed67 100644
--- a/src/library/scala/collection/mutable/ArrayOps.scala
+++ b/src/library/scala/collection/mutable/ArrayOps.scala
@@ -14,8 +14,23 @@ package mutable
 
 import scala.reflect.ClassManifest
 
-/**
- * @since 2.8
+/** This class serves as a wrapper for `Array`s with all the operations found in
+ *  indexed sequences. Where needed, instances of arrays are implicitly converted
+ *  into this class.
+ *
+ *  The difference between this class and `WrappedArray` is that calling transformer
+ *  methods such as `filter` and `map` will yield an array, whereas a `WrappedArray`
+ *  will remain a `WrappedArray`.
+ *
+ *  @since 2.8
+ *
+ *  @tparam T   type of the elements contained in this array.
+ *
+ *  @define Coll ArrayOps
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 abstract class ArrayOps[T] extends ArrayLike[T, Array[T]] {
 
@@ -31,7 +46,11 @@ abstract class ArrayOps[T] extends ArrayLike[T, Array[T]] {
       super.toArray[U]
 
   /** Flattens a two-dimensional array by concatenating all its rows
-   *  into a single array
+   *  into a single array.
+   *
+   *  @tparam U        Type of row elements.
+   *  @param asArray   A function that converts elements of this array to rows - arrays of type `U`.
+   *  @return          An array obtained by concatenating rows of this array.
    */
   def flatten[U](implicit asArray: T => /*<:<!!!*/ Array[U]): Array[U] = {
     val b = rowBuilder[U]
@@ -40,7 +59,11 @@ abstract class ArrayOps[T] extends ArrayLike[T, Array[T]] {
     b.result
   }
 
-  /** Transposes a two dimensional array
+  /** Transposes a two dimensional array.
+   *
+   *  @tparam U       Type of row elements.
+   *  @param asArray  A function that converts elements of this array to rows - arrays of type `U`.
+   *  @return         An array obtained by replacing elements of this arrays with rows the represent.
    */
   def transpose[U](implicit asArray: T => Array[U]): Array[Array[U]] = {
     val bs = asArray(head) map (_ => rowBuilder[U])
@@ -60,10 +83,13 @@ abstract class ArrayOps[T] extends ArrayLike[T, Array[T]] {
 }
 
 /**
+ * A companion object for `ArrayOps`.
+ *
  * @since 2.8
  */
 object ArrayOps {
 
+  /** A class of `ArrayOps` for arrays containing reference types. */
   class ofRef[T <: AnyRef](override val repr: Array[T]) extends ArrayOps[T] with ArrayLike[T, Array[T]] {
 
     override protected[this] def thisCollection: WrappedArray[T] = new WrappedArray.ofRef[T](repr)
@@ -76,6 +102,7 @@ object ArrayOps {
     def update(index: Int, elem: T) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays containing `byte`s. */
   class ofByte(override val repr: Array[Byte]) extends ArrayOps[Byte] with ArrayLike[Byte, Array[Byte]] {
 
     override protected[this] def thisCollection: WrappedArray[Byte] = new WrappedArray.ofByte(repr)
@@ -87,6 +114,7 @@ object ArrayOps {
     def update(index: Int, elem: Byte) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays containing `short`s. */
   class ofShort(override val repr: Array[Short]) extends ArrayOps[Short] with ArrayLike[Short, Array[Short]] {
 
     override protected[this] def thisCollection: WrappedArray[Short] = new WrappedArray.ofShort(repr)
@@ -98,6 +126,7 @@ object ArrayOps {
     def update(index: Int, elem: Short) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays containing `char`s. */
   class ofChar(override val repr: Array[Char]) extends ArrayOps[Char] with ArrayLike[Char, Array[Char]] {
 
     override protected[this] def thisCollection: WrappedArray[Char] = new WrappedArray.ofChar(repr)
@@ -109,6 +138,7 @@ object ArrayOps {
     def update(index: Int, elem: Char) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays containing `int`s. */
   class ofInt(override val repr: Array[Int]) extends ArrayOps[Int] with ArrayLike[Int, Array[Int]] {
 
     override protected[this] def thisCollection: WrappedArray[Int] = new WrappedArray.ofInt(repr)
@@ -120,6 +150,7 @@ object ArrayOps {
     def update(index: Int, elem: Int) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays containing `long`s. */
   class ofLong(override val repr: Array[Long]) extends ArrayOps[Long] with ArrayLike[Long, Array[Long]] {
 
     override protected[this] def thisCollection: WrappedArray[Long] = new WrappedArray.ofLong(repr)
@@ -131,6 +162,7 @@ object ArrayOps {
     def update(index: Int, elem: Long) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays containing `float`s. */
   class ofFloat(override val repr: Array[Float]) extends ArrayOps[Float] with ArrayLike[Float, Array[Float]] {
 
     override protected[this] def thisCollection: WrappedArray[Float] = new WrappedArray.ofFloat(repr)
@@ -142,6 +174,7 @@ object ArrayOps {
     def update(index: Int, elem: Float) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays containing `double`s. */
   class ofDouble(override val repr: Array[Double]) extends ArrayOps[Double] with ArrayLike[Double, Array[Double]] {
 
     override protected[this] def thisCollection: WrappedArray[Double] = new WrappedArray.ofDouble(repr)
@@ -153,6 +186,7 @@ object ArrayOps {
     def update(index: Int, elem: Double) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays containing `boolean`s. */
   class ofBoolean(override val repr: Array[Boolean]) extends ArrayOps[Boolean] with ArrayLike[Boolean, Array[Boolean]] {
 
     override protected[this] def thisCollection: WrappedArray[Boolean] = new WrappedArray.ofBoolean(repr)
@@ -164,6 +198,7 @@ object ArrayOps {
     def update(index: Int, elem: Boolean) { repr(index) = elem }
   }
 
+  /** A class of `ArrayOps` for arrays of `Unit` types. */
   class ofUnit(override val repr: Array[Unit]) extends ArrayOps[Unit] with ArrayLike[Unit, Array[Unit]] {
 
     override protected[this] def thisCollection: WrappedArray[Unit] = new WrappedArray.ofUnit(repr)
diff --git a/src/library/scala/collection/mutable/ArraySeq.scala b/src/library/scala/collection/mutable/ArraySeq.scala
index f6f958601d..d59cf684b2 100644
--- a/src/library/scala/collection/mutable/ArraySeq.scala
+++ b/src/library/scala/collection/mutable/ArraySeq.scala
@@ -21,6 +21,23 @@ import generic._
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   2.8
+ *
+ *  @tparam A      type of the elements contained in this array sequence.
+ *  @param length  the length of the underlying array.
+ *
+ *  @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, 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`
+ *    and the new element type `B`. This is usually the `canBuildFrom` value
+ *    defined in object `ArraySeq`.
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 class ArraySeq[A](override val length: Int)
 extends IndexedSeq[A]
@@ -49,7 +66,7 @@ extends IndexedSeq[A]
     }
   }
 
-  /** Fills the given array <code>xs</code> with at most `len` elements of
+  /** Fills the given array `xs` with at most `len` elements of
    *  this traversable starting at position `start`.
    *  Copying will stop once either the end of the current traversable is reached or
    *  `len` elements have been copied or the end of the array is reached.
@@ -64,7 +81,12 @@ extends IndexedSeq[A]
    }
 }
 
+/** $factoryInfo
+ *  @define coll array sequence
+ *  @define Coll ArraySeq
+ */
 object ArraySeq extends SeqFactory[ArraySeq] {
+  /** $genericCanBuildFromInfo */
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, ArraySeq[A]] = new GenericCanBuildFrom[A]
   def newBuilder[A]: Builder[A, ArraySeq[A]] =
     new ArrayBuffer[A] mapResult { buf =>
diff --git a/src/library/scala/collection/mutable/ArrayStack.scala b/src/library/scala/collection/mutable/ArrayStack.scala
index 8f9d1bfc88..0c6dc7a0e1 100644
--- a/src/library/scala/collection/mutable/ArrayStack.scala
+++ b/src/library/scala/collection/mutable/ArrayStack.scala
@@ -28,12 +28,20 @@ private object Utils {
   }
 }
 
-/**
- * Simple stack class backed by an array. Should be significantly faster
- * than the standard mutable stack.
+/** Simple stack class backed by an array. Should be significantly faster
+ *  than the standard mutable stack.
  *
- * @author David MacIver
- * @since  2.7
+ *  @author David MacIver
+ *  @since  2.7
+ *
+ *  @tparam T    type of the elements contained in this array stack.
+ *
+ *  @define Coll ArrayStack
+ *  @define coll array stack
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @cloneable @serializable @SerialVersionUID(8565219180626620510L)
 class ArrayStack[T] private(private var table : Array[AnyRef],
@@ -47,10 +55,9 @@ class ArrayStack[T] private(private var table : Array[AnyRef],
   /** The number of elements in the stack */
   def length = index
 
-  /**
-   * Push an element onto the stack.
+  /** Push an element onto the stack.
    *
-   * @param x The element to push
+   *  @param x The element to push
    */
   def push(x: T) {
     if (index == table.length) table = Utils.growArray(table)
@@ -58,8 +65,9 @@ class ArrayStack[T] private(private var table : Array[AnyRef],
     index += 1
   }
 
-  /**
-   * Pop the top element off the stack.
+  /** Pop the top element off the stack.
+   *
+   *  @return the element on top of the stack
    */
   def pop: T = {
     if (index == 0) error("Stack empty")
@@ -73,68 +81,73 @@ class ArrayStack[T] private(private var table : Array[AnyRef],
   @deprecated("use top instead")
   def peek = top
 
-  /**
-   * View the top element of the stack.
+  /** View the top element of the stack.
+   *
+   *  Does not remove the element on the top. If the stack is empty,
+   *  an exception is thrown.
+   *
+   *  @return the element on top of the stack.
    */
   def top: T = table(index - 1).asInstanceOf[T]
 
-  /**
-   * Duplicate the top element of the stack.
+  /** Duplicate the top element of the stack.
+   *
+   *  After calling this method, the stack will have an additional element at
+   *  the top equal to the element that was previously at the top.
+   *  If the stack is empty, an exception is thrown.
    */
   def dup = push(top)
 
-  /**
-   * Empties the stack.
-   */
+  /** Empties the stack. */
   def clear {
     index = 0
     table = new Array(1)
   }
 
-  /**
-   * Empties the stack, passing all elements on it in FIFO order to the
-   * provided function.
+  /** Empties the stack, passing all elements on it in LIFO order to the
+   *  provided function.
    *
-   * @param f The function to drain to.
+   *  @param f The function to drain to.
    */
   def drain(f: T => Unit) = while (!isEmpty) f(pop)
 
-  /**
-   * Pushes all the provided elements onto the stack.
+  /** Pushes all the provided elements in the traversable object onto the stack.
    *
-   * @param x The source of elements to push
+   *  @param x  The source of elements to push.
+   *  @return   A reference to this stack.
    */
   def ++=(xs: TraversableOnce[T]): this.type = { xs foreach += ; this }
 
-  /**
-   *  Alias for push.
+  /** Does the same as `push`, but returns the updated stack.
    *
-   *  @param x The element to push
+   *  @param x  The element to push.
+   *  @return   A reference to this stack.
    */
   def +=(x: T): this.type = { push(x); this }
 
-  /**
-   * Pop the top two elements off the stack, apply f to them and push the result
-   * back on to the stack.
+  /** Pop the top two elements off the stack, apply `f` to them and push the result
+   *  back on to the stack.
    *
-   * @param f The combining function
+   *  This function will throw an exception if stack contains fewer than 2 elements.
+   *
+   *  @param f   The function to apply to the top two elements.
    */
-  def combine(f: (T, T) => T) = push(f(pop, pop));
+  def combine(f: (T, T) => T): Unit = push(f(pop, pop))
 
-  /**
-   * Repeatedly combine the top elements of the stack until the stack contains only
-   * one element.
+  /** Repeatedly combine the top elements of the stack until the stack contains only
+   *  one element.
+   *
+   *  @param f   The function to apply repeatedly to topmost elements.
    */
-  def reduceWith(f: (T, T) => T) = while(size > 1) combine(f)
+  def reduceWith(f: (T, T) => T): Unit = while(size > 1) combine(f)
 
   override def size = index
 
-  /**
-   * Evaluates the expression, preserving the contents of the stack so that
-   * any changes the evaluation makes to the stack contents will be undone after
-   * it completes.
+  /** Evaluates the expression, preserving the contents of the stack so that
+   *  any changes the evaluation makes to the stack contents will be undone after
+   *  it completes.
    *
-   * @param action The action to run.
+   *  @param action The action to run.
    */
   def preserving[T](action: => T) = {
     val oldIndex = index
@@ -150,8 +163,8 @@ class ArrayStack[T] private(private var table : Array[AnyRef],
 
   override def isEmpty: Boolean = index == 0
 
-  /**
-   * Iterates over the stack in LIFO order.
+  /** Creates and iterator over the stack in LIFO order.
+   *  @return an iterator over the elements of the stack.
    */
   def iterator: Iterator[T] = new Iterator[T] {
     var currentIndex = index
diff --git a/src/library/scala/collection/mutable/BitSet.scala b/src/library/scala/collection/mutable/BitSet.scala
index 92dad18956..5d0f5863ca 100644
--- a/src/library/scala/collection/mutable/BitSet.scala
+++ b/src/library/scala/collection/mutable/BitSet.scala
@@ -16,11 +16,22 @@ import generic._
 import BitSetLike.{LogWL, updateArray}
 
 /** A class for mutable bitsets.
+ *
  *  $bitsetinfo
  *
- *  @author Martin Odersky
- *  @version 2.8
- *  @since 1
+ *  @define Coll BitSet
+ *  @define coll bitset
+ *  @define thatinfo the class of the returned collection. In the standard library configuration,
+ *    `That` is always `BitSet[B]` because an implicit of type `CanBuildFrom[BitSet, B, BitSet]`
+ *    is defined in object `BitSet`.
+ *  @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 `BitSet`.
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable @SerialVersionUID(8483111450368547763L)
 class BitSet(protected var elems: Array[Long]) extends Set[Int]
@@ -30,6 +41,10 @@ class BitSet(protected var elems: Array[Long]) extends Set[Int]
 
   override def empty = BitSet.empty
 
+  /** Creates the bitset of a certain initial size.
+   *
+   *  @param initSize    initial size of the bitset.
+   */
   def this(initSize: Int) = this(new Array[Long]((initSize + 63) >> 6 max 1))
 
   def this() = this(0)
@@ -79,7 +94,10 @@ class BitSet(protected var elems: Array[Long]) extends Set[Int]
 
   /** Wraps this bitset as an immutable bitset backed by the array of bits
    *  of this bitset.
+   *
    *  @note Subsequent changes in this bitset will be reflected in the returned immutable bitset.
+   *
+   *  @return an immutable set containing all the elements of this set.
    */
   def toImmutable = immutable.BitSet.fromArray(elems)
 
@@ -90,8 +108,12 @@ class BitSet(protected var elems: Array[Long]) extends Set[Int]
   }
 }
 
+/** $factoryInfo
+ *  @define coll bitset
+ *  @define Coll BitSet
+ */
 object BitSet extends BitSetFactory[BitSet] {
   def empty: BitSet = new BitSet
-  /** $canBuildFromInfo */
+  /** $bitsetCanBuildFrom */
   implicit def canBuildFrom: CanBuildFrom[BitSet, Int, BitSet] = bitsetCanBuildFrom
 }
diff --git a/src/library/scala/collection/mutable/Buffer.scala b/src/library/scala/collection/mutable/Buffer.scala
index 1c8aeb6b7a..fbc52ae322 100644
--- a/src/library/scala/collection/mutable/Buffer.scala
+++ b/src/library/scala/collection/mutable/Buffer.scala
@@ -18,12 +18,17 @@ import generic._
  *  appending, prepending, or inserting new elements. It is also
  *  possible to access and modify elements in a random access fashion
  *  via the index of the element in the current sequence.
-  *
+ *
  *  @author Matthias Zenger
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   1
-  */
+ *
+ *  @tparam A    type of the elements contained in this buffer.
+ *
+ *  @define Coll Buffer
+ *  @define coll buffer
+ */
 @cloneable
 trait Buffer[A] extends Seq[A]
                    with GenericTraversableTemplate[A, Buffer]
@@ -31,7 +36,9 @@ trait Buffer[A] extends Seq[A]
   override def companion: GenericCompanion[Buffer] = Buffer
 }
 
-/** Factory object for <code>Buffer</code> trait.
+/** $factoryInfo
+ *  @define coll buffer
+ *  @define Coll Buffer
  */
 object Buffer extends SeqFactory[Buffer] {
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, Buffer[A]] = new GenericCanBuildFrom[A]
diff --git a/src/library/scala/collection/mutable/BufferLike.scala b/src/library/scala/collection/mutable/BufferLike.scala
index 0fb34cc8e0..15e96b2019 100644
--- a/src/library/scala/collection/mutable/BufferLike.scala
+++ b/src/library/scala/collection/mutable/BufferLike.scala
@@ -144,8 +144,8 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
    */
   def append(elems: A*) { appendAll(elems) }
 
-  /** Appends the elements contained in a traversable collection to this buffer.
-   *  @param elems  the collection containing the elements to append.
+  /** Appends the elements contained in a traversable object to this buffer.
+   *  @param xs  the traversable object containing the elements to append.
    */
   def appendAll(xs: TraversableOnce[A]) { this ++= xs }
 
@@ -154,7 +154,7 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
    */
   def prepend(elems: A*) { prependAll(elems) }
 
-  /** Prepends the elements contained in a traversable collection to this buffer.
+  /** Prepends the elements contained in a traversable object to this buffer.
    *  @param elems  the collection containing the elements to prepend.
    */
   def prependAll(xs: TraversableOnce[A]) { xs ++=: this }
@@ -272,7 +272,7 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
   /** Adds a number of elements provided by a traversable object and returns
    *  either the collection itself.
    *
-   *  @param iter     the iterable object.
+   *  @param xs     the traversable object.
    */
   @migration(2, 8,
     "As of 2.8, ++ always creates a new collection, even on Buffers.\n"+
diff --git a/src/library/scala/collection/mutable/BufferProxy.scala b/src/library/scala/collection/mutable/BufferProxy.scala
index d4444dab67..983572452b 100644
--- a/src/library/scala/collection/mutable/BufferProxy.scala
+++ b/src/library/scala/collection/mutable/BufferProxy.scala
@@ -16,13 +16,18 @@ import generic._
 import script._
 
 /** This is a simple proxy class for <a href="Buffer.html"
- *  target="contentFrame"><code>scala.collection.mutable.Buffer</code></a>.
+ *  target="contentFrame">`scala.collection.mutable.Buffer`</a>.
  *  It is most useful for assembling customized set abstractions
  *  dynamically using object composition and forwarding.
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 16/04/2004
  *  @since   1
+ *
+ *  @tparam A     type of the elements the buffer proxy contains.
+ *
+ *  @define Coll BufferProxy
+ *  @define coll buffer proxy
  */
 trait BufferProxy[A] extends Buffer[A] with Proxy {
 
@@ -52,21 +57,21 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
 
   override def readOnly = self.readOnly
 
-  /** Appends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method. The identity of the
+  /** Appends a number of elements provided by a traversable object
+   *  via its <code>foreach</code> method. The identity of the
    *  buffer is returned.
    *
-   *  @param iter  the iterable object.
+   *  @param iter  the traversable object.
    *  @return      the updated buffer.
    */
   @deprecated("Use ++= instead if you intend to add by side effect to an existing collection.\n"+
               "Use `clone() ++=` if you intend to create a new collection.")
   override def ++(xs: TraversableOnce[A]): Buffer[A] = self.++(xs)
 
-  /** Appends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method.
+  /** Appends a number of elements provided by a traversable object.
    *
-   *  @param iter  the iterable object.
+   *  @param xs   the traversable object.
+   *  @return     a reference to this $coll.
    */
   override def ++=(xs: TraversableOnce[A]): this.type = { self.++=(xs); this }
 
@@ -76,10 +81,9 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
    */
   override def append(elems: A*) { self.++=(elems) }
 
-  /** Appends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method.
+  /** Appends a number of elements provided by a traversable object.
    *
-   *  @param iter  the iterable object.
+   *  @param xs   the traversable object.
    */
   override def appendAll(xs: TraversableOnce[A]) { self.appendAll(xs) }
 
@@ -87,6 +91,7 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
    *  the identity of the buffer.
    *
    *  @param elem  the element to append.
+   *  @return      a reference to this $coll.
    */
   def +=:(elem: A): this.type = { self.+=:(elem); this }
 
@@ -98,26 +103,25 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
    */
   override def prepend(elems: A*) { self.prependAll(elems) }
 
-  /** Prepends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method. The identity of the
-   *  buffer is returned.
+  /** Prepends a number of elements provided by a traversable object.
+   *  The identity of the buffer is returned.
    *
-   *  @param iter  the iterable object.
+   *  @param xs  the traversable object.
    */
   override def prependAll(xs: TraversableOnce[A]) { self.prependAll(xs) }
 
-  /** Inserts new elements at the index <code>n</code>. Opposed to method
-   *  <code>update</code>, this method will not replace an element with a
-   *  one. Instead, it will insert the new elements at index <code>n</code>.
+  /** Inserts new elements at the index `n`. Opposed to method
+   *  `update`, this method will not replace an element with a
+   *  one. Instead, it will insert the new elements at index `n`.
    *
    *  @param n      the index where a new element will be inserted.
    *  @param elems  the new elements to insert.
    */
   override def insert(n: Int, elems: A*) { self.insertAll(n, elems) }
 
-  /** Inserts new elements at the index <code>n</code>. Opposed to method
-   *  <code>update</code>, this method will not replace an element with a
-   *  one. Instead, it will insert a new element at index <code>n</code>.
+  /** Inserts new elements at the index `n`. Opposed to method
+   *  `update`, this method will not replace an element with a
+   *  one. Instead, it will insert a new element at index `n`.
    *
    *  @param n     the index where a new element will be inserted.
    *  @param iter  the iterable object providing all elements to insert.
@@ -126,8 +130,7 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
 
   override def insertAll(n: Int, iter: scala.collection.Traversable[A]): Unit = self.insertAll(n, iter)
 
-  /** Replace element at index <code>n</code> with the new element
-   *  <code>newelem</code>.
+  /** Replace element at index `n` with the new element `newelem`.
    *
    *  @param n       the index of the element to replace.
    *  @param newelem the new element.
@@ -152,7 +155,7 @@ trait BufferProxy[A] extends Buffer[A] with Proxy {
 
   /** Return a clone of this buffer.
    *
-   *  @return a <code>Buffer</code> with the same elements.
+   *  @return a `Buffer` with the same elements.
    */
   override def clone(): Buffer[A] = new BufferProxy[A] {
     def self = BufferProxy.this.self.clone()
diff --git a/src/library/scala/collection/mutable/Builder.scala b/src/library/scala/collection/mutable/Builder.scala
index 2e6a9149bc..a930c29948 100644
--- a/src/library/scala/collection/mutable/Builder.scala
+++ b/src/library/scala/collection/mutable/Builder.scala
@@ -15,7 +15,7 @@ import generic._
 
 /** The base trait of all builders.
  *  A builder lets one construct a collection incrementally, by adding
- *  elements to the builder with += and then converting to the required
+ *  elements to the builder with `+=` and then converting to the required
  *  collection type with `result`.
  *
  *  @tparam  Elem  the type of elements that get added to the builder.
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 2cfa4f8ae2..f9505f694b 100644
--- a/src/library/scala/collection/mutable/ConcurrentMap.scala
+++ b/src/library/scala/collection/mutable/ConcurrentMap.scala
@@ -1,23 +1,26 @@
 package scala.collection
 package mutable
 
-/**
- * A template trait for mutable maps that allow concurrent access.
- * $concurrentmapinfo
+
+/** A template trait for mutable maps that allow concurrent access.
+ *
+ *  $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..d8b8278c74 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`),
+ *  the tail (`next`) and a reference to the previous node (`prev`) 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 14f1720a4c..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._
@@ -108,7 +110,7 @@ trait HashTable[A] {
 
   private def capacity(expectedSize: Int) = if (expectedSize == 0) 1 else powerOfTwo(expectedSize)
 
-  /** Find entry with given key in table, null if not found
+  /** Find entry with given key in table, null if not found.
    */
   protected def findEntry(key: A): Entry = {
     val h = index(elemHashCode(key))
@@ -129,7 +131,7 @@ trait HashTable[A] {
       resize(2 * table.length)
   }
 
-  /** Remove entry from table if present
+  /** Remove entry from table if present.
    */
   protected def removeEntry(key: A) : Entry = {
     val h = index(elemHashCode(key))
@@ -155,7 +157,7 @@ trait HashTable[A] {
     null
   }
 
-  /** An iterator returning all entries
+  /** An iterator returning all entries.
    */
   protected def entriesIterator: Iterator[Entry] = new Iterator[Entry] {
     val iterTable = table
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 0a173395e0..14ee5afc9b 100644
--- a/src/library/scala/collection/mutable/IndexedSeq.scala
+++ b/src/library/scala/collection/mutable/IndexedSeq.scala
@@ -14,11 +14,10 @@ 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
  *
- *  @since 2.8
+ *  $indexedSeqInfo
  */
 trait IndexedSeq[A] extends Seq[A]
                    with scala.collection.IndexedSeq[A]
@@ -27,6 +26,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]] = new ArrayBuffer[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/IndexedSeqView.scala b/src/library/scala/collection/mutable/IndexedSeqView.scala
index d870b762d3..9a0e7a4010 100644
--- a/src/library/scala/collection/mutable/IndexedSeqView.scala
+++ b/src/library/scala/collection/mutable/IndexedSeqView.scala
@@ -92,6 +92,8 @@ self =>
 }
 
 /** $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
diff --git a/src/library/scala/collection/mutable/Iterable.scala b/src/library/scala/collection/mutable/Iterable.scala
index 347ee3c8ac..85c6df6fb0 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]
@@ -27,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/LazyBuilder.scala b/src/library/scala/collection/mutable/LazyBuilder.scala
index 7714d29f08..91cf8f2ad9 100644
--- a/src/library/scala/collection/mutable/LazyBuilder.scala
+++ b/src/library/scala/collection/mutable/LazyBuilder.scala
@@ -17,6 +17,9 @@ import immutable.{List, Nil}
  *  be added to this builder with `++=` are not evaluated until `result` is called.
  *
  *  @since 2.8
+ *
+ *  @tparam Elem    type of the elements for this builder.
+ *  @tparam To      type of the collection this builder builds.
  */
 abstract class LazyBuilder[Elem, +To] extends Builder[Elem, To] {
   /** The different segments of elements to be added to the builder, represented as iterators */
diff --git a/src/library/scala/collection/mutable/LinearSeq.scala b/src/library/scala/collection/mutable/LinearSeq.scala
index 9abaef5aff..185b8c97a3 100644
--- a/src/library/scala/collection/mutable/LinearSeq.scala
+++ b/src/library/scala/collection/mutable/LinearSeq.scala
@@ -14,11 +14,12 @@ package mutable
 
 import generic._
 
-/** A subtrait of <code>collection.LinearSeq</code> which represents sequences
+/** A subtrait of `collection.LinearSeq` which represents sequences
  *  that can be mutated.
  *  $linearSeqInfo
  *
- *  @since 2.8
+ *  @define Coll LinearSeq
+ *  @define coll linear sequence
  */
 trait LinearSeq[A] extends Seq[A]
                            with scala.collection.LinearSeq[A]
@@ -27,6 +28,10 @@ trait LinearSeq[A] extends Seq[A]
   override def companion: GenericCompanion[LinearSeq] = LinearSeq
 }
 
+/** $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]
   def newBuilder[A]: Builder[A, LinearSeq[A]] = new MutableList[A]
diff --git a/src/library/scala/collection/mutable/LinkedEntry.scala b/src/library/scala/collection/mutable/LinkedEntry.scala
index 46db4cdf09..5d591058e8 100644
--- a/src/library/scala/collection/mutable/LinkedEntry.scala
+++ b/src/library/scala/collection/mutable/LinkedEntry.scala
@@ -12,8 +12,8 @@
 package scala.collection
 package mutable
 
-/**
- * @since 2.8
+/** Class for the linked hash map entry, used internally.
+ *  @since 2.8
  */
 @serializable
 final class LinkedEntry[A, B](val key: A, var value: B)
diff --git a/src/library/scala/collection/mutable/LinkedHashMap.scala b/src/library/scala/collection/mutable/LinkedHashMap.scala
index 2636219727..97961ccd9c 100644
--- a/src/library/scala/collection/mutable/LinkedHashMap.scala
+++ b/src/library/scala/collection/mutable/LinkedHashMap.scala
@@ -14,20 +14,36 @@ package mutable
 
 import generic._
 
-/** This class implements mutable maps using a hashtable.
- *  The iterator and all traversal methods of this class visit elements in the order they were inserted.
- *
- *  @author  Martin Odersky
- *  @version 2.8
- *  @since   2.7
+/** $factoryInfo
+ *  @define Coll LinkedHashMap
+ *  @define coll linked hash map
  */
 object LinkedHashMap extends MutableMapFactory[LinkedHashMap] {
   implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), LinkedHashMap[A, B]] = new MapCanBuildFrom[A, B]
   def empty[A, B] = new LinkedHashMap[A, B]
 }
 
-/**
- * @since 2.7
+/** This class implements mutable maps using a hashtable.
+ *  The iterator and all traversal methods of this class visit elements in the order they were inserted.
+ *
+ *  @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 LinkedHashMap
+ *  @define coll linked hash map
+ *  @define thatinfo the class of the returned collection. In the standard library configuration,
+ *    `That` is always `LinkedHashMap[A, B]` if the elements contained in the resulting collection are
+ *    pairs of type `(A, B)`. This is because an implicit of type `CanBuildFrom[LinkedHashMap, (A, B), LinkedHashMap[A, B]]`
+ *    is defined in object `LinkedHashMap`. 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 `LinkedHashMap`.
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
+ *  @define orderDependent
+ *  @define orderDependentFold
  */
 @serializable @SerialVersionUID(1L)
 class LinkedHashMap[A, B] extends Map[A, B]
diff --git a/src/library/scala/collection/mutable/LinkedHashSet.scala b/src/library/scala/collection/mutable/LinkedHashSet.scala
index 54338f61c9..7ecb71e23b 100644
--- a/src/library/scala/collection/mutable/LinkedHashSet.scala
+++ b/src/library/scala/collection/mutable/LinkedHashSet.scala
@@ -13,9 +13,29 @@ package mutable
 
 import generic._
 
-/** Todo: this has O(n) cost for element removal.
- *  Should be rewritten to be more efficient.
- *  @since 2.2
+/** This class implements mutable sets using a hashtable.
+ *  The iterator and all traversal methods of this class visit elements in the order they were inserted.
+ *
+ *  @author  Matthias Zenger
+ *  @author  Martin Odersky
+ *  @version 2.0, 31/12/2006
+ *  @since   1
+ *
+ *  @tparam A     the type of the elements contained in this set.
+ *
+ *  @define Coll LinkedHashSet
+ *  @define coll linked hash set
+ *  @define thatinfo the class of the returned collection. In the standard library configuration,
+ *    `That` is always `LinkedHashSet[B]` because an implicit of type `CanBuildFrom[LinkedHashSet, B, LinkedHashSet[B]]`
+ *    is defined in object `LinkedHashSet`.
+ *  @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 `LinkedHashSet`.
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
+ *  @define orderDependent
+ *  @define orderDependentFold
  */
 @serializable @SerialVersionUID(1L)
 class LinkedHashSet[A] extends Set[A]
@@ -63,7 +83,10 @@ class LinkedHashSet[A] extends Set[A]
   }
 }
 
-/** Factory object for `LinkedHashSet` class */
+/** $factoryInfo
+ *  @define Coll LinkedHashSet
+ *  @define coll linked hash set
+ */
 object LinkedHashSet extends SetFactory[LinkedHashSet] {
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, LinkedHashSet[A]] = setCanBuildFrom[A]
   override def empty[A]: LinkedHashSet[A] = new LinkedHashSet[A]
diff --git a/src/library/scala/collection/mutable/LinkedList.scala b/src/library/scala/collection/mutable/LinkedList.scala
index 5570e80b22..a72acf1438 100644
--- a/src/library/scala/collection/mutable/LinkedList.scala
+++ b/src/library/scala/collection/mutable/LinkedList.scala
@@ -14,13 +14,29 @@ package mutable
 
 import generic._
 
-/** This class implements single linked lists where both the head (<code>elem</code>)
- *  and the tail (<code>next</code>) are mutable.
+/** This class implements single 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 linked list.
+ *
+ *  @define Coll LinkedList
+ *  @define coll linked list
+ *  @define thatinfo the class of the returned collection. In the standard library configuration,
+ *    `That` is always `LinkedList[B]` because an implicit of type `CanBuildFrom[LinkedList, B, LinkedList[B]]`
+ *    is defined in object `LinkedList`.
+ *  @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 `LinkedList`.
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable @SerialVersionUID(-7308240733518833071L)
 class LinkedList[A]() extends LinearSeq[A]
@@ -39,6 +55,10 @@ class LinkedList[A]() extends LinearSeq[A]
   override def companion: GenericCompanion[LinkedList] = LinkedList
 }
 
+/** $factoryInfo
+ *  @define Coll LinkedList
+ *  @define coll linked list
+ */
 object LinkedList extends SeqFactory[LinkedList] {
 
   override def empty[A]: LinkedList[A] = new LinkedList[A]
diff --git a/src/library/scala/collection/mutable/LinkedListLike.scala b/src/library/scala/collection/mutable/LinkedListLike.scala
index 2523ece370..4f1a878e02 100644
--- a/src/library/scala/collection/mutable/LinkedListLike.scala
+++ b/src/library/scala/collection/mutable/LinkedListLike.scala
@@ -16,13 +16,20 @@ import generic._
 import annotation.tailrec
 
 /** This extensible class may be used as a basis for implementing linked
- *  list. Type variable <code>A</code> refers to the element type of the
- *  list, type variable <code>This</code> is used to model self types of
+ *  list. 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
  *  @author  Martin Odersky
- *  @version 2.8
+ *  @version 1.0, 08/07/2003
  *  @since   2.8
+ *
+ *  @tparam A    type of the elements contained in the linked list
+ *  @tparam This the type of the actual linked list holding the elements
+ *
+ *  @define Coll LinkedList
+ *  @define coll linked list
  */
 trait LinkedListLike[A, This <: Seq[A] with LinkedListLike[A, This]] extends SeqLike[A, This] { self =>
 
diff --git a/src/library/scala/collection/mutable/ListBuffer.scala b/src/library/scala/collection/mutable/ListBuffer.scala
index b8e5aeb262..a2611a8c0f 100644
--- a/src/library/scala/collection/mutable/ListBuffer.scala
+++ b/src/library/scala/collection/mutable/ListBuffer.scala
@@ -15,13 +15,29 @@ package mutable
 import generic._
 import immutable.{List, Nil, ::}
 
-/** A Buffer implementation back up by a list. It provides constant time
+/** A `Buffer` implementation back up by a list. It provides constant time
  *  prepend and append. Most other operations are linear.
  *
  *  @author  Matthias Zenger
  *  @author  Martin Odersky
  *  @version 2.8
  *  @since   1
+ *
+ *  @tparam A    the type of this list buffer's elements.
+ *
+ *  @define Coll ListBuffer
+ *  @define coll list buffer
+ *  @define thatinfo the class of the returned collection. In the standard library configuration,
+ *    `That` is always `ListBuffer[B]` because an implicit of type `CanBuildFrom[ListBuffer, B, ListBuffer[B]]`
+ *    is defined in object `ListBuffer`.
+ *  @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 `ListBuffer`.
+ *  @define orderDependent
+ *  @define orderDependentFold
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
  */
 @serializable @SerialVersionUID(3419063961353022661L)
 final class ListBuffer[A]
@@ -42,7 +58,9 @@ final class ListBuffer[A]
 
   protected def underlying: immutable.Seq[A] = start
 
-  /** The current length of the buffer
+  /** The current length of the buffer.
+   *
+   *  This operation takes constant time.
    */
   override def length = len
 
@@ -52,13 +70,13 @@ final class ListBuffer[A]
     if (n < 0 || n >= len) throw new IndexOutOfBoundsException(n.toString())
     else super.apply(n)
 
-  /** Replaces element at index <code>n</code> with the new element
-   *  <code>newelem</code>. Takes time linear in the buffer size. (except the
+  /** Replaces element at index `n` with the new element
+   *  `newelem`. Takes time linear in the buffer size. (except the
    *  first element, which is updated in constant time).
    *
    *  @param n  the index of the element to replace.
    *  @param x  the new element.
-   *  @throws Predef.IndexOutOfBoundsException if <code>n</code> is out of bounds.
+   *  @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
    */
   def update(n: Int, x: A) {
     try {
@@ -90,6 +108,7 @@ final class ListBuffer[A]
   /** Appends a single element to this buffer. This operation takes constant time.
    *
    *  @param x  the element to append.
+   *  @return   this $coll.
    */
   def += (x: A): this.type = {
     if (exported) copy()
@@ -117,7 +136,7 @@ final class ListBuffer[A]
    *  time.
    *
    *  @param x  the element to prepend.
-   *  @return   this buffer.
+   *  @return   this $coll.
    */
   def +=: (x: A): this.type = {
     if (exported) copy()
@@ -128,13 +147,13 @@ final class ListBuffer[A]
     this
   }
 
-  /** Inserts new elements at the index <code>n</code>. Opposed to method
-   *  <code>update</code>, this method will not replace an element with a new
-   *  one. Instead, it will insert a new element at index <code>n</code>.
+  /** Inserts new elements at the index `n`. Opposed to method
+   *  `update`, this method will not replace an element with a new
+   *  one. Instead, it will insert a new element at index `n`.
    *
    *  @param  n     the index where a new element will be inserted.
    *  @param  iter  the iterable object providing all elements to insert.
-   *  @throws Predef.IndexOutOfBoundsException if <code>n</code> is out of bounds.
+   *  @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
    */
   def insertAll(n: Int, seq: Traversable[A]) {
     try {
@@ -230,9 +249,9 @@ final class ListBuffer[A]
    *  the buffer size
    *
    *  @param  n  the index which refers to the element to delete.
-   *  @return n  the element that was formerly at position <code>n</code>.
-   *  @note      an element must exists at position <code>n</code>
-   *  @throws Predef.IndexOutOfBoundsException if <code>n</code> is out of bounds.
+   *  @return n  the element that was formerly at position `n`.
+   *  @note      an element must exists at position `n`.
+   *  @throws Predef.IndexOutOfBoundsException if `n` is out of bounds.
    */
   def remove(n: Int): A = {
     if (n < 0 || n >= len) throw new IndexOutOfBoundsException(n.toString())
@@ -259,6 +278,7 @@ final class ListBuffer[A]
    *  buffer size.
    *
    *  @param x  the element to remove.
+   *  @return   this $coll.
    */
   override def -= (elem: A): this.type = {
     if (exported) copy()
@@ -328,10 +348,9 @@ final class ListBuffer[A]
   override def stringPrefix: String = "ListBuffer"
 }
 
-/** Factory object for <code>ListBuffer</code> class.
- *
- *  @author  Martin Odersky
- *  @version 2.8
+/** $factoryInfo
+ *  @define Coll ListBuffer
+ *  @define coll list buffer
  */
 object ListBuffer extends SeqFactory[ListBuffer] {
   implicit def canBuildFrom[A]: CanBuildFrom[Coll, A, ListBuffer[A]] = new GenericCanBuildFrom[A]
diff --git a/src/library/scala/collection/mutable/ListMap.scala b/src/library/scala/collection/mutable/ListMap.scala
index c96873c81d..a4321d3818 100644
--- a/src/library/scala/collection/mutable/ListMap.scala
+++ b/src/library/scala/collection/mutable/ListMap.scala
@@ -14,8 +14,26 @@ package mutable
 
 import generic._
 
-/** A simple map backed by a list.
- * @since 2.8
+/** A simple mutable map backed by a list.
+ *
+ *  @tparam A    the type of the keys contained in this list map.
+ *  @tparam B    the type of the values assigned to keys in this list map.
+ *
+ *  @define Coll mutable.ListMap
+ *  @define coll mutable list map
+ *  @define thatinfo the class of the returned collection. In the standard library configuration,
+ *    `That` is always `ListMap[A, B]` if the elements contained in the resulting collection are
+ *    pairs of type `(A, B)`. This is because an implicit of type `CanBuildFrom[ListMap, (A, B), ListMap[A, B]]`
+ *    is defined in object `ListMap`. 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 `ListMap`.
+ *  @define mayNotTerminateInf
+ *  @define willNotTerminateInf
+ *  @define orderDependent
+ *  @define orderDependentFold
  */
 @serializable
 class ListMap[A, B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] {
@@ -40,10 +58,9 @@ class ListMap[A, B] extends Map[A, B] with MapLike[A, B, ListMap[A, B]] {
   override def size: Int = siz
 }
 
-/** This class implements mutable maps using a list.
- *
- *  @author  Martin Odersky
- *  @version 2.8
+/** $factoryInfo
+ *  @define Coll ListMap
+ *  @define coll list map
  */
 object ListMap extends MutableMapFactory[ListMap] {
   implicit def canBuildFrom[A, B]: CanBuildFrom[Coll, (A, B), ListMap[A, B]] = new MapCanBuildFrom[A, B]
diff --git a/src/library/scala/collection/mutable/MapLike.scala b/src/library/scala/collection/mutable/MapLike.scala
index 9c3c1c0e5f..19e67a6731 100644
--- a/src/library/scala/collection/mutable/MapLike.scala
+++ b/src/library/scala/collection/mutable/MapLike.scala
@@ -40,7 +40,7 @@ import annotation.migration
  *    `drop`, `filter` return the same kind of map, you
  *    should also override:
  *  {{{
- *    def> empty: This
+ *    def empty: This
  *  }}}
  *    If you wish to avoid the unnecessary construction of an `Option`
  *    object, you could also override `apply`, `update`,
@@ -187,7 +187,8 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
    */
   def clear() { keysIterator foreach -= }
 
-  /** If given key is already in this map, returns associated value
+  /** If given key is already in this map, returns associated value.
+   *
    *  Otherwise, computes value from given expression `op`, stores with key
    *  in map and returns that value.
    *  @param  key the key to test
diff --git a/src/library/scala/collection/mutable/MultiMap.scala b/src/library/scala/collection/mutable/MultiMap.scala
index 01ddea070c..39c51ef5ad 100644
--- a/src/library/scala/collection/mutable/MultiMap.scala
+++ b/src/library/scala/collection/mutable/MultiMap.scala
@@ -13,21 +13,42 @@ package scala.collection
 package mutable
 
 
-/** This class is typically used as a mixin. It turns maps which map <code>A</code>
- *  to <code>Set[B]</code> objects into multi maps which map <code>A</code> to
- *  <code>B</code> objects.
+/** A trait for mutable maps with multiple values assigned to a key.
  *
+ *  This class is typically used as a mixin. It turns maps which map `A`
+ *  to `Set[B]` objects into multi maps which map `A` to
+ *  `B` objects.
+ *
+ *  @define coll multimap
+ *  @define Coll MultiMap
  *  @author  Matthias Zenger
  *  @author  Martin Odersky
  *  @version 2.8
  *  @since   1
  */
 trait MultiMap[A, B] extends Map[A, Set[B]] {
+  /** Creates a new set.
+   *
+   *  Classes that use this trait as a mixin can override this method
+   *  to have the desired implementation of sets assigned to new keys.
+   *  By default this is `HashSet`.
+   *
+   *  @return An empty set of values of type `B`.
+   */
   protected def makeSet: Set[B] = new HashSet[B]
 
   @deprecated("use addBinding instead")
   def add(key: A, value: B): this.type = addBinding(key, value)
 
+  /** Assigns the specified `value` to a specified `key`, replacing
+   *  the existing value assigned to that `key` if it is equal to
+   *  the specified value. Otherwise, simply adds another binding to
+   *  the `key`.
+   *
+   *  @param key    The key to which to bind the new value.
+   *  @param value  The value to bind to the key.
+   *  @return       A reference to this multimap.
+   */
   def addBinding(key: A, value: B): this.type = {
     get(key) match {
       case None =>
@@ -40,6 +61,15 @@ trait MultiMap[A, B] extends Map[A, Set[B]] {
     this
   }
 
+  /** Removes the binding of `value` to `key` if it exists.
+   *
+   *  If this was the last value assigned to the specified key, the
+   *  set assigned to that key will be removed as well.
+   *
+   *  @param key     The key of the binding.
+   *  @param value   The value to remove.
+   *  @return        A reference to this multimap.
+   */
   def removeBinding(key: A, value: B): this.type = {
     get(key) match {
       case None =>
@@ -50,6 +80,12 @@ trait MultiMap[A, B] extends Map[A, Set[B]] {
     this
   }
 
+  /** Checks if there exists a binding to `key` such that it satisfies the predicate `p`.
+   *
+   *  @param key   The key for which the predicate is checked.
+   *  @param p     The predicate which a value assigned to the key must satisfy.
+   *  @return      A boolean if such a binding exists
+   */
   def entryExists(key: A, p: B => Boolean): Boolean = get(key) match {
     case None => false
     case Some(set) => set exists p
diff --git a/src/library/scala/collection/mutable/MutableList.scala b/src/library/scala/collection/mutable/MutableList.scala
index 7784927c87..4324fa7ef9 100644
--- a/src/library/scala/collection/mutable/MutableList.scala
+++ b/src/library/scala/collection/mutable/MutableList.scala
@@ -15,12 +15,12 @@ package mutable
 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>
- *  !!! todo: convert to LinkedListBuffer?
  *
  *  @author  Matthias Zenger
  *  @author  Martin Odersky
diff --git a/src/library/scala/collection/mutable/OpenHashMap.scala b/src/library/scala/collection/mutable/OpenHashMap.scala
index 79bb96a0bf..cbcc19c3e8 100644
--- a/src/library/scala/collection/mutable/OpenHashMap.scala
+++ b/src/library/scala/collection/mutable/OpenHashMap.scala
@@ -57,6 +57,9 @@ class OpenHashMap[Key, Value](initialSize : Int) extends Map[Key, Value]
   import OpenHashMap.OpenEntry
   type Entry = OpenEntry[Key, Value]
 
+  /**
+   * A default constructor creates a hashmap with initial size 8.
+   */
   def this() = this(8);
 
   override def empty: OpenHashMap[Key, Value] = OpenHashMap.empty[Key, Value]
@@ -212,7 +215,7 @@ class OpenHashMap[Key, Value](initialSize : Int) extends Map[Key, Value]
    *
    * @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")
diff --git a/src/library/scala/collection/mutable/PriorityQueue.scala b/src/library/scala/collection/mutable/PriorityQueue.scala
index 4d74a2ee74..eade376abe 100644
--- a/src/library/scala/collection/mutable/PriorityQueue.scala
+++ b/src/library/scala/collection/mutable/PriorityQueue.scala
@@ -144,10 +144,10 @@ class PriorityQueue[A](implicit ord: Ordering[A])
     this
   }
 
-  /** Adds all elements provided by an <code>Iterable</code> object
+  /** Adds all elements provided by a `TraversableOnce` object
    *  into the priority queue.
    *
-   *  @param  iter        an iterable object
+   *  @param  xs    an iterable object
    */
   def ++(xs: TraversableOnce[A]) = { this.clone() ++= xs }
 
@@ -206,14 +206,16 @@ 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
-   * <code>x</code> and <code>y</code> the original queue's ordering
-   * had <code>compare</code> returning an integer w, the new one will return -w,
+   * `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
-   * <code>compare</code> method returns 0. In this case, such elements
+   * `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.
    */
   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 427ffe478a..3f1ee5d217 100644
--- a/src/library/scala/collection/mutable/PriorityQueueProxy.scala
+++ b/src/library/scala/collection/mutable/PriorityQueueProxy.scala
@@ -11,7 +11,7 @@
 package scala.collection
 package mutable
 
-/** This class implements priority queues using a heap. The
+/** 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.
  *
diff --git a/src/library/scala/collection/mutable/Seq.scala b/src/library/scala/collection/mutable/Seq.scala
index a57d397275..8d11e14063 100644
--- a/src/library/scala/collection/mutable/Seq.scala
+++ b/src/library/scala/collection/mutable/Seq.scala
@@ -16,9 +16,10 @@ import generic._
 
 /** A subtrait of <code>collection.Seq</code> which represents sequences
  *  that can be mutated.
- *  The class adds an <code>update</code> method to <code>collection.Seq</code>.
  *
- *  @since 2.8
+ *  $seqInfo
+ *
+ *  The class adds an <code>update</code> method to <code>collection.Seq</code>.
  */
 trait Seq[A] extends Iterable[A]
                      with scala.collection.Seq[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
 
diff --git a/src/library/scala/collection/mutable/Stack.scala b/src/library/scala/collection/mutable/Stack.scala
index 45e9fa24b2..c224c030a4 100644
--- a/src/library/scala/collection/mutable/Stack.scala
+++ b/src/library/scala/collection/mutable/Stack.scala
@@ -57,11 +57,11 @@ class Stack[A] private (var elems: List[A]) extends scala.collection.Seq[A] with
    */
   def push(elem1: A, elem2: A, elems: A*): this.type = this.push(elem1).push(elem2).pushAll(elems)
 
-  /** Push all elements provided by the given iterator object onto
-   *  the stack. The last element returned by the iterator
+  /** Push all elements in the given traversable object onto
+   *  the stack. The last element in the traversable object
    *  will be on top of the new stack.
    *
-   *  @param   elems      the iterator object.
+   *  @param xs the traversable object.
    *  @return the stack with the new elements on top.
    */
   def pushAll(xs: TraversableOnce[A]): this.type = { xs foreach push ; this }
diff --git a/src/library/scala/collection/mutable/SynchronizedBuffer.scala b/src/library/scala/collection/mutable/SynchronizedBuffer.scala
index 1c9a77c46a..0fef1a6635 100644
--- a/src/library/scala/collection/mutable/SynchronizedBuffer.scala
+++ b/src/library/scala/collection/mutable/SynchronizedBuffer.scala
@@ -54,18 +54,18 @@ trait SynchronizedBuffer[A] extends Buffer[A] {
     super.+=(elem)
   }
 
-  /** Appends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method. The identity of the
-   *  buffer is returned.
+  /** Appends a number of elements provided by a traversable object via
+   *  its `foreach` method.
+   *  The identity of the buffer is returned.
    *
-   *  @param iter  the iterable object.
+   *  @param xs the traversable object.
    */
   override def ++(xs: TraversableOnce[A]): Self = synchronized {
     super.++(xs)
   }
 
-  /** Appends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method.
+  /** Appends a number of elements provided by a traversable object
+   *  via its `foreach` method.
    *
    *  @param iter  the iterable object.
    */
@@ -81,10 +81,10 @@ trait SynchronizedBuffer[A] extends Buffer[A] {
     super.++=(elems)
   }
 
-  /** Appends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method.
+  /** Appends a number of elements provided by a traversable object
+   *  via its <code>foreach</code> method.
    *
-   *  @param iter  the iterable object.
+   *  @param xs the traversable object.
    */
   override def appendAll(xs: TraversableOnce[A]): Unit = synchronized {
     super.appendAll(xs)
@@ -99,11 +99,11 @@ trait SynchronizedBuffer[A] extends Buffer[A] {
     super.+=:(elem)
   }
 
-  /** Prepends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method. The identity of the
+  /** Prepends a number of elements provided by a traversable object
+   *  via its <code>foreach</code> method. The identity of the
    *  buffer is returned.
    *
-   *  @param iter  the iterable object.
+   *  @param xs the traversable object.
    */
   override def ++=:(xs: TraversableOnce[A]): this.type = synchronized[this.type] { super.++=:(xs) }
 
@@ -113,11 +113,11 @@ trait SynchronizedBuffer[A] extends Buffer[A] {
    */
   override def prepend(elems: A*): Unit = prependAll(elems)
 
-  /** Prepends a number of elements provided by an iterable object
-   *  via its <code>iterator</code> method. The identity of the
+  /** Prepends a number of elements provided by a traversable object
+   *  via its <code>foreach</code> method. The identity of the
    *  buffer is returned.
    *
-   *  @param iter  the iterable object.
+   *  @param xs the traversable object.
    */
   override def prependAll(xs: TraversableOnce[A]): Unit = synchronized {
     super.prependAll(xs)
@@ -139,10 +139,10 @@ trait SynchronizedBuffer[A] extends Buffer[A] {
    *  one. Instead, it will insert a new element at index <code>n</code>.
    *
    *  @param n     the index where a new element will be inserted.
-   *  @param iter  the iterable object providing all elements to insert.
+   *  @param xs    the traversable object providing all elements to insert.
    */
-  abstract override def insertAll(n: Int, iter: Traversable[A]): Unit = synchronized {
-     super.insertAll(n, iter)
+  abstract override def insertAll(n: Int, xs: Traversable[A]): Unit = synchronized {
+     super.insertAll(n, xs)
   }
 
   /** Replace element at index <code>n</code> with the new element
diff --git a/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala b/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala
index 9d18846252..933b3b41a4 100644
--- a/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala
+++ b/src/library/scala/collection/mutable/SynchronizedPriorityQueue.scala
@@ -12,7 +12,7 @@
 package scala.collection
 package mutable
 
-/** This class implements synchronized priority queues using a heap.
+/** 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.
  *
@@ -39,13 +39,13 @@ class SynchronizedPriorityQueue[A](implicit ord: Ordering[A]) extends PriorityQu
     this
   }
 
-  /** Adds all elements provided by an iterator into the priority queue.
+  /** Adds all elements of a traversable object into the priority queue.
    *
-   *  @param  it        an iterator
+   *  @param  xs        a traversable object
    */
-  override def ++=(it: TraversableOnce[A]): this.type = {
+  override def ++=(xs: TraversableOnce[A]): this.type = {
     synchronized {
-      super.++=(it)
+      super.++=(xs)
     }
     this
   }
diff --git a/src/library/scala/collection/mutable/SynchronizedQueue.scala b/src/library/scala/collection/mutable/SynchronizedQueue.scala
index e7630cee06..b09687a78e 100644
--- a/src/library/scala/collection/mutable/SynchronizedQueue.scala
+++ b/src/library/scala/collection/mutable/SynchronizedQueue.scala
@@ -36,11 +36,11 @@ class SynchronizedQueue[A] extends Queue[A] {
    */
   override def +=(elem: A): this.type = synchronized[this.type] { super.+=(elem) }
 
-  /** Adds all elements provided by an <code>Iterable</code> object
+  /** Adds all elements provided by a `TraversableOnce` object
    *  at the end of the queue. The elements are prepended in the order they
    *  are given out by the iterator.
    *
-   *  @param  iter        an iterable object
+   *  @param  xs        a traversable object
    */
   override def ++=(xs: TraversableOnce[A]): this.type = synchronized[this.type] { super.++=(xs) }
 
diff --git a/src/library/scala/collection/mutable/SynchronizedStack.scala b/src/library/scala/collection/mutable/SynchronizedStack.scala
index 4394d307eb..4940884302 100644
--- a/src/library/scala/collection/mutable/SynchronizedStack.scala
+++ b/src/library/scala/collection/mutable/SynchronizedStack.scala
@@ -39,16 +39,18 @@ class SynchronizedStack[A] extends Stack[A] {
   /** Push two or more elements onto the stack. The last element
    *  of the sequence will be on top of the new stack.
    *
-   *  @param   elems      the element sequence.
-   *  @return the stack with the new elements on top.
+   *  @param elem1      the first element to push.
+   *  @param elem2      the second element to push.
+   *  @param elems      the element sequence that will be pushed.
+   *  @return           the stack with the new elements on top.
    */
   override def push(elem1: A, elem2: A, elems: A*): this.type = synchronized[this.type] { super.push(elem1, elem2, elems: _*) }
 
-  /** Pushes all elements provided by an iterator
-   *  on top of the stack. The elements are pushed in the order they
-   *  are given out by the iterator.
+  /** Pushes all elements provided by a traversable object
+   *  on top of the stack. The elements are pushed in the order the
+   *  traversable object is traversed.
    *
-   *  @param  elems        an iterator
+   *  @param  xs        a traversable object
    */
   override def pushAll(xs: TraversableOnce[A]): this.type = synchronized[this.type] { super.pushAll(elems) }
 
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]
diff --git a/src/library/scala/collection/mutable/WeakHashMap.scala b/src/library/scala/collection/mutable/WeakHashMap.scala
index cad4dc2e43..8f496add1e 100644
--- a/src/library/scala/collection/mutable/WeakHashMap.scala
+++ b/src/library/scala/collection/mutable/WeakHashMap.scala
@@ -16,8 +16,9 @@ import JavaConversions._
 import generic._
 
 
-/**
- * @since 2.8
+/** A hash map with weak references to entries which are weakly reachable.
+ *
+ *  @since 2.8
  */
 class WeakHashMap[A, B] extends JMapWrapper[A, B](new java.util.WeakHashMap)
 			   with JMapWrapperLike[A, B, WeakHashMap[A, B]] {
diff --git a/src/library/scala/runtime/AbstractFunction0.scala b/src/library/scala/runtime/AbstractFunction0.scala
index 1022a056f9..2d7d613132 100644
--- a/src/library/scala/runtime/AbstractFunction0.scala
+++ b/src/library/scala/runtime/AbstractFunction0.scala
@@ -8,9 +8,12 @@
 
 package scala.runtime
 
-abstract class AbstractFunction0[+R] extends Function0[R] { }
-abstract class AbstractFunction1[-T1, +R] extends Function1[T1, R] { }
-abstract class AbstractFunction2[-T1, -T2, +R] extends Function2[T1, T2, R] { }
+abstract class AbstractFunction0[@specialized(Unit, Int, Long, Double) +R] extends Function0[R] { }
+abstract class AbstractFunction1[@specialized(Int, Long, Double) -T1,
+                                 @specialized(Unit, Int, Long, Double) +R] extends Function1[T1, R] { }
+abstract class AbstractFunction2[@specialized(Int, Long, Double) -T1,
+                                 @specialized(Int, Long, Double) -T2,
+                                 @specialized(Unit, Int, Long, Double) +R] extends Function2[T1, T2, R] { }
 abstract class AbstractFunction3[-T1, -T2, -T3, +R] extends Function3[T1, T2, T3, R] { }
 abstract class AbstractFunction4[-T1, -T2, -T3, -T4, +R] extends Function4[T1, T2, T3, T4, R] { }
 abstract class AbstractFunction5[-T1, -T2, -T3, -T4, -T5, +R] extends Function5[T1, T2, T3, T4, T5, R] { }
diff --git a/src/library/scala/runtime/AnyValCompanion.scala b/src/library/scala/runtime/AnyValCompanion.scala
new file mode 100644
index 0000000000..0a6f93805a
--- /dev/null
+++ b/src/library/scala/runtime/AnyValCompanion.scala
@@ -0,0 +1,86 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2002-2010, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+// $Id$
+
+package scala.runtime
+
+/** A common supertype for companion classes of primitive types.
+ *
+ *  A common trait for /companion/ objects of primitive types comes handy
+ *  when parameterizing code on types. For instance, the specialized
+ *  annotation is passed a sequence of types on which to specialize:
+ *  {{{
+ *     class Tuple1[@specialized(Unit, Int, Double) T]
+ *  }}}
+ *
+ */
+sealed trait AnyValCompanion
+
+/** A object representing 'object scala.Unit'. It should never be used
+ *  directly.
+ */
+object Unit extends AnyValCompanion {
+  override def toString = "object scala.Unit"
+}
+
+/** A object representing 'object scala.Boolean'. It should never be used
+ *  directly.
+ */
+object Boolean extends AnyValCompanion {
+  override def toString = "object scala.Boolean"
+}
+
+/** A object representing 'object scala.Byte'. It should never be used
+ *  directly.
+ */
+object Byte extends AnyValCompanion {
+  override def toString = "object scala.Byte"
+}
+
+/** A object representing 'object scala.Short'. It should never be used
+ *  directly.
+ */
+object Short extends AnyValCompanion {
+  override def toString = "object scala.Short"
+}
+
+/** A object representing 'object scala.Char'. It should never be used
+ *  directly.
+ */
+object Char extends AnyValCompanion {
+  override def toString = "object scala.Char"
+}
+
+/** A object representing 'object scala.Int'. It should never be used
+ *  directly.
+ */
+object Int extends AnyValCompanion {
+  override def toString = "object scala.Int"
+}
+
+/** A object representing 'object scala.Long'. It should never be used
+ *  directly.
+ */
+object Long extends AnyValCompanion {
+  override def toString = "object scala.Long"
+}
+
+/** A object representing 'object scala.Float'. It should never be used
+ *  directly.
+ */
+object Float extends AnyValCompanion {
+  override def toString = "object scala.Float"
+}
+
+/** A object representing 'object scala.Double'. It should never be used
+ *  directly.
+ */
+object Double extends AnyValCompanion {
+  override def toString = "object scala.Double"
+}
diff --git a/src/library/scala/specialized.scala b/src/library/scala/specialized.scala
index 5ad2b0501f..4ac3037328 100644
--- a/src/library/scala/specialized.scala
+++ b/src/library/scala/specialized.scala
@@ -18,20 +18,17 @@ package scala
  *  </code>
  *
  *  Type T can be specialized on a subset of the primitive types by
- *  specifying a comma-separated string argument:
+ *  specifying a list of primitive types to specialize at:
  *
  *  <code>
- *   class MyList[@specialized("Int, Double, Boolean") T] ..
+ *   class MyList[@specialized(Int, Double, Boolean) T] ..
  *  </code>
- *  Only primitive types are supported and no name resolution is currently
- *  done on the string arguments (meaning imports and type aliases are
- *  not resolved).
  *
  *  @since 2.8
  */
-class specialized(types: String) extends StaticAnnotation {
+class specialized(types: runtime.AnyValCompanion*) extends StaticAnnotation {
   def this() {
-    this("Boolean, Byte, Short, Char, Int, Long, Float, Double")
+    this(Unit, Boolean, Byte, Short, Char, Int, Long, Float, Double)
   }
 }
 
diff --git a/src/library/scala/util/Properties.scala b/src/library/scala/util/Properties.scala
index b781e46be5..3a08fa0482 100644
--- a/src/library/scala/util/Properties.scala
+++ b/src/library/scala/util/Properties.scala
@@ -54,6 +54,7 @@ private[scala] trait PropertiesTrait
   def clearProp(name: String)                   = System.clearProperty(name)
 
   def envOrElse(name: String, alt: String)      = Option(System getenv name) getOrElse alt
+  def envOrNone(name: String)                   = Option(System getenv name)
 
   // for values based on propFilename
   def scalaPropOrElse(name: String, alt: String): String  = scalaProps.getProperty(name, alt)
author	Antonio Cunei <antonio.cunei@epfl.ch>	2010-04-12 07:44:39 +0000
committer	Antonio Cunei <antonio.cunei@epfl.ch>	2010-04-12 07:44:39 +0000
commit	f31eaf606f2f1f524621dacd280abfccb9110f59 (patch)
tree	cb7aa7c227e526571a74b92b6b9471032dce4ba5 /src/library
parent	8ff235f9491a4a90969b494a32c1f55c69e2e0a8 (diff)
download	scala-f31eaf606f2f1f524621dacd280abfccb9110f59.tar.gz scala-f31eaf606f2f1f524621dacd280abfccb9110f59.tar.bz2 scala-f31eaf606f2f1f524621dacd280abfccb9110f59.zip