Merge pull request #4760 from janekdb/2.11.x-collection-documentation-fixes-previously-4651

2.11.x collection documentation fixes

5 files changed, 85 insertions, 88 deletions

diff --git a/src/library/scala/collection/GenTraversableLike.scala b/src/library/scala/collection/GenTraversableLike.scala
index 479a8b5b1b..d730996be2 100644
--- a/src/library/scala/collection/GenTraversableLike.scala
+++ b/src/library/scala/collection/GenTraversableLike.scala
@@ -158,18 +158,6 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
   @migration("The behavior of `scanRight` has changed. The previous behavior can be reproduced with scanRight.reverse.", "2.9.0")
   def scanRight[B, That](z: B)(op: (A, B) => B)(implicit bf: CanBuildFrom[Repr, B, That]): That
 
-  /** Applies a function `f` to all elements of this $coll.
-   *
-   *  @param  f   the function that is applied for its side-effect to every element.
-   *              The result of function `f` is discarded.
-   *
-   *  @tparam  U  the type parameter describing the result of function `f`.
-   *              This result will always be ignored. Typically `U` is `Unit`,
-   *              but this is not necessary.
-   *
-   *  @usecase def foreach(f: A => Unit): Unit
-   *    @inheritdoc
-   */
   def foreach[U](f: A => U): Unit
 
   /** Builds a new collection by applying a function to all elements of this $coll.
diff --git a/src/library/scala/collection/GenTraversableOnce.scala b/src/library/scala/collection/GenTraversableOnce.scala
index a45ec965f5..244ff26397 100644
--- a/src/library/scala/collection/GenTraversableOnce.scala
+++ b/src/library/scala/collection/GenTraversableOnce.scala
@@ -49,6 +49,22 @@ import scala.language.higherKinds
  */
 trait GenTraversableOnce[+A] extends Any {
 
+  /** Applies a function `f` to all elements of this $coll.
+    *
+    *  @param  f   the function that is applied for its side-effect to every element.
+    *              The result of function `f` is discarded.
+    *
+    *  @tparam  U  the type parameter describing the result of function `f`.
+    *              This result will always be ignored. Typically `U` is `Unit`,
+    *              but this is not necessary.
+    *
+    *  @usecase def foreach(f: A => Unit): Unit
+    *    @inheritdoc
+    *
+    *    Note: this method underlies the implementation of most other bulk operations.
+    *    It's important to implement this method in an efficient way.
+    *
+    */
   def foreach[U](f: A => U): Unit
 
   def hasDefiniteSize: Boolean
@@ -110,13 +126,14 @@ trait GenTraversableOnce[+A] extends Any {
    *  binary operator.
    *
    *  $undefinedorder
+   *  $willNotTerminateInf
    *
    *  @tparam A1     a type parameter for the binary operator, a supertype of `A`.
    *  @param z       a neutral element for the fold operation; may be added to the result
    *                 an arbitrary number of times, and must not change the result (e.g., `Nil` for list concatenation,
-   *                 0 for addition, or 1 for multiplication.)
-   *  @param op      a binary operator that must be associative
-   *  @return        the result of applying fold operator `op` between all the elements and `z`
+   *                 0 for addition, or 1 for multiplication).
+   *  @param op      a binary operator that must be associative.
+   *  @return        the result of applying the fold operator `op` between all the elements and `z`, or `z` if this $coll is empty.
    */
   def fold[A1 >: A](z: A1)(op: (A1, A1) => A1): A1
 
@@ -205,6 +222,7 @@ trait GenTraversableOnce[+A] extends Any {
    *             op(...op(z, x_1), x_2, ..., x_n)
    *           }}}
    *           where `x,,1,,, ..., x,,n,,` are the elements of this $coll.
+   *           Returns `z` if this $coll is empty.
    */
   def foldLeft[B](z: B)(op: (B, A) => B): B
 
@@ -222,30 +240,32 @@ trait GenTraversableOnce[+A] extends Any {
    *             op(x_1, op(x_2, ... op(x_n, z)...))
    *           }}}
    *           where `x,,1,,, ..., x,,n,,` are the elements of this $coll.
+   *           Returns `z` if this $coll is empty.
    */
   def foldRight[B](z: B)(op: (A, B) => B): B
 
   /** Aggregates the results of applying an operator to subsequent elements.
    *
-   *  This is a more general form of `fold` and `reduce`. It has similar
-   *  semantics, but does not require the result to be a supertype of the
-   *  element type. It traverses the elements in different partitions
-   *  sequentially, using `seqop` to update the result, and then applies
-   *  `combop` to results from different partitions. The implementation of
-   *  this operation may operate on an arbitrary number of collection
-   *  partitions, so `combop` may be invoked an arbitrary number of times.
-   *
-   *  For example, one might want to process some elements and then produce
-   *  a `Set`. In this case, `seqop` would process an element and append it
-   *  to the list, while `combop` would concatenate two lists from different
-   *  partitions together. The initial value `z` would be an empty set.
+   *  This is a more general form of `fold` and `reduce`. It is similar to
+   *  `foldLeft` in that it doesn't require the result to be a supertype of the
+   *  element type. In addition, it allows parallel collections to be processed
+   *  in chunks, and then combines the intermediate results.
+   *
+   *  `aggregate` splits the $coll into partitions and processes each
+   *  partition by sequentially applying `seqop`, starting with `z` (like
+   *  `foldLeft`). Those intermediate results are then combined by using
+   *  `combop` (like `fold`). The implementation of this operation may operate
+   *  on an arbitrary number of collection partitions (even 1), so `combop` may
+   *  be invoked an arbitrary number of times (even 0).
+   *
+   *  As an example, consider summing up the integer values of a list of chars.
+   *  The initial value for the sum is 0. First, `seqop` transforms each input
+   *  character to an Int and adds it to the sum (of the partition). Then,
+   *  `combop` just needs to sum up the intermediate results of the partitions:
    *  {{{
-   *    pc.aggregate(Set[Int]())(_ += process(_), _ ++ _)
+   *    List('a', 'b', 'c').aggregate(0)({ (sum, ch) => sum + ch.toInt }, { (p1, p2) => p1 + p2 })
    *  }}}
    *
-   *  Another example is calculating geometric mean from a collection of doubles
-   *  (one would typically require big doubles for this).
-   *
    *  @tparam B        the type of accumulated results
    *  @param z         the initial value for the accumulated result of the partition - this
    *                   will typically be the neutral element for the `seqop` operator (e.g.
@@ -423,13 +443,13 @@ trait GenTraversableOnce[+A] extends Any {
    */
   def find(@deprecatedName('pred) p: A => Boolean): Option[A]
 
-  /** Copies values of this $coll to an array.
+  /** Copies the elements of this $coll to an array.
    *  Fills the given array `xs` with values of this $coll.
    *  Copying will stop once either the end of the current $coll is reached,
-   *  or the end of the array is reached.
+   *  or the end of the target array is reached.
    *
    *  @param  xs     the array to fill.
-   *  @tparam B      the type of the elements of the array.
+   *  @tparam B      the type of the elements of the target array.
    *
    *  @usecase def copyToArray(xs: Array[A]): Unit
    *    @inheritdoc
@@ -438,14 +458,14 @@ trait GenTraversableOnce[+A] extends Any {
    */
   def copyToArray[B >: A](xs: Array[B]): Unit
 
-  /** Copies values of this $coll to an array.
+  /** Copies the elements of this $coll to an array.
    *  Fills the given array `xs` with values of this $coll, beginning at index `start`.
    *  Copying will stop once either the end of the current $coll is reached,
-   *  or the end of the array is reached.
+   *  or the end of the target array is reached.
    *
    *  @param  xs     the array to fill.
    *  @param  start  the starting index.
-   *  @tparam B      the type of the elements of the array.
+   *  @tparam B      the type of the elements of the target array.
    *
    *  @usecase def copyToArray(xs: Array[A], start: Int): Unit
    *    @inheritdoc
@@ -454,6 +474,22 @@ trait GenTraversableOnce[+A] extends Any {
    */
   def copyToArray[B >: A](xs: Array[B], start: Int): Unit
 
+  /** Copies the elements of this $coll to an array.
+   *  Fills the given array `xs` with at most `len` elements of
+   *  this $coll, starting at position `start`.
+   *  Copying will stop once either the end of the current $coll is reached,
+   *  or the end of the target array is reached, or `len` elements have been copied.
+   *
+   *  @param  xs     the array to fill.
+   *  @param  start  the starting index.
+   *  @param  len    the maximal number of elements to copy.
+   *  @tparam B      the type of the elements of the target array.
+   *
+   *  @usecase def copyToArray(xs: Array[A], start: Int, len: Int): Unit
+   *    @inheritdoc
+   *
+   *    $willNotTerminateInf
+   */
   def copyToArray[B >: A](xs: Array[B], start: Int, len: Int): Unit
 
   /** Displays all elements of this $coll in a string using start, end, and
diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index 04ae8c8aff..bd1be84e97 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -340,14 +340,6 @@ trait TraversableLike[+A, +Repr] extends Any
     b.result
   }
 
-  /** Tests whether a predicate holds for all elements of this $coll.
-   *
-   *  $mayNotTerminateInf
-   *
-   *  @param   p     the predicate used to test elements.
-   *  @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
     breakable {
@@ -374,15 +366,6 @@ trait TraversableLike[+A, +Repr] extends Any
     result
   }
 
-  /** Finds the first element of the $coll satisfying a predicate, if any.
-   *
-   *  $mayNotTerminateInf
-   *  $orderDependent
-   *
-   *  @param p    the predicate used to test elements.
-   *  @return     an option value containing the first element in the $coll
-   *              that satisfies `p`, or `None` if none exists.
-   */
   def find(p: A => Boolean): Option[A] = {
     var result: Option[A] = None
     breakable {
@@ -594,23 +577,6 @@ trait TraversableLike[+A, +Repr] extends Any
    */
   def inits: Iterator[Repr] = iterateUntilEmpty(_.init)
 
-  /** Copies elements of this $coll to an array.
-   *  Fills the given array `xs` with at most `len` elements of
-   *  this $coll, starting at position `start`.
-   *  Copying will stop once either the end of the current $coll is reached,
-   *  or the end of the array is reached, or `len` elements have been copied.
-   *
-   *  @param  xs     the array to fill.
-   *  @param  start  the starting index.
-   *  @param  len    the maximal number of elements to copy.
-   *  @tparam B      the type of the elements of the array.
-   *
-   *
-   *  @usecase def copyToArray(xs: Array[A], start: Int, len: Int): Unit
-   *    @inheritdoc
-   *
-   *    $willNotTerminateInf
-   */
   def copyToArray[B >: A](xs: Array[B], start: Int, len: Int) {
     var i = start
     val end = (start + len) min xs.length
@@ -625,7 +591,7 @@ trait TraversableLike[+A, +Repr] extends Any
 
   @deprecatedOverriding("Enforce contract of toTraversable that if it is Traversable it returns itself.", "2.11.0")
   def toTraversable: Traversable[A] = thisCollection
-  
+
   def toIterator: Iterator[A] = toStream.iterator
   def toStream: Stream[A] = toBuffer.toStream
   // Override to provide size hint.
diff --git a/src/library/scala/collection/package.scala b/src/library/scala/collection/package.scala
index 13fe7a79c4..856f901b77 100644
--- a/src/library/scala/collection/package.scala
+++ b/src/library/scala/collection/package.scala
@@ -13,8 +13,11 @@ package scala
  *
  * == Guide ==
  *
- * A detailed guide for the collections library is available
+ * A detailed guide for using the collections library is available
  * at [[http://docs.scala-lang.org/overviews/collections/introduction.html]].
+ * Developers looking to extend the collections library can find a description
+ * of its architecture at
+ * [[http://docs.scala-lang.org/overviews/core/architecture-of-scala-collections.html]].
  *
  * == Using Collections ==
  *
@@ -31,24 +34,25 @@ package scala
  * array: Array[Int] = Array(1, 2, 3, 4, 5, 6)
  *
  * scala> array map { _.toString }
- * res0: Array[java.lang.String] = Array(1, 2, 3, 4, 5, 6)
+ * res0: Array[String] = Array(1, 2, 3, 4, 5, 6)
  *
  * scala> val list = List(1,2,3,4,5,6)
  * list: List[Int] = List(1, 2, 3, 4, 5, 6)
  *
  * scala> list map { _.toString }
- * res1: List[java.lang.String] = List(1, 2, 3, 4, 5, 6)
+ * res1: List[String] = List(1, 2, 3, 4, 5, 6)
  *
  * }}}
  *
  * == Creating Collections ==
  *
- * The most common way to create a collection is to use the companion objects as factories.
- * Of these, the three most common
- * are [[scala.collection.Seq]], [[scala.collection.immutable.Set]], and [[scala.collection.immutable.Map]].  Their
- * companion objects are all available
- * as type aliases the either the [[scala]] package or in `scala.Predef`, and can be used
- * like so:
+ * The most common way to create a collection is to use its companion object as
+ * a factory. The three most commonly used collections are
+ * [[scala.collection.Seq]], [[scala.collection.immutable.Set]], and
+ * [[scala.collection.immutable.Map]].
+ * They can be used directly as shown below since their companion objects are
+ * all available as type aliases in either the [[scala]] package or in
+ * `scala.Predef`. New collections are created like this:
  * {{{
  * scala> val seq = Seq(1,2,3,4,1)
  * seq: Seq[Int] = List(1, 2, 3, 4, 1)
@@ -56,12 +60,12 @@ package scala
  * scala> val set = Set(1,2,3,4,1)
  * set: scala.collection.immutable.Set[Int] = Set(1, 2, 3, 4)
  *
- * scala> val map = Map(1 -> "one",2 -> "two", 3 -> "three",2 -> "too")
- * map: scala.collection.immutable.Map[Int,java.lang.String] = Map((1,one), (2,too), (3,three))
+ * scala> val map = Map(1 -> "one", 2 -> "two", 3 -> "three", 2 -> "too")
+ * map: scala.collection.immutable.Map[Int,String] = Map(1 -> one, 2 -> too, 3 -> three)
  * }}}
  *
- * It is also typical to use the [[scala.collection.immutable]] collections over those
- * in [[scala.collection.mutable]]; The types aliased in
+ * It is also typical to prefer the [[scala.collection.immutable]] collections
+ * over those in [[scala.collection.mutable]]; the types aliased in
  * the `scala.Predef` object are the immutable versions.
  *
  * Also note that the collections library was carefully designed to include several implementations of
@@ -74,9 +78,13 @@ package scala
  *
  * === Converting between Java Collections ===
  *
- * The `JavaConversions` object provides implicit defs that will allow mostly seamless integration
- * between Java Collections-based APIs and the Scala collections library.
+ * The [[scala.collection.JavaConversions]] object provides implicit defs that
+ * will allow mostly seamless integration between APIs using Java Collections
+ * and the Scala collections library.
  *
+ * Alternatively the [[scala.collection.JavaConverters]] object provides a collection
+ * of decorators that allow converting between Scala and Java collections using `asScala`
+ * and `asJava` methods.
  */
 package object collection {
   import scala.collection.generic.CanBuildFrom
diff --git a/src/library/scala/collection/parallel/ParIterableLike.scala b/src/library/scala/collection/parallel/ParIterableLike.scala
index e7b022b895..8c9b959569 100644
--- a/src/library/scala/collection/parallel/ParIterableLike.scala
+++ b/src/library/scala/collection/parallel/ParIterableLike.scala
@@ -1499,5 +1499,4 @@ self: ParIterableLike[T, Repr, Sequential] =>
       append(s)
     }
   })
-
 }