SI-9624 Improve documentation for TraversableOnce

- Move the doc comment for `hasDefiniteSize` up from TraversableLike
  to GenTraversableOnce and improve it.

- Add a note to `GenTraversableOnce.isEmpty` that implementations must
  not consume elements.

- Clarify alternatives to subclassing TraversableOnce.

1 files changed, 5 insertions, 4 deletions

diff --git a/src/library/scala/collection/TraversableOnce.scala b/src/library/scala/collection/TraversableOnce.scala
index 910c59b179..75c0d82922 100644
--- a/src/library/scala/collection/TraversableOnce.scala
+++ b/src/library/scala/collection/TraversableOnce.scala
@@ -38,9 +38,10 @@ import scala.reflect.ClassTag
  *  `Traversables`, such as folds, conversions, and other operations which
  *  traverse some or all of the elements and return a derived value.
  *  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`.
+ *  consider declaring an `Iterator` with a `next` and `hasNext` method or
+ *  creating an `Iterator` with one of the methods on the `Iterator` object.
+ *  Consider declaring a subclass of `Traversable` instead if the elements
+ *  can be traversed repeatedly.
  *
  *  @define coll traversable or iterator
  *  @define orderDependent
@@ -61,8 +62,8 @@ import scala.reflect.ClassTag
 trait TraversableOnce[+A] extends Any with GenTraversableOnce[A] {
   self =>
 
+  //TODO 2.12: Remove these methods. They are already defined in GenTraversableOnce
   /* Self-documenting abstract methods. */
-
   def foreach[U](f: A => U): Unit
   def isEmpty: Boolean
   def hasDefiniteSize: Boolean