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.

3 files changed, 25 insertions, 15 deletions

diff --git a/src/library/scala/collection/GenTraversableOnce.scala b/src/library/scala/collection/GenTraversableOnce.scala
index 244ff26397..4af2ca23be 100644
--- a/src/library/scala/collection/GenTraversableOnce.scala
+++ b/src/library/scala/collection/GenTraversableOnce.scala
@@ -67,6 +67,23 @@ trait GenTraversableOnce[+A] extends Any {
     */
   def foreach[U](f: A => U): Unit
 
+  /** Tests whether this $coll is known to have a finite size.
+    *  All strict collections are known to have finite size. For a non-strict
+    *  collection such as `Stream`, the predicate returns `'''true'''` if all
+    *  elements have been computed. It returns `'''false'''` if the stream is
+    *  not yet evaluated to the end. Non-empty Iterators usually return
+    *  `'''false'''` even if they were created from a collection with a known
+    *  finite size.
+    *
+    *  Note: many collection methods will not work on collections of infinite sizes.
+    *  The typical failure mode is an infinite loop. These methods always attempt a
+    *  traversal without checking first that `hasDefiniteSize` returns `'''true'''`.
+    *  However, checking `hasDefiniteSize` can provide an assurance that size is
+    *  well-defined and non-termination is not a concern.
+    *
+    *  @return  `'''true'''` if this collection is known to have finite size,
+    *           `'''false'''` otherwise.
+    */
   def hasDefiniteSize: Boolean
 
   def seq: TraversableOnce[A]
@@ -81,6 +98,9 @@ trait GenTraversableOnce[+A] extends Any {
 
   /** Tests whether the $coll is empty.
    *
+   *  Note: Implementations in subclasses that are not repeatedly traversable must take
+   *  care not to consume any elements when `isEmpty` is called.
+   *
    *  @return    `true` if the $coll contains no elements, `false` otherwise.
    */
   def isEmpty: Boolean
diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index bd1be84e97..bbbc33b3f5 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -138,17 +138,6 @@ trait TraversableLike[+A, +Repr] extends Any
     result
   }
 
-  /** Tests whether this $coll is known to have a finite size.
-   *  All strict collections are known to have finite size. For a non-strict
-   *  collection such as `Stream`, the predicate returns `'''true'''` if all
-   *  elements have been computed. It returns `'''false'''` if the stream is
-   *  not yet evaluated to the end.
-   *
-   *  Note: many collection methods will not work on collections of infinite sizes.
-   *
-   *  @return  `'''true'''` if this collection is known to have finite size,
-   *           `'''false'''` otherwise.
-   */
   def hasDefiniteSize = true
 
   def ++[B >: A, That](that: GenTraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = {
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