SI-8587 Explicitly document forall/exists for empty collections

This behaviour isn't always intuitive for newcomers.

Also changes inadvertant doc comment to an impl. comment.

2 files changed, 7 insertions, 8 deletions

diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index b60ea86ab0..d3a7db6968 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -345,8 +345,8 @@ trait TraversableLike[+A, +Repr] extends Any
    *  $mayNotTerminateInf
    *
    *  @param   p     the predicate used to test elements.
-   *  @return        `true` if the given predicate `p` holds for all elements
-   *                 of this $coll, otherwise `false`.
+   *  @return        `true`  if this $coll is empty, otherwise `true` if the given predicate `p`
+    *                holds for all elements of this $coll, otherwise `false`.
    */
   def forall(p: A => Boolean): Boolean = {
     var result = true
@@ -362,8 +362,8 @@ trait TraversableLike[+A, +Repr] extends Any
    *  $mayNotTerminateInf
    *
    *  @param   p     the predicate used to test elements.
-   *  @return        `true` if the given predicate `p` holds for some of the
-   *                 elements of this $coll, otherwise `false`.
+   *  @return        `false` if this $coll is empty, otherwise `true` if the given predicate `p`
+    *                holds for some of the elements of this $coll, otherwise `false`
    */
   def exists(p: A => Boolean): Boolean = {
     var result = false
diff --git a/src/library/scala/collection/TraversableOnce.scala b/src/library/scala/collection/TraversableOnce.scala
index 072fd3da44..a8c4e047ab 100644
--- a/src/library/scala/collection/TraversableOnce.scala
+++ b/src/library/scala/collection/TraversableOnce.scala
@@ -85,10 +85,9 @@ trait TraversableOnce[+A] extends Any with GenTraversableOnce[A] {
    */
   def seq: TraversableOnce[A]
 
-  /** Presently these are abstract because the Traversable versions use
-   *  breakable/break, and I wasn't sure enough of how that's supposed to
-   *  function to consolidate them with the Iterator versions.
-   */
+  // Presently these are abstract because the Traversable versions use
+  // breakable/break, and I wasn't sure enough of how that's supposed to
+  // function to consolidate them with the Iterator versions.
   def forall(p: A => Boolean): Boolean
   def exists(p: A => Boolean): Boolean
   def find(p: A => Boolean): Option[A]