Updated docs. No review.

41 files changed, 710 insertions, 126 deletions

diff --git a/src/library/scala/collection/Parallel.scala b/src/library/scala/collection/Parallel.scala
index e500817745..df77e5d1c7 100644
--- a/src/library/scala/collection/Parallel.scala
+++ b/src/library/scala/collection/Parallel.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection
 
 
@@ -7,7 +16,7 @@ package scala.collection
 
 /** A marker trait for objects with parallelised operations.
  *
- *  @since 2.8
+ *  @since 2.9
  *  @author prokopec
  */
 trait Parallel
diff --git a/src/library/scala/collection/Parallelizable.scala b/src/library/scala/collection/Parallelizable.scala
index 215a8a66ff..999849fbab 100644
--- a/src/library/scala/collection/Parallelizable.scala
+++ b/src/library/scala/collection/Parallelizable.scala
@@ -9,6 +9,8 @@ import parallel.ParIterableLike
 /** This trait describes collections which can be turned into parallel collections
  *  by invoking the method `par`. Parallelizable collections may be parametrized with
  *  a target type different than their own.
+ *
+ *  @tparam ParRepr      the actual type of the collection, which has to be parallel
  */
 trait Parallelizable[+ParRepr <: Parallel] {
 
diff --git a/src/library/scala/collection/parallel/Combiner.scala b/src/library/scala/collection/parallel/Combiner.scala
index 4a6ae0cd8f..ec45a5eb90 100644
--- a/src/library/scala/collection/parallel/Combiner.scala
+++ b/src/library/scala/collection/parallel/Combiner.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -8,27 +17,25 @@ import scala.collection.generic.Sizing
 
 
 /** The base trait for all combiners.
- *  A combiner lets one construct collections incrementally just like
+ *  A combiner incremental collection construction just like
  *  a regular builder, but also implements an efficient merge operation of two builders
  *  via `combine` method. Once the collection is constructed, it may be obtained by invoking
  *  the `result` method.
  *
+ *  The complexity of the `combine` method should be less than linear for best
+ *  performance. The `result` method doesn't have to be a constant time operation,
+ *  but may be performed in parallel.
+ *
  *  @tparam Elem   the type of the elements added to the builder
  *  @tparam To     the type of the collection the builder produces
  *
- *  @author prokopec
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
  */
 trait Combiner[-Elem, +To] extends Builder[Elem, To] with Sizing with Parallel {
 self: EnvironmentPassingCombiner[Elem, To] =>
   private[collection] final val tasksupport = getTaskSupport
 
-  // type EPC = EnvironmentPassingCombiner[Elem, To]
-  //
-  // [scalacfork] /scratch/trunk2/src/library/scala/collection/parallel/Combiner.scala:25: error: contravariant type Elem occurs in invariant position in type scala.collection.parallel.EnvironmentPassingCombiner[Elem,To] of type EPC
-  // [scalacfork]   type EPC = EnvironmentPassingCombiner[Elem, To]
-  // [scalacfork]        ^
-  // [scalacfork] one error found
-
   /** Combines the contents of the receiver builder and the `other` builder,
    *  producing a new builder containing both their elements.
    *
@@ -59,10 +66,9 @@ self: EnvironmentPassingCombiner[Elem, To] =>
 }
 
 
-trait EnvironmentPassingCombiner[-Elem, +To] extends Combiner[Elem, To] {
+private[collection] trait EnvironmentPassingCombiner[-Elem, +To] extends Combiner[Elem, To] {
   abstract override def result = {
     val res = super.result
-    //
     res
   }
 }
diff --git a/src/library/scala/collection/parallel/ParIterable.scala b/src/library/scala/collection/parallel/ParIterable.scala
index 7f5b39d3e4..48b0e35151 100644
--- a/src/library/scala/collection/parallel/ParIterable.scala
+++ b/src/library/scala/collection/parallel/ParIterable.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -14,8 +23,11 @@ import scala.collection.parallel.mutable.ParArray
  *
  *  @tparam T    the element type of the collection
  *
- *  @author prokopec
- *  @since 2.8
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
+ *
+ *  @define Coll ParIterable
+ *  @define coll parallel iterable
  */
 trait ParIterable[+T] extends Iterable[T]
                          with GenericParTemplate[T, ParIterable]
diff --git a/src/library/scala/collection/parallel/ParIterableLike.scala b/src/library/scala/collection/parallel/ParIterableLike.scala
index 190752a3ca..1a63e26622 100644
--- a/src/library/scala/collection/parallel/ParIterableLike.scala
+++ b/src/library/scala/collection/parallel/ParIterableLike.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -18,7 +27,6 @@ import annotation.unchecked.uncheckedVariance
 
 
 
-// TODO update docs!!
 /** A template trait for parallel collections of type `ParIterable[T]`.
  *
  *  $paralleliterableinfo
@@ -30,75 +38,96 @@ import annotation.unchecked.uncheckedVariance
  *
  *  @define paralleliterableinfo
  *  This is a base trait for Scala parallel collections. It defines behaviour
- *  common to all parallel collections. The actual parallel operation implementation
- *  is found in the `ParallelIterableFJImpl` trait extending this trait. Concrete
- *  parallel collections should inherit both this and that trait.
+ *  common to all parallel collections. Concrete parallel collections should
+ *  inherit this trait and `ParIterable` if they want to define specific combiner
+ *  factories.
  *
  *  Parallel operations are implemented with divide and conquer style algorithms that
  *  parallelize well. The basic idea is to split the collection into smaller parts until
  *  they are small enough to be operated on sequentially.
  *
- *  All of the parallel operations are implemented in terms of several methods. The first is:
+ *  All of the parallel operations are implemented as tasks within this trait. Tasks rely
+ *  on the concept of splitters, which extend iterators. Every parallel collection defines:
+ *
  *  {{{
- *     def split: Seq[Repr]
+ *     def parallelIterator: ParIterableIterator[T]
  *  }}}
- *  which splits the collection into a sequence of disjunct views. This is typically a
- *  very fast operation which simply creates wrappers around the receiver collection.
- *  These views can then be split recursively into smaller views and so on. Each of
- *  the views is still a parallel collection.
  *
- *  The next method is:
+ *  which returns an instance of `ParIterableIterator[T]`, which is a subtype of `Splitter[T]`.
+ *  Parallel iterators have a method `remaining` to check the remaining number of elements,
+ *  and method `split` which is defined by splitters. Method `split` divides the splitters
+ *  iterate over into disjunct subsets:
+ *
  *  {{{
- *     def combine[OtherRepr >: Repr](other: OtherRepr): OtherRepr
+ *     def split: Seq[Splitter]
  *  }}}
- *  which combines this collection with the argument collection and returns a collection
- *  containing both the elements of this collection and the argument collection. This behaviour
- *  may be implemented by producing a view that iterates over both collections, by aggressively
- *  copying all the elements into the new collection or by lazily creating a wrapper over both
- *  collections that gets evaluated once it's needed. It is recommended to avoid copying all of
+ *
+ *  which splits the splitter into a sequence of disjunct subsplitters. This is typically a
+ *  very fast operation which simply creates wrappers around the receiver collection.
+ *  This can be repeated recursively.
+ *
+ *  Method `newCombiner` produces a new combiner. Combiners are an extension of builders.
+ *  They provide a method `combine` which combines two combiners and returns a combiner
+ *  containing elements of both combiners.
+ *  This method can be implemented by aggressively copying all the elements into the new combiner
+ *  or by lazily binding their results. It is recommended to avoid copying all of
  *  the elements for performance reasons, although that cost might be negligible depending on
- *  the use case.
+ *  the use case. Standard parallel collection combiners avoid copying when merging results,
+ *  relying either on a two-step lazy construction or specific data-structure properties.
  *
  *  Methods:
+ *
  *  {{{
- *     def seq: Repr
- *  }}}
- *  and
- *  {{{
+ *     def seq: Sequential
  *     def par: Repr
  *  }}}
+ *
  *  produce a view of the collection that has sequential or parallel operations, respectively.
+ *  These methods are efficient - they will not copy the elements, but have fixed target
+ *  types. The combination of methods `toParMap`, `toParSeq` or `toParSet` is more flexible,
+ *  but may copy the elements in some cases.
  *
  *  The method:
+ *
  *  {{{
  *     def threshold(sz: Int, p: Int): Int
  *  }}}
+ *
  *  provides an estimate on the minimum number of elements the collection has before
  *  the splitting stops and depends on the number of elements in the collection. A rule of the
  *  thumb is the number of elements divided by 8 times the parallelism level. This method may
  *  be overridden in concrete implementations if necessary.
  *
- *  Finally, method `newCombiner` produces a new parallel builder.
- *
- *  Since this trait extends the `Iterable` trait, methods like `size` and `iterator` must also
- *  be implemented.
+ *  Since this trait extends the `Iterable` trait, methods like `size` must also
+ *  be implemented in concrete collections, while `iterator` forwards to `parallelIterator` by
+ *  default.
  *
  *  Each parallel collection is bound to a specific fork/join pool, on which dormant worker
- *  threads are kept. One can change a fork/join pool of a collection any time except during
- *  some method being invoked. The fork/join pool contains other information such as the parallelism
+ *  threads are kept. The fork/join pool contains other information such as the parallelism
  *  level, that is, the number of processors used. When a collection is created, it is assigned the
- *  default fork/join pool found in the `scala.collection.parallel` package object.
+ *  default fork/join pool found in the `scala.parallel` package object.
+ *
+ *  Parallel collections are not necessarily ordered in terms of the `foreach`
+ *  operation (see `Traversable`). Parallel sequences have a well defined order for iterators - creating
+ *  an iterator and traversing the elements linearly will always yield the same order.
+ *  However, bulk operations such as `foreach`, `map` or `filter` always occur in undefined orders for all
+ *  parallel collections.
  *
- *  Parallel collections may or may not be strict, and they are not ordered in terms of the `foreach`
- *  operation (see `Traversable`). In terms of the iterator of the collection, some collections
- *  are ordered (for instance, parallel sequences).
+ *  Existing parallel collection implementations provide strict parallel iterators. Strict parallel iterators are aware
+ *  of the number of elements they have yet to traverse. It's also possible to provide non-strict parallel iterators,
+ *  which do not know the number of elements remaining. To do this, the new collection implementation must override
+ *  `isStrictSplitterCollection` to `false`. This will make some operations unavailable.
  *
- *  @author prokopec
- *  @since 2.8
+ *  To create a new parallel collection, extend the `ParIterable` trait, and implement `size`, `parallelIterator`,
+ *  `newCombiner` and `seq`. Having an implicit combiner factory requires extending this trait in addition, as
+ *  well as providing a companion object, as with regular collections.
+ *
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
  *
  *  @define sideeffects
  *  The higher-order functions passed to certain operations may contain side-effects. Since implementations
- *  of operations may not be sequential, this means that side-effects may not be predictable and may
+ *  of bulk operations may not be sequential, this means that side-effects may not be predictable and may
  *  produce data-races, deadlocks or invalidation of state if care is not taken. It is up to the programmer
  *  to either avoid using side-effects or to use some form of synchronization when accessing mutable data.
  *
@@ -112,12 +141,13 @@ import annotation.unchecked.uncheckedVariance
  *  builder for the resulting collection.
  *
  *  @define abortsignalling
- *  This method will provide sequential views it produces with `abort` signalling capabilities. This means
- *  that sequential views may send and read `abort` signals.
+ *  This method will use `abort` signalling capabilities. This means
+ *  that splitters may send and read `abort` signals.
  *
  *  @define indexsignalling
- *  This method will provide sequential views it produces with `indexFlag` signalling capabilities. This means
- *  that sequential views may set and read `indexFlag` state.
+ *  This method will use `indexFlag` signalling capabilities. This means
+ *  that splitters may set and read the `indexFlag` state.
+ *
  */
 trait ParIterableLike[+T, +Repr <: Parallel, +Sequential <: Iterable[T] with IterableLike[T, Sequential]]
 extends IterableLike[T, Repr]
@@ -213,7 +243,7 @@ self =>
    */
   protected[this] override def newBuilder: collection.mutable.Builder[T, Repr] = newCombiner
 
-  /** Optionally reuses existing combiner for better performance. By default it doesn't - subclasses may override this behaviour.
+  /** Optionally reuses an existing combiner for better performance. By default it doesn't - subclasses may override this behaviour.
    *  The provided combiner `oldc` that can potentially be reused will be either some combiner from the previous computational task, or `None` if there
    *  was no previous phase (in which case this method must return `newc`).
    *
@@ -383,7 +413,8 @@ self =>
     executeAndWaitResult(new Aggregate(z, seqop, combop, parallelIterator))
   }
 
-  /** Applies a function `f` to all the elements of $coll.
+  /** Applies a function `f` to all the elements of $coll. Does so in a nondefined order,
+   *  and in parallel.
    *
    *  $undefinedorder
    *
diff --git a/src/library/scala/collection/parallel/ParIterableView.scala b/src/library/scala/collection/parallel/ParIterableView.scala
index 5efe87c9ee..0bcad549a2 100644
--- a/src/library/scala/collection/parallel/ParIterableView.scala
+++ b/src/library/scala/collection/parallel/ParIterableView.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -13,10 +22,11 @@ import scala.collection.generic.CanCombineFrom
 
 /** A template view of a non-strict view of a parallel iterable collection.
  *
- *  @tparam T         ...
- *  @tparam Coll      ...
+ *  @tparam T         the type of elements
+ *  @tparam Coll      the type of the parallel collection this view was created from
+ *  @tparam CollSeq   the type of the sequential collection corresponding to the underlying parallel collection
  *
- *  @since 2.8
+ *  @since 2.9
  */
 trait ParIterableView[+T, +Coll <: Parallel, +CollSeq]
 extends ParIterableViewLike[T, Coll, CollSeq, ParIterableView[T, Coll, CollSeq], IterableView[T, CollSeq]]
diff --git a/src/library/scala/collection/parallel/ParIterableViewLike.scala b/src/library/scala/collection/parallel/ParIterableViewLike.scala
index 6e3d2ff9fe..d34aa10977 100644
--- a/src/library/scala/collection/parallel/ParIterableViewLike.scala
+++ b/src/library/scala/collection/parallel/ParIterableViewLike.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -22,12 +31,12 @@ import scala.collection.parallel.immutable.ParRange
  *  which carries information about the type of the sequential version of the view.
  *
  *  @tparam T         the type of the elements this view can traverse
- *  @tparam Coll      the type of the collection this view is derived from
- *  @tparam CollSeq   TODO
+ *  @tparam Coll      the type of the parallel collection this view is derived from
+ *  @tparam CollSeq   the type of the sequential collection corresponding to the underlying parallel collection
  *  @tparam This      the actual representation type of this view
  *  @tparam ThisSeq   the type of the sequential representation of this view
  *
- *  @since 2.8
+ *  @since 2.9
  */
 trait ParIterableViewLike[+T,
                           +Coll <: Parallel,
diff --git a/src/library/scala/collection/parallel/ParMap.scala b/src/library/scala/collection/parallel/ParMap.scala
index 4b732e6615..e6763ef83c 100644
--- a/src/library/scala/collection/parallel/ParMap.scala
+++ b/src/library/scala/collection/parallel/ParMap.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -15,7 +24,16 @@ import scala.collection.generic.CanCombineFrom
 
 
 
-
+/** A template trait for parallel maps.
+ *
+ *  $sideeffects
+ *
+ *  @tparam K    the key type of the map
+ *  @tparam V    the value type of the map
+ *
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
+ */
 trait ParMap[K, +V]
 extends Map[K, V]
    with GenericParMapTemplate[K, V, ParMap]
diff --git a/src/library/scala/collection/parallel/ParMapLike.scala b/src/library/scala/collection/parallel/ParMapLike.scala
index 9be70d9957..e8f076dc4f 100644
--- a/src/library/scala/collection/parallel/ParMapLike.scala
+++ b/src/library/scala/collection/parallel/ParMapLike.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -14,6 +23,17 @@ import scala.collection.mutable.Builder
 
 
 
+/** A template trait for mutable parallel maps. This trait is to be mixed in
+ *  with concrete parallel maps to override the representation type.
+ *
+ *  $sideeffects
+ *
+ *  @tparam K    the key type of the map
+ *  @tparam V    the value type of the map
+ *
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
+ */
 trait ParMapLike[K,
                  +V,
                  +Repr <: ParMapLike[K, V, Repr, Sequential] with ParMap[K, V],
diff --git a/src/library/scala/collection/parallel/ParSeq.scala b/src/library/scala/collection/parallel/ParSeq.scala
index 970160ec56..89e77b24d7 100644
--- a/src/library/scala/collection/parallel/ParSeq.scala
+++ b/src/library/scala/collection/parallel/ParSeq.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -11,11 +20,16 @@ import scala.collection.parallel.mutable.ParArrayCombiner
 import scala.collection.parallel.mutable.ParArray
 
 
+
 /** A template trait for parallel sequences.
  *
  *  $parallelseqinfo
  *
  *  $sideeffects
+ *
+ *  @tparam T      the type of the elements in this parallel sequence
+ *
+ *  @author Aleksandar Prokopec
  */
 trait ParSeq[+T] extends Seq[T]
                     with ParIterable[T]
diff --git a/src/library/scala/collection/parallel/ParSeqLike.scala b/src/library/scala/collection/parallel/ParSeqLike.scala
index 8a4f15fe6d..9ac647cf5a 100644
--- a/src/library/scala/collection/parallel/ParSeqLike.scala
+++ b/src/library/scala/collection/parallel/ParSeqLike.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -12,29 +21,29 @@ import scala.collection.generic.VolatileAbort
 
 
 
-// TODO update docs!!
 /** A template trait for sequences of type `ParSeq[T]`, representing
  *  parallel sequences with element type `T`.
  *
  *  $parallelseqinfo
  *
- *  @tparam T        the type of the elements contained in this collection
- *  @tparam Repr     the type of the actual collection containing the elements
+ *  @tparam T           the type of the elements contained in this collection
+ *  @tparam Repr        the type of the actual collection containing the elements
+ *  @tparam Sequential  the type of the sequential version of this parallel collection
  *
  *  @define parallelseqinfo
- *  Parallel sequences inherit the `IndexedSeq` trait. This means they provide
- *  efficient indexing and length computations. Like their sequential counterparts
+ *  Parallel sequences inherit the `Seq` trait. Their indexing and length computations
+ *  are defined to be efficient. Like their sequential counterparts
  *  they always have a defined order of elements. This means they will produce resulting
  *  parallel sequences in the same way sequential sequences do. However, the order
- *  in which they iterate over elements to produce results is not defined and is generally
+ *  in which they perform bulk operations on elements to produce results is not defined and is generally
  *  nondeterministic. If the higher-order functions given to them produce no sideeffects,
  *  then this won't be noticeable.
  *
  *  This trait defines a new, more general `split` operation and reimplements the `split`
  *  operation of `ParallelIterable` trait using the new `split` operation.
  *
- *  @author prokopec
- *  @since 2.8
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
  */
 trait ParSeqLike[+T, +Repr <: Parallel, +Sequential <: Seq[T] with SeqLike[T, Sequential]]
 extends scala.collection.SeqLike[T, Repr]
diff --git a/src/library/scala/collection/parallel/ParSeqView.scala b/src/library/scala/collection/parallel/ParSeqView.scala
index f46be33513..6ac24668ca 100644
--- a/src/library/scala/collection/parallel/ParSeqView.scala
+++ b/src/library/scala/collection/parallel/ParSeqView.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -14,10 +23,11 @@ import scala.collection.generic.CanCombineFrom
 
 /** A template view of a non-strict view of a parallel sequence.
  *
- *  @tparam T
- *  @tparam Coll
+ *  @tparam T         the type of elements in this parallel sequence
+ *  @tparam Coll      the type of the underlying parallel collection
+ *  @tparam CollSeq   the type of the sequential collection corresponding to the underlying parallel collection
  *
- *  @since 2.8
+ *  @since 2.9
  */
 trait ParSeqView[+T, +Coll <: Parallel, +CollSeq]
 extends ParSeqViewLike[T, Coll, CollSeq, ParSeqView[T, Coll, CollSeq], SeqView[T, CollSeq]]
diff --git a/src/library/scala/collection/parallel/ParSeqViewLike.scala b/src/library/scala/collection/parallel/ParSeqViewLike.scala
index 7b564a9ad4..e661574c5c 100644
--- a/src/library/scala/collection/parallel/ParSeqViewLike.scala
+++ b/src/library/scala/collection/parallel/ParSeqViewLike.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -20,11 +29,11 @@ import scala.collection.parallel.immutable.ParRange
  *
  *  @tparam T             the type of the elements in this view
  *  @tparam Coll          type of the collection this view is derived from
- *  @tparam CollSeq       TODO
+ *  @tparam CollSeq       type of the sequential collection corresponding to the underlying parallel collection
  *  @tparam This          actual representation type of this view
  *  @tparam ThisSeq       type of the sequential version of this view
  *
- *  @since 2.8
+ *  @since 2.9
  */
 trait ParSeqViewLike[+T,
                      +Coll <: Parallel,
diff --git a/src/library/scala/collection/parallel/ParSet.scala b/src/library/scala/collection/parallel/ParSet.scala
index 0453b8a95e..f3dab8faa9 100644
--- a/src/library/scala/collection/parallel/ParSet.scala
+++ b/src/library/scala/collection/parallel/ParSet.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -15,6 +24,15 @@ import scala.collection.generic._
 
 
 
+/** A template trait for parallel sets.
+ *
+ *  $sideeffects
+ *
+ *  @tparam T    the element type of the set
+ *
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
+ */
 trait ParSet[T]
 extends Set[T]
    with GenericParTemplate[T, ParSet]
diff --git a/src/library/scala/collection/parallel/ParSetLike.scala b/src/library/scala/collection/parallel/ParSetLike.scala
index 272ad0048b..d888d5865f 100644
--- a/src/library/scala/collection/parallel/ParSetLike.scala
+++ b/src/library/scala/collection/parallel/ParSetLike.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -13,6 +22,16 @@ import scala.collection.mutable.Builder
 
 
 
+/** A template trait for parallel sets. This trait is mixed in with concrete
+ *  parallel sets to override the representation type.
+ *
+ *  $sideeffects
+ *
+ *  @tparam T    the element type of the set
+ *
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
+ */
 trait ParSetLike[T,
                  +Repr <: ParSetLike[T, Repr, Sequential] with ParSet[T],
                  +Sequential <: Set[T] with SetLike[T, Sequential]]
diff --git a/src/library/scala/collection/parallel/RemainsIterator.scala b/src/library/scala/collection/parallel/RemainsIterator.scala
index 3363186b7d..3033511519 100644
--- a/src/library/scala/collection/parallel/RemainsIterator.scala
+++ b/src/library/scala/collection/parallel/RemainsIterator.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -12,7 +21,7 @@ import scala.collection.parallel.immutable.repetition
 
 
 
-trait RemainsIterator[+T] extends Iterator[T] {
+private[collection] trait RemainsIterator[+T] extends Iterator[T] {
   /** The number of elements this iterator has yet to iterate.
    *  This method doesn't change the state of the iterator.
    */
@@ -26,7 +35,7 @@ trait RemainsIterator[+T] extends Iterator[T] {
  *  @param T          type of the elements iterated.
  *  @param IterRepr   iterator type.
  */
-trait AugmentedIterableIterator[+T] extends RemainsIterator[T] {
+private[collection] trait AugmentedIterableIterator[+T] extends RemainsIterator[T] {
 
   /* accessors */
 
@@ -358,6 +367,11 @@ trait AugmentedSeqIterator[+T] extends AugmentedIterableIterator[T] {
 }
 
 
+/** Parallel iterators allow splitting and provide a `remaining` method to
+ *  obtain the number of elements remaining in the iterator.
+ *
+ *  @param T          type of the elements iterated.
+ */
 trait ParIterableIterator[+T]
 extends AugmentedIterableIterator[T]
    with Splitter[T]
@@ -500,6 +514,10 @@ self =>
 }
 
 
+/** Parallel sequence iterators allow splitting into arbitrary subsets.
+ *
+ *  @param T          type of the elements iterated.
+ */
 trait ParSeqIterator[+T]
 extends ParIterableIterator[T]
    with AugmentedSeqIterator[T]
diff --git a/src/library/scala/collection/parallel/Splitter.scala b/src/library/scala/collection/parallel/Splitter.scala
index e598b96c82..7328f3db6c 100644
--- a/src/library/scala/collection/parallel/Splitter.scala
+++ b/src/library/scala/collection/parallel/Splitter.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -7,10 +16,10 @@ import scala.collection.Seq
 /** A splitter (or a split iterator) can be split into more splitters that traverse over
  *  disjoint subsets of elements.
  *
- *  @tparam T    type of the elements this parallel iterator traverses
+ *  @tparam T    type of the elements this splitter traverses
  *
- *  @since 2.8.1
- *  @author prokopec
+ *  @since 2.9
+ *  @author Aleksandar Prokopec
  */
 trait Splitter[+T] extends Iterator[T] {
 
@@ -19,13 +28,13 @@ trait Splitter[+T] extends Iterator[T] {
    *  Returns a sequence of split iterators, each iterating over some subset of the
    *  elements in the collection. These subsets are disjoint and should be approximately
    *  equal in size. These subsets are not empty, unless the iterator is empty in which
-   *  case this method returns a sequence with a single empty iterator. If the iterator has
-   *  more than two elements, this method will return two or more iterators.
+   *  case this method returns a sequence with a single empty iterator. If the splitter has
+   *  more than two elements, this method will return two or more splitters.
    *
-   *  Implementors are advised to keep this partition relatively small - two iterators are
+   *  Implementors are advised to keep this partition relatively small - two splitters are
    *  already enough when partitioning the collection, although there may be a few more.
    *
-   *  '''Note:''' this method actually invalidates the current iterator.
+   *  '''Note:''' this method actually invalidates the current splitter.
    *
    *  @return a sequence of disjunct iterators of the collection
    */
@@ -59,37 +68,37 @@ object Splitter {
  *
  *  Implementors might want to override the parameterless `split` method for efficiency.
  *
- *  @tparam T     type of the elements this parallel iterator traverses
+ *  @tparam T     type of the elements this splitter traverses
  *
- *  @since 2.8.1
- *  @author prokopec
+ *  @since 2.9
+ *  @author Aleksandar Prokopec
  */
 trait PreciseSplitter[+T] extends Splitter[T] {
 
-  /** Splits the iterator into disjunct views.
+  /** Splits the splitter into disjunct views.
    *
-   *  This overloaded version of the `split` method is specific to precise parallel iterators.
-   *  It returns a sequence of parallel iterators, each iterating some subset of the
-   *  elements in this iterator. The sizes of the subiterators in the partition is equal to
+   *  This overloaded version of the `split` method is specific to precise splitters.
+   *  It returns a sequence of splitters, each iterating some subset of the
+   *  elements in this splitter. The sizes of the subsplitters in the partition is equal to
    *  the size in the corresponding argument, as long as there are enough elements in this
-   *  iterator to split it that way.
+   *  splitter to split it that way.
    *
-   *  If there aren't enough elements, a zero element iterator is appended for each additional argument.
-   *  If there are additional elements, an additional iterator is appended at the end to compensate.
+   *  If there aren't enough elements, a zero element splitter is appended for each additional argument.
+   *  If there are additional elements, an additional splitter is appended at the end to compensate.
    *
-   *  For example, say we have a parallel iterator `ps` with 100 elements. Invoking:
+   *  For example, say we have a splitter `ps` with 100 elements. Invoking:
    *  {{{
    *    ps.split(50, 25, 25, 10, 5)
    *  }}}
-   *  will return a sequence of five iterators, last two views being empty. On the other hand, calling:
+   *  will return a sequence of five splitters, last two views being empty. On the other hand, calling:
    *  {{{
    *    ps.split(50, 40)
    *  }}}
-   *  will return a sequence of three iterators, last of them containing ten elements.
+   *  will return a sequence of three splitters, last of them containing ten elements.
    *
-   *  '''Note:''' this method actually invalidates the current iterator.
+   *  '''Note:''' this method actually invalidates the current splitter.
    *
-   *  Unlike the case with `split` found in parallel iterable iterators, views returned by this method can be empty.
+   *  Unlike the case with `split` found in splitters, views returned by this method can be empty.
    *
    *  @param sizes   the sizes used to split this split iterator into iterators that traverse disjunct subsets
    *  @return        a sequence of disjunct subsequence iterators of this parallel iterator
diff --git a/src/library/scala/collection/parallel/TaskSupport.scala b/src/library/scala/collection/parallel/TaskSupport.scala
index 1b1ee6e469..20800250b4 100644
--- a/src/library/scala/collection/parallel/TaskSupport.scala
+++ b/src/library/scala/collection/parallel/TaskSupport.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -8,9 +17,9 @@ package scala.collection.parallel
 
 trait TaskSupport extends Tasks
 
-class ForkJoinTaskSupport extends TaskSupport with AdaptiveWorkStealingForkJoinTasks
+private[collection] class ForkJoinTaskSupport extends TaskSupport with AdaptiveWorkStealingForkJoinTasks
 
-class ThreadPoolTaskSupport extends TaskSupport with AdaptiveWorkStealingThreadPoolTasks
+private[collection] class ThreadPoolTaskSupport extends TaskSupport with AdaptiveWorkStealingThreadPoolTasks
 
 
 
diff --git a/src/library/scala/collection/parallel/Tasks.scala b/src/library/scala/collection/parallel/Tasks.scala
index 13a41eb7d4..6f00547925 100644
--- a/src/library/scala/collection/parallel/Tasks.scala
+++ b/src/library/scala/collection/parallel/Tasks.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
@@ -13,10 +22,7 @@ import annotation.unchecked.uncheckedVariance
 
 
 /** A trait that declares task execution capabilities used
- *  by parallel collections. Parallel collections inherit a subtrait
- *  of this trait.
- *
- *  One implementation trait of `TaskExecution` is `ForkJoinTaskExecution`.
+ *  by parallel collections.
  */
 trait Tasks {
 
@@ -214,6 +220,7 @@ trait AdaptiveWorkStealingTasks extends Tasks {
 }
 
 
+/** An implementation of tasks objects based on the Java thread pooling API. */
 trait ThreadPoolTasks extends Tasks {
   import java.util.concurrent._
 
diff --git a/src/library/scala/collection/parallel/immutable/ParHashMap.scala b/src/library/scala/collection/parallel/immutable/ParHashMap.scala
index 446d87348b..66b981e8c4 100644
--- a/src/library/scala/collection/parallel/immutable/ParHashMap.scala
+++ b/src/library/scala/collection/parallel/immutable/ParHashMap.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel.immutable
 
 
@@ -23,9 +32,20 @@ import annotation.unchecked.uncheckedVariance
 
 
 
-/** Parallel hash trie map.
+/** Immutable parallel hash map, based on hash tries.
+ *
+ *  $paralleliterableinfo
+ *
+ *  $sideeffects
  *
- *  @author prokopec
+ *  @tparam K    the key type of the map
+ *  @tparam V    the value type of the map
+ *
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
+ *
+ *  @define Coll immutable.ParHashMap
+ *  @define coll immutable parallel hash map
  */
 @SerialVersionUID(1L)
 class ParHashMap[K, +V] private[immutable] (private[this] val trie: HashMap[K, V])
@@ -126,6 +146,10 @@ self =>
 }
 
 
+/** $factoryinfo
+ *  @define Coll immutable.ParHashMap
+ *  @define coll immutable parallel hash map
+ */
 object ParHashMap extends ParMapFactory[ParHashMap] {
   def empty[K, V]: ParHashMap[K, V] = new ParHashMap[K, V]
 
diff --git a/src/library/scala/collection/parallel/immutable/ParHashSet.scala b/src/library/scala/collection/parallel/immutable/ParHashSet.scala
index 77dd947201..bd9cefa298 100644
--- a/src/library/scala/collection/parallel/immutable/ParHashSet.scala
+++ b/src/library/scala/collection/parallel/immutable/ParHashSet.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel.immutable
 
 
@@ -24,9 +33,19 @@ import scala.collection.immutable.HashSet
 
 
 
-/** Parallel hash trie set.
+/** Immutable parallel hash set, based on hash tries.
+ *
+ *  $paralleliterableinfo
+ *
+ *  $sideeffects
  *
- *  @author prokopec
+ *  @tparam T    the element type of the set
+ *
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
+ *
+ *  @define Coll immutable.ParHashSet
+ *  @define coll immutable parallel hash set
  */
 @SerialVersionUID(1L)
 class ParHashSet[T] private[immutable] (private[this] val trie: HashSet[T])
@@ -108,6 +127,10 @@ self =>
 }
 
 
+/** $factoryinfo
+ *  @define Coll immutable.ParHashSet
+ *  @define coll immutable parallel hash set
+ */
 object ParHashSet extends ParSetFactory[ParHashSet] {
   def newCombiner[T]: Combiner[T, ParHashSet[T]] = HashSetCombiner[T]
 
diff --git a/src/library/scala/collection/parallel/immutable/ParIterable.scala b/src/library/scala/collection/parallel/immutable/ParIterable.scala
index 00a8c02fd6..0118452cb8 100644
--- a/src/library/scala/collection/parallel/immutable/ParIterable.scala
+++ b/src/library/scala/collection/parallel/immutable/ParIterable.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection
 package parallel.immutable
 
@@ -14,10 +23,10 @@ import scala.collection.parallel.Combiner
  *
  *  $sideeffects
  *
- *  @tparam A    the element type of the collection
+ *  @tparam T    the element type of the collection
  *
- *  @author prokopec
- *  @since 2.8
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
  */
 trait ParIterable[+T]
 extends collection.immutable.Iterable[T]
diff --git a/src/library/scala/collection/parallel/immutable/ParMap.scala b/src/library/scala/collection/parallel/immutable/ParMap.scala
index c06891c459..d99091c57c 100644
--- a/src/library/scala/collection/parallel/immutable/ParMap.scala
+++ b/src/library/scala/collection/parallel/immutable/ParMap.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection
 package parallel.immutable
 
@@ -16,6 +25,16 @@ import scala.collection.parallel.Combiner
 
 
 
+/** A template trait for immutable parallel maps.
+ *
+ *  $sideeffects
+ *
+ *  @tparam K    the key type of the map
+ *  @tparam V    the value type of the map
+ *
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
+ */
 trait ParMap[K, +V]
 extends Map[K, V]
    with GenericParMapTemplate[K, V, ParMap]
diff --git a/src/library/scala/collection/parallel/immutable/ParRange.scala b/src/library/scala/collection/parallel/immutable/ParRange.scala
index 2456c2beda..19d2a6d3b8 100644
--- a/src/library/scala/collection/parallel/immutable/ParRange.scala
+++ b/src/library/scala/collection/parallel/immutable/ParRange.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel.immutable
 
 
@@ -9,6 +18,20 @@ import scala.collection.parallel.ParIterableIterator
 
 
 
+/** Parallel ranges.
+ *
+ *  $paralleliterableinfo
+ *
+ *  $sideeffects
+ *
+ *  @param range    the sequential range this parallel range was obtained from
+ *
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
+ *
+ *  @define Coll immutable.ParRange
+ *  @define coll immutable parallel range
+ */
 @SerialVersionUID(1L)
 class ParRange(val range: Range)
 extends ParSeq[Int]
diff --git a/src/library/scala/collection/parallel/immutable/ParSeq.scala b/src/library/scala/collection/parallel/immutable/ParSeq.scala
index 68ed9a3139..dbb37a9c69 100644
--- a/src/library/scala/collection/parallel/immutable/ParSeq.scala
+++ b/src/library/scala/collection/parallel/immutable/ParSeq.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection
 package parallel.immutable
 
diff --git a/src/library/scala/collection/parallel/immutable/ParSet.scala b/src/library/scala/collection/parallel/immutable/ParSet.scala
index 5f9e4eee8a..2002d6432d 100644
--- a/src/library/scala/collection/parallel/immutable/ParSet.scala
+++ b/src/library/scala/collection/parallel/immutable/ParSet.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection
 package parallel.immutable
 
@@ -14,6 +23,11 @@ import scala.collection.parallel.Combiner
 
 
 
+/** An immutable variant of `ParSet`.
+ *
+ *  @define Coll mutable.ParSet
+ *  @define coll mutable parallel set
+ */
 trait ParSet[T]
 extends Set[T]
    with GenericParTemplate[T, ParSet]
@@ -34,6 +48,10 @@ self =>
 
 
 
+/** $factoryInfo
+ *  @define Coll mutable.ParSet
+ *  @define coll mutable parallel set
+ */
 object ParSet extends ParSetFactory[ParSet] {
   def newCombiner[T]: Combiner[T, ParSet[T]] = HashSetCombiner[T]
 
diff --git a/src/library/scala/collection/parallel/immutable/ParVector.scala b/src/library/scala/collection/parallel/immutable/ParVector.scala
index 663621e060..f79ba2a7f9 100644
--- a/src/library/scala/collection/parallel/immutable/ParVector.scala
+++ b/src/library/scala/collection/parallel/immutable/ParVector.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection
 package parallel.immutable
 
@@ -16,6 +25,20 @@ import immutable.VectorIterator
 
 
 
+/** Immutable parallel vectors, based on vectors.
+ *
+ *  $paralleliterableinfo
+ *
+ *  $sideeffects
+ *
+ *  @tparam T    the element type of the vector
+ *
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
+ *
+ *  @define Coll immutable.ParVector
+ *  @define coll immutable parallel vector
+ */
 class ParVector[+T](private[this] val vector: Vector[T])
 extends ParSeq[T]
    with GenericParTemplate[T, ParVector]
@@ -61,6 +84,10 @@ extends ParSeq[T]
 
 
 
+/** $factoryInfo
+ *  @define Coll immutable.ParVector
+ *  @define coll immutable parallel vector
+ */
 object ParVector extends ParFactory[ParVector] {
   implicit def canBuildFrom[T]: CanCombineFrom[Coll, T, ParVector[T]] =
     new GenericCanCombineFrom[T]
diff --git a/src/library/scala/collection/parallel/immutable/package.scala b/src/library/scala/collection/parallel/immutable/package.scala
index 142e554178..8bb0b2216d 100644
--- a/src/library/scala/collection/parallel/immutable/package.scala
+++ b/src/library/scala/collection/parallel/immutable/package.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 
 
diff --git a/src/library/scala/collection/parallel/mutable/LazyCombiner.scala b/src/library/scala/collection/parallel/mutable/LazyCombiner.scala
index 955698fdd4..8f7a62aa4f 100644
--- a/src/library/scala/collection/parallel/mutable/LazyCombiner.scala
+++ b/src/library/scala/collection/parallel/mutable/LazyCombiner.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel.mutable
 
 
diff --git a/src/library/scala/collection/parallel/mutable/ParArray.scala b/src/library/scala/collection/parallel/mutable/ParArray.scala
index ccd693a241..bf5cbf9a1e 100644
--- a/src/library/scala/collection/parallel/mutable/ParArray.scala
+++ b/src/library/scala/collection/parallel/mutable/ParArray.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel.mutable
 
 
@@ -25,17 +34,18 @@ import scala.collection.Sequentializable
  *  cannot be changed after it's been created.
  *
  *  `ParArray` internally keeps an array containing the elements. This means that
- *  bulk operations based on traversal are fast, but those returning a parallel array as a result
- *  are slightly slower. The reason for this is that `ParArray` uses lazy builders that
- *  create the internal data array only after the size of the array is known. The fragments
- *  are then copied into the resulting data array in parallel using fast array copy operations.
- *  Operations for which the resulting array size is known in advance are optimised to use this
- *  information.
+ *  bulk operations based on traversal ensure fast access to elements. `ParArray` uses lazy builders that
+ *  create the internal data array only after the size of the array is known. In the meantime, they keep
+ *  the result set fragmented. The fragments
+ *  are copied into the resulting data array in parallel using fast array copy operations once all the combiners
+ *  are populated in parallel.
  *
  *  @tparam T        type of the elements in the array
  *
  *  @define Coll ParArray
  *  @define coll parallel array
+ *
+ *  @author Aleksandar Prokopec
  */
 @SerialVersionUID(1L)
 class ParArray[T] private[mutable] (val arrayseq: ArraySeq[T])
@@ -673,9 +683,10 @@ self =>
 }
 
 
-
-
-
+/** $factoryinfo
+ *  @define Coll mutable.ParArray
+ *  @define coll parallel array
+ */
 object ParArray extends ParFactory[ParArray] {
   implicit def canBuildFrom[T]: CanCombineFrom[Coll, T, ParArray[T]] = new GenericCanCombineFrom[T]
   def newBuilder[T]: Combiner[T, ParArray[T]] = newCombiner
diff --git a/src/library/scala/collection/parallel/mutable/ParFlatHashTable.scala b/src/library/scala/collection/parallel/mutable/ParFlatHashTable.scala
index 82c69b4c53..8929c978b6 100644
--- a/src/library/scala/collection/parallel/mutable/ParFlatHashTable.scala
+++ b/src/library/scala/collection/parallel/mutable/ParFlatHashTable.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection
 package parallel.mutable
 
@@ -9,6 +18,12 @@ import collection.parallel.ParIterableIterator
 
 
 
+/** Parallel flat hash table.
+ *
+ *  @tparam T        type of the elements in the table
+ *
+ *  @author Aleksandar Prokopec
+ */
 trait ParFlatHashTable[T] extends collection.mutable.FlatHashTable[T] {
 
   override def alwaysInitSizeMap = true
diff --git a/src/library/scala/collection/parallel/mutable/ParHashMap.scala b/src/library/scala/collection/parallel/mutable/ParHashMap.scala
index 4db3d89291..4dcf263fc5 100644
--- a/src/library/scala/collection/parallel/mutable/ParHashMap.scala
+++ b/src/library/scala/collection/parallel/mutable/ParHashMap.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 package mutable
 
@@ -12,6 +21,18 @@ import collection.mutable.UnrolledBuffer
 
 
 
+/** A parallel hash map.
+ *
+ *  `ParHashMap` is a parallel map which internally keeps elements within a hash table.
+ *  It uses chaining to resolve collisions.
+ *
+ *  @tparam T        type of the elements in the parallel hash map
+ *
+ *  @define Coll ParHashMap
+ *  @define coll parallel hash map
+ *
+ *  @author Aleksandar Prokopec
+ */
 @SerialVersionUID(1L)
 class ParHashMap[K, V] private[collection] (contents: HashTable.Contents[K, DefaultEntry[K, V]])
 extends ParMap[K, V]
@@ -118,6 +139,10 @@ self =>
 }
 
 
+/** $factoryinfo
+ *  @define Coll mutable.ParHashMap
+ *  @define coll parallel hash map
+ */
 object ParHashMap extends ParMapFactory[ParHashMap] {
   var iters = 0
 
diff --git a/src/library/scala/collection/parallel/mutable/ParHashSet.scala b/src/library/scala/collection/parallel/mutable/ParHashSet.scala
index 4065baec06..d22e0e8abd 100644
--- a/src/library/scala/collection/parallel/mutable/ParHashSet.scala
+++ b/src/library/scala/collection/parallel/mutable/ParHashSet.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel.mutable
 
 
@@ -13,6 +22,18 @@ import collection.mutable.UnrolledBuffer
 
 
 
+/** A parallel hash set.
+ *
+ *  `ParHashSet` is a parallel set which internally keeps elements within a hash table.
+ *  It uses linear probing to resolve collisions.
+ *
+ *  @tparam T        type of the elements in the parallel hash map
+ *
+ *  @define Coll ParHashMap
+ *  @define coll parallel hash map
+ *
+ *  @author Aleksandar Prokopec
+ */
 @SerialVersionUID(1L)
 class ParHashSet[T] private[collection] (contents: FlatHashTable.Contents[T])
 extends ParSet[T]
@@ -86,8 +107,8 @@ extends ParSet[T]
 
 
 /** $factoryInfo
- *  @define Coll mutable.ParSet
- *  @define coll mutable parallel set
+ *  @define Coll mutable.ParHashSet
+ *  @define coll parallel hash set
  */
 object ParHashSet extends ParSetFactory[ParHashSet] {
   implicit def canBuildFrom[T]: CanCombineFrom[Coll, T, ParHashSet[T]] = new GenericCanCombineFrom[T]
diff --git a/src/library/scala/collection/parallel/mutable/ParHashTable.scala b/src/library/scala/collection/parallel/mutable/ParHashTable.scala
index b238ce09de..be1cbf1333 100644
--- a/src/library/scala/collection/parallel/mutable/ParHashTable.scala
+++ b/src/library/scala/collection/parallel/mutable/ParHashTable.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection
 package parallel.mutable
 
diff --git a/src/library/scala/collection/parallel/mutable/ParIterable.scala b/src/library/scala/collection/parallel/mutable/ParIterable.scala
index 5049e3507a..eba4ff2e72 100644
--- a/src/library/scala/collection/parallel/mutable/ParIterable.scala
+++ b/src/library/scala/collection/parallel/mutable/ParIterable.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel.mutable
 
 
@@ -7,7 +16,7 @@ import scala.collection.parallel.ParIterableLike
 import scala.collection.parallel.Combiner
 
 
-/** A template trait for parallel iterable collections.
+/** A template trait for mutable parallel iterable collections.
  *
  *  $paralleliterableinfo
  *
@@ -15,8 +24,8 @@ import scala.collection.parallel.Combiner
  *
  *  @tparam T    the element type of the collection
  *
- *  @author prokopec
- *  @since 2.8
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
  */
 trait ParIterable[T] extends collection.mutable.Iterable[T]
                         with collection.parallel.ParIterable[T]
diff --git a/src/library/scala/collection/parallel/mutable/ParMap.scala b/src/library/scala/collection/parallel/mutable/ParMap.scala
index cb6014289d..f4fa7303c4 100644
--- a/src/library/scala/collection/parallel/mutable/ParMap.scala
+++ b/src/library/scala/collection/parallel/mutable/ParMap.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel.mutable
 
 
@@ -8,6 +17,16 @@ import collection.parallel.Combiner
 
 
 
+/** A template trait for mutable parallel maps.
+ *
+ *  $sideeffects
+ *
+ *  @tparam K    the key type of the map
+ *  @tparam V    the value type of the map
+ *
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
+ */
 trait ParMap[K, V]
 extends collection.mutable.Map[K, V]
    with collection.parallel.ParMap[K, V]
diff --git a/src/library/scala/collection/parallel/mutable/ParMapLike.scala b/src/library/scala/collection/parallel/mutable/ParMapLike.scala
index 25b5c3b5f7..cd2bea1419 100644
--- a/src/library/scala/collection/parallel/mutable/ParMapLike.scala
+++ b/src/library/scala/collection/parallel/mutable/ParMapLike.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel
 package mutable
 
@@ -8,6 +17,17 @@ import collection.mutable.Builder
 
 
 
+/** A template trait for mutable parallel maps. This trait is to be mixed in
+ *  with concrete parallel maps to override the representation type.
+ *
+ *  $sideeffects
+ *
+ *  @tparam K    the key type of the map
+ *  @tparam V    the value type of the map
+ *
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
+ */
 trait ParMapLike[K,
                  V,
                  +Repr <: ParMapLike[K, V, Repr, Sequential] with ParMap[K, V],
diff --git a/src/library/scala/collection/parallel/mutable/ParSeq.scala b/src/library/scala/collection/parallel/mutable/ParSeq.scala
index a11ebf42d9..10d3033701 100644
--- a/src/library/scala/collection/parallel/mutable/ParSeq.scala
+++ b/src/library/scala/collection/parallel/mutable/ParSeq.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel.mutable
 
 
diff --git a/src/library/scala/collection/parallel/mutable/ParSet.scala b/src/library/scala/collection/parallel/mutable/ParSet.scala
index e700bd97d7..b7f4b61d66 100644
--- a/src/library/scala/collection/parallel/mutable/ParSet.scala
+++ b/src/library/scala/collection/parallel/mutable/ParSet.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection.parallel.mutable
 
 
diff --git a/src/library/scala/collection/parallel/mutable/ParSetLike.scala b/src/library/scala/collection/parallel/mutable/ParSetLike.scala
index d3fab5a4db..df87eff42c 100644
--- a/src/library/scala/collection/parallel/mutable/ParSetLike.scala
+++ b/src/library/scala/collection/parallel/mutable/ParSetLike.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection
 package parallel.mutable
 
@@ -13,6 +22,16 @@ import scala.collection.mutable.Builder
 
 
 
+/** A template trait for mutable parallel sets. This trait is mixed in with concrete
+ *  parallel sets to override the representation type.
+ *
+ *  $sideeffects
+ *
+ *  @tparam T    the element type of the set
+ *
+ *  @author Aleksandar Prokopec
+ *  @since 2.9
+ */
 trait ParSetLike[T,
                  +Repr <: ParSetLike[T, Repr, Sequential] with ParSet[T],
                  +Sequential <: mutable.Set[T] with mutable.SetLike[T, Sequential]]
diff --git a/src/library/scala/collection/parallel/package.scala b/src/library/scala/collection/parallel/package.scala
index 67b60ad129..db7e5c75ba 100644
--- a/src/library/scala/collection/parallel/package.scala
+++ b/src/library/scala/collection/parallel/package.scala
@@ -1,3 +1,12 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2011, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+
 package scala.collection