Doing a little polishing on the parallel collec...

Doing a little polishing on the parallel collections refactor (which
overall looks like a big improvement.) I went for some simpler wording
and moved a number of scaladoc tags around because the rug had been
pulled out from under their feet.

This leaves a lot undone, but since many of the docs need to be reworded
before they can move from e.g. SeqLike to GenSeqLike, and I'm not well
informed on exactly how these abstractions are being presented, I stayed
in the safe zone. Review by prokopec.

15 files changed, 67 insertions, 91 deletions

diff --git a/src/library/scala/collection/GenIterableLike.scala b/src/library/scala/collection/GenIterableLike.scala
index d268d042a2..61e8b0d349 100644
--- a/src/library/scala/collection/GenIterableLike.scala
+++ b/src/library/scala/collection/GenIterableLike.scala
@@ -8,11 +8,7 @@
 
 package scala.collection
 
-
-
-import generic._
-
-
+import generic.{ CanBuildFrom => CBF, _ }
 
 /** A template trait for all iterable collections which may possibly
  *  have their operations implemented in parallel.
@@ -30,14 +26,13 @@ trait GenIterableLike[+A, +Repr] extends GenTraversableLike[A, Repr] {
 
   def sameElements[A1 >: A](that: GenIterable[A1]): Boolean
 
-  def zip[A1 >: A, B, That](that: GenIterable[B])(implicit bf: CanBuildFrom[Repr, (A1, B), That]): That
+  def zip[A1 >: A, B, That](that: GenIterable[B])(implicit bf: CBF[Repr, (A1, B), That]): That
 
-  def zipWithIndex[A1 >: A, That](implicit bf: CanBuildFrom[Repr, (A1, Int), That]): That
+  def zipWithIndex[A1 >: A, That](implicit bf: CBF[Repr, (A1, Int), That]): That
 
-  def zipAll[B, A1 >: A, That](that: GenIterable[B], thisElem: A1, thatElem: B)(implicit bf: CanBuildFrom[Repr, (A1, B), That]): That
+  def zipAll[B, A1 >: A, That](that: GenIterable[B], thisElem: A1, thatElem: B)(implicit bf: CBF[Repr, (A1, B), That]): That
 
   def isEmpty = iterator.isEmpty
 
   def head = iterator.next
-
 }
diff --git a/src/library/scala/collection/GenMap.scala b/src/library/scala/collection/GenMap.scala
index 06e4446d05..7e7b6c7fb0 100644
--- a/src/library/scala/collection/GenMap.scala
+++ b/src/library/scala/collection/GenMap.scala
@@ -8,9 +8,7 @@
 
 package scala.collection
 
-
 import generic._
-import mutable.Builder
 
 
 /** A trait for all traversable collections which may possibly
diff --git a/src/library/scala/collection/GenMapLike.scala b/src/library/scala/collection/GenMapLike.scala
index 213b1cf66b..5631ae96d4 100644
--- a/src/library/scala/collection/GenMapLike.scala
+++ b/src/library/scala/collection/GenMapLike.scala
@@ -8,11 +8,8 @@
 
 package scala.collection
 
-
-
-
-/** A trait for all traversable collections which may possibly
- *  have their operations implemented in parallel.
+/** A trait for all maps upon which operations may be
+ *  implemented in parallel.
  *
  *  @author Martin Odersky
  *  @author Aleksandar Prokopec
diff --git a/src/library/scala/collection/GenSeqLike.scala b/src/library/scala/collection/GenSeqLike.scala
index 74804faff5..8dcd5936d5 100644
--- a/src/library/scala/collection/GenSeqLike.scala
+++ b/src/library/scala/collection/GenSeqLike.scala
@@ -8,14 +8,17 @@
 
 package scala.collection
 
-
-
 import generic._
 
-
-
-/** A template trait for all sequences which may possibly
- *  have their operations implemented in parallel.
+/** A template trait for all sequences which may be traversed
+ *  in parallel.
+ *
+ *  @define mayNotTerminateInf
+ *
+ *    Note: may not terminate for infinite-sized collections.
+ *  @define willNotTerminateInf
+ *
+ *    Note: will not terminate for infinite-sized collections.
  *
  *  @author Martin Odersky
  *  @author Aleksandar Prokopec
diff --git a/src/library/scala/collection/GenSetLike.scala b/src/library/scala/collection/GenSetLike.scala
index 91e90c1499..dc4a82688c 100644
--- a/src/library/scala/collection/GenSetLike.scala
+++ b/src/library/scala/collection/GenSetLike.scala
@@ -6,12 +6,8 @@
 **                          |/                                          **
 \*                                                                      */
 
-
 package scala.collection
 
-
-
-
 /** A template trait for sets which may possibly
  *  have their operations implemented in parallel.
  *
@@ -19,12 +15,19 @@ package scala.collection
  *  @author Aleksandar Prokopec
  *  @since 2.9
  */
-trait GenSetLike[A, +Repr] extends GenIterableLike[A, Repr] with (A => Boolean) with Equals with Parallelizable[A, parallel.ParSet[A]] {
-  def seq: Set[A]
+trait GenSetLike[A, +Repr]
+       extends GenIterableLike[A, Repr]
+          with (A => Boolean)
+          with Equals
+          with Parallelizable[A, parallel.ParSet[A]] {
+
+  def iterator: Iterator[A]
   def contains(elem: A): Boolean
   def +(elem: A): Repr
   def -(elem: A): Repr
 
+  def seq: Set[A]
+
   /** Tests if some element is contained in this set.
    *
    *  This method is equivalent to `contains`. It allows sets to be interpreted as predicates.
diff --git a/src/library/scala/collection/GenTraversableLike.scala b/src/library/scala/collection/GenTraversableLike.scala
index 5c49df2461..c284efd9d4 100644
--- a/src/library/scala/collection/GenTraversableLike.scala
+++ b/src/library/scala/collection/GenTraversableLike.scala
@@ -8,14 +8,37 @@
 
 package scala.collection
 
-
-
 import generic._
 
-
-
-/** A template trait for all traversable collections which may possibly
- *  have their operations implemented in parallel.
+/** A template trait for all traversable collections upon which operations
+ *  may be implemented in parallel.
+ *
+ *  @define thatinfo the class of the returned collection. Where possible, `That` is
+ *    the same class as the current collection class `Repr`, but this
+ *    depends on the element type `B` being admissible for that class,
+ *    which means that an implicit instance of type `CanBuildFrom[Repr, B, That]`
+ *    is found.
+ *  @define bfinfo an implicit value of class `CanBuildFrom` which determines
+ *    the result class `That` from the current representation type `Repr` and
+ *    and the new element type `B`.
+ *  @define orderDependent
+ *
+ *    Note: might return different results for different runs, unless the underlying collection type is ordered.
+ *  @define orderDependentFold
+ *
+ *    Note: might return different results for different runs, unless the underlying collection type is ordered.
+ *    or the operator is associative and commutative.
+ *  @define mayNotTerminateInf
+ *
+ *    Note: may not terminate for infinite-sized collections.
+ *  @define willNotTerminateInf
+ *
+ *    Note: will not terminate for infinite-sized collections.
+ *
+ *  @define Coll GenTraversable
+ *  @define coll collection
+ *  @tparam T    the collection element type.
+ *  @tparam Repr the actual type of the element container.
  *
  *  @author Martin Odersky
  *  @author Aleksandar Prokopec
diff --git a/src/library/scala/collection/GenTraversableOnce.scala b/src/library/scala/collection/GenTraversableOnce.scala
index 04825148bd..41dfa96e93 100644
--- a/src/library/scala/collection/GenTraversableOnce.scala
+++ b/src/library/scala/collection/GenTraversableOnce.scala
@@ -8,11 +8,8 @@
 
 package scala.collection
 
-
-
-
-/** A trait for all objects traversable once or more which may possibly
- *  have their traversal occur in parallel.
+/** A trait for all traversable-once objects which may be
+ *  traversed in parallel.
  *
  *  @author Martin Odersky
  *  @author Aleksandar Prokopec
diff --git a/src/library/scala/collection/GenTraversableOnceLike.scala b/src/library/scala/collection/GenTraversableOnceLike.scala
index d81f26649e..dcc9ba805e 100644
--- a/src/library/scala/collection/GenTraversableOnceLike.scala
+++ b/src/library/scala/collection/GenTraversableOnceLike.scala
@@ -8,21 +8,22 @@
 
 package scala.collection
 
-
-
-
-/** A template trait for all objects traversable once or more which may possibly
- *  have their traversal occur in parallel.
+/** A template trait for all traversable-once objects which may be
+ *  traversed in parallel.
  *
  *  Methods in this trait are either abstract or can be implemented in terms
  *  of other methods.
  *
+ *  @define Coll GenTraversableOnce
+ *  @define coll collection or iterator
+ *  @define possiblyparinfo
+ *  This trait may possibly have operations implemented in parallel.
+ *  @define undefinedorder
+ *  The order in which operations are performed on elements is unspecified and may be nondeterministic.
+ *
  *  @author Martin Odersky
  *  @author Aleksandar Prokopec
  *  @since 2.9
- *
- *  @define possiblyparinfo
- *  This trait may possibly have operations implemented in parallel.
  */
 trait GenTraversableOnceLike[+A] {
 
diff --git a/src/library/scala/collection/SeqLike.scala b/src/library/scala/collection/SeqLike.scala
index 5cfcd85b14..05f89dd098 100644
--- a/src/library/scala/collection/SeqLike.scala
+++ b/src/library/scala/collection/SeqLike.scala
@@ -58,12 +58,6 @@ import parallel.ParSeq
  *    and the new element type `B`.
  *  @define orderDependent
  *  @define orderDependentFold
- *  @define mayNotTerminateInf
- *
- *    Note: may not terminate for infinite-sized collections.
- *  @define willNotTerminateInf
- *
- *    Note: will not terminate for infinite-sized collections.
  */
 trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr] with Parallelizable[A, ParSeq[A]] { self =>
 
diff --git a/src/library/scala/collection/Set.scala b/src/library/scala/collection/Set.scala
index c7d42a4632..7241d7fb3a 100644
--- a/src/library/scala/collection/Set.scala
+++ b/src/library/scala/collection/Set.scala
@@ -14,13 +14,12 @@ import generic._
 /** A base trait for all sets, mutable as well as immutable.
  *
  * $setNote
- * $setNote2
+ * '''Implementation note:''' If your additions and mutations return the same kind of set as the set
+ *       you are defining, you should inherit from `SetLike` as well.
  * $setTags
+ *
  * @since 1.0
  * @author Matthias Zenger
- * @define setNote2
- * '''Implementation note:''' If your additions and mutations return the same kind of set as the set
- *       you are defining, you should inherit from `SetLike` as well.
  */
 trait Set[A] extends (A => Boolean)
                 with Iterable[A]
diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index 3f67788b59..5dc38e2043 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -6,8 +6,6 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.collection
 
 import generic._
@@ -17,7 +15,6 @@ import annotation.migration
 import annotation.unchecked.{ uncheckedVariance => uV }
 import parallel.ParIterable
 
-
 /** A template trait for traversable collections of type `Traversable[A]`.
  *
  *  $traversableInfo
@@ -68,27 +65,6 @@ import parallel.ParIterable
  *
  *  @define Coll Traversable
  *  @define coll traversable collection
- *  @define thatinfo the class of the returned collection. Where possible, `That` is
- *    the same class as the current collection class `Repr`, but this
- *    depends on the element type `B` being admissible for that class,
- *    which means that an implicit instance of type `CanBuildFrom[Repr, B, That]`
- *    is found.
- *  @define bfinfo an implicit value of class `CanBuildFrom` which determines
- *    the result class `That` from the current representation type `Repr` and
- *    and the new element type `B`.
- *  @define orderDependent
- *
- *    Note: might return different results for different runs, unless the underlying collection type is ordered.
- *  @define orderDependentFold
- *
- *    Note: might return different results for different runs, unless the underlying collection type is ordered.
- *    or the operator is associative and commutative.
- *  @define mayNotTerminateInf
- *
- *    Note: may not terminate for infinite-sized collections.
- *  @define willNotTerminateInf
- *
- *    Note: will not terminate for infinite-sized collections.
  */
 trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr]
                                     with FilterMonadic[A, Repr]
diff --git a/src/library/scala/collection/immutable/GenMap.scala b/src/library/scala/collection/immutable/GenMap.scala
index 71417d82a4..9dc7242f80 100644
--- a/src/library/scala/collection/immutable/GenMap.scala
+++ b/src/library/scala/collection/immutable/GenMap.scala
@@ -6,14 +6,10 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala.collection
 package immutable
 
-
 import generic._
-import mutable.Builder
 
 
 /** A base trait for maps that can be mutated.
diff --git a/src/library/scala/collection/mutable/MapLike.scala b/src/library/scala/collection/mutable/MapLike.scala
index b97abd6a87..5fe1abb260 100644
--- a/src/library/scala/collection/mutable/MapLike.scala
+++ b/src/library/scala/collection/mutable/MapLike.scala
@@ -7,7 +7,6 @@
 \*                                                                      */
 
 
-
 package scala.collection
 package mutable
 
diff --git a/src/library/scala/collection/parallel/ParIterableLike.scala b/src/library/scala/collection/parallel/ParIterableLike.scala
index 35020dd7e6..51d487b773 100644
--- a/src/library/scala/collection/parallel/ParIterableLike.scala
+++ b/src/library/scala/collection/parallel/ParIterableLike.scala
@@ -143,9 +143,6 @@ import annotation.unchecked.uncheckedVariance
  *  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.
  *
- *  @define undefinedorder
- *  The order in which the operations on elements are performed is unspecified and may be nondeterministic.
- *
  *  @define pbfinfo
  *  An implicit value of class `CanCombineFrom` which determines the
  *  result class `That` from the current representation type `Repr` and
diff --git a/src/library/scala/collection/parallel/ParSeqLike.scala b/src/library/scala/collection/parallel/ParSeqLike.scala
index 3081acdc18..ba4a09d062 100644
--- a/src/library/scala/collection/parallel/ParSeqLike.scala
+++ b/src/library/scala/collection/parallel/ParSeqLike.scala
@@ -21,8 +21,6 @@ import scala.collection.generic.CanCombineFrom
 import scala.collection.generic.VolatileAbort
 
 
-
-
 /** A template trait for sequences of type `ParSeq[T]`, representing
  *  parallel sequences with element type `T`.
  *