Rewording for #3958, and a few doc changes.

No review.

5 files changed, 31 insertions, 9 deletions

diff --git a/src/library/scala/collection/TraversableOnce.scala b/src/library/scala/collection/TraversableOnce.scala
index 451ebe4b92..e29ca1ed91 100644
--- a/src/library/scala/collection/TraversableOnce.scala
+++ b/src/library/scala/collection/TraversableOnce.scala
@@ -17,14 +17,18 @@ import mutable.{ Buffer, ListBuffer, ArrayBuffer }
  *  @tparam A    the element type of the collection
  *
  *  @define traversableonceinfo
- *  This trait is composed of those methods which can be implemented
- *  solely in terms of foreach and which do not need access to a Builder.
- *  It represents the implementations common to Iterators and
- *  Traversables, such as folds, conversions, and other operations which
+ *  This trait exists primarily to eliminate code duplication between
+ *  `Iterator` and `Traversable`, and thus implements some of the common
+ *  methods that can be implemented solely in terms of foreach without
+ *  access to a `Builder`. It also includes a number of abstract methods
+ *  whose implementations are provided by `Iterator`, `Traversable`, etc.
+ *  It contains implementations common to `Iterators` and
+ *  `Traversables`, such as folds, conversions, and other operations which
  *  traverse some or all of the elements and return a derived value.
- *  Note that, while all the methods here can implemented in terms of
- *  foreach, some of them are defined in subtraits such as `TraversableLike`
- *  and `Iterator`.
+ *  Directly subclassing `TraversableOnce` is not recommended - instead,
+ *  consider declaring an `Iterator` with a `next` and `hasNext` method,
+ *  creating an `Iterator` with one of the methods on the `Iterator` object,
+ *  or declaring a subclass of `Traversable`.
  *
  *  @author Martin Odersky
  *  @author Paul Phillips
diff --git a/src/library/scala/collection/generic/GenericClassManifestCompanion.scala b/src/library/scala/collection/generic/GenericClassManifestCompanion.scala
index 98cafd3841..e1df2f953d 100644
--- a/src/library/scala/collection/generic/GenericClassManifestCompanion.scala
+++ b/src/library/scala/collection/generic/GenericClassManifestCompanion.scala
@@ -16,7 +16,11 @@ import mutable.Builder
 
 
 
-
+/** This class represents companions of classes which require classmanifests
+ *  for their element types.
+ *
+ *  @author Aleksandar Prokopec
+ */
 abstract class GenericClassManifestCompanion[+CC[X] <: Traversable[X]] {
   type Coll = CC[_]
 
diff --git a/src/library/scala/collection/generic/GenericClassManifestTraversableTemplate.scala b/src/library/scala/collection/generic/GenericClassManifestTraversableTemplate.scala
index bf167bd6ab..5d562dab4e 100644
--- a/src/library/scala/collection/generic/GenericClassManifestTraversableTemplate.scala
+++ b/src/library/scala/collection/generic/GenericClassManifestTraversableTemplate.scala
@@ -17,6 +17,11 @@ import annotation.unchecked.uncheckedVariance
 
 
 
+/** This trait represents collections classes which require class
+ *  manifests for their element types.
+ *
+ *  @author Aleksandar Prokopec
+ */
 trait GenericClassManifestTraversableTemplate[+A, +CC[X] <: Traversable[X]] extends HasNewBuilder[A, CC[A] @uncheckedVariance] {
   implicit protected[this] val manifest: ClassManifest[A]
   def classManifestCompanion: GenericClassManifestCompanion[CC]
diff --git a/src/library/scala/collection/generic/GenericOrderedCompanion.scala b/src/library/scala/collection/generic/GenericOrderedCompanion.scala
index edf942e41d..669c715838 100644
--- a/src/library/scala/collection/generic/GenericOrderedCompanion.scala
+++ b/src/library/scala/collection/generic/GenericOrderedCompanion.scala
@@ -17,6 +17,11 @@ import mutable.Builder
 
 
 
+/** This class represents companions of classes which require the ordered trait
+ *  for their element types.
+ *
+ *  @author Aleksandar Prokopec
+ */
 abstract class GenericOrderedCompanion[+CC[X] <: Traversable[X]] {
   type Coll = CC[_]
 
diff --git a/src/library/scala/collection/generic/GenericOrderedTraversableTemplate.scala b/src/library/scala/collection/generic/GenericOrderedTraversableTemplate.scala
index 0ff4e86bdf..53bcd0c63a 100644
--- a/src/library/scala/collection/generic/GenericOrderedTraversableTemplate.scala
+++ b/src/library/scala/collection/generic/GenericOrderedTraversableTemplate.scala
@@ -16,7 +16,11 @@ import annotation.unchecked.uncheckedVariance
 
 
 
-
+/** This trait represents collections classes which require
+ *  ordered element types.
+ *
+ *  @author Aleksandar Prokopec
+ */
 trait GenericOrderedTraversableTemplate[+A, +CC[X] <: Traversable[X]] extends HasNewBuilder[A, CC[A] @uncheckedVariance] {
   implicit protected[this] val ord: Ordering[A]
   def orderedCompanion: GenericOrderedCompanion[CC]