more docs. noreview.

5 files changed, 288 insertions, 188 deletions

diff --git a/src/library/scala/collection/IterableLike.scala b/src/library/scala/collection/IterableLike.scala
index 06db5fb6fc..2e86b90479 100644
--- a/src/library/scala/collection/IterableLike.scala
+++ b/src/library/scala/collection/IterableLike.scala
@@ -221,7 +221,7 @@ self =>
   /** Returns a $coll formed from this $coll and another iterable collection
    *  by combining corresponding elements in pairs.
    *  If one of the two collections is shorter than the other,
-   *  placeholder elements are used to extend the collection to the longer length.
+   *  placeholder elements are used to extend the shorter collection to the length of the longer.
    *
    *  $orderDependent
    *
diff --git a/src/library/scala/collection/Iterator.scala b/src/library/scala/collection/Iterator.scala
index 61eabefe8b..dfd945545e 100644
--- a/src/library/scala/collection/Iterator.scala
+++ b/src/library/scala/collection/Iterator.scala
@@ -260,6 +260,10 @@ import Iterator.empty
  *  @author  Martin Odersky, Matthias Zenger
  *  @version 2.8
  *  @since   1
+ *  @define willNotTerminateInf
+ *  Note: will not terminate for infinite iterators.
+ *  @define mayNotTerminateInf
+ *  Note: may not terminate for infinite iterators.
  */
 trait Iterator[+A] { self =>
 
@@ -284,7 +288,7 @@ trait Iterator[+A] { self =>
     private var remaining = n
     def hasNext = remaining > 0 && self.hasNext
     def next(): A =
-      if (hasNext) { remaining -= 1; self.next }
+      if (hasNext) { remaining -= 1; self.next() }
       else empty.next()
   }
 
@@ -380,7 +384,7 @@ trait Iterator[+A] { self =>
     def next() = if (hasNext) { hdDefined = false; hd } else empty.next()
   }
 
-  /** Returns an iterator over all the elements of this iterator that
+  /** Creates an iterator over all the elements of this iterator that
    *  satisfy the predicate `p`. The order of the elements
    *  is preserved.
    *
@@ -392,7 +396,7 @@ trait Iterator[+A] { self =>
    */
   def withFilter(p: A => Boolean): Iterator[A] = filter(p)
 
-  /** Returns an iterator over all the elements of this iterator which
+  /** Creates an iterator over all the elements of this iterator which
    *  do not satisfy a predicate p.
    *
    *  @param p the predicate used to test values.
@@ -400,12 +404,12 @@ trait Iterator[+A] { self =>
    */
   def filterNot(p: A => Boolean): Iterator[A] = filter(!p(_))
 
- /** Returns a new iterator based on the partial function `pf`,
-  *  containing `pf(x)` for all the elements which are defined on pf.
-  *  The order of the elements is preserved.
-  *
+ /** Creates an iterator by transforming values
+  *  produced by this iterator with a partial function, dropping those
+  *  values for which the partial function is not defined.
   *  @param pf the partial function which filters and maps the iterator.
-  *  @return the new iterator.
+  *  @return a new iterator which yields each value `x` produced by this iterator for
+  *          which `pf` is defined the image `pf(x)`.
   */
   def partialMap[B](pf: PartialFunction[A, B]): Iterator[B] = {
     val self = buffered
@@ -416,12 +420,11 @@ trait Iterator[+A] { self =>
     }
   }
 
-  /** Returns an iterator over the longest prefix of this iterator such that
-   *  all elements of the result satisfy the predicate `p`.
-   *  The order of the elements is preserved.
-   *
-   *  @param p the predicate used to filter the iterator.
-   *  @return  the longest prefix of this iterator satisfying `p`.
+  /** Takes longest prefix of values produced by this iterator that satisfy a predicate.
+   *  @param   p  The predicate used to test elements.
+   *  @return  An iterator returning the values produced by this iterator, until
+   *           this iterator produces a value that does not satisfy
+   *           the predicate `p`.
    */
   def takeWhile(p: A => Boolean): Iterator[A] = new Iterator[A] {
     private var hd: A = _
@@ -485,20 +488,29 @@ trait Iterator[+A] { self =>
     }
   }
 
-  /** Return an iterator formed from this iterator and the specified iterator
-   *  `that` by associating each element of the former with
-   *  the element at the same position in the latter.
+  /** Creates an iterator formed from this iterator and another iterator
+   *  by combining corresponding values in pairs.
    *  If one of the two iterators is longer than the other, its remaining
    *  elements are ignored.
+   *  @param   that  The iterator providing the second half of each result pair
+   *  @return        a new iterator containing pairs consisting of
+   *                 corresponding elements of this iterator and `that`. The number
+   *                 of elements returned by the new iterator is the
+   *                 minimum of the number of elements returned by this
+   *                 iterator and `that`.
    */
   def zip[B](that: Iterator[B]) = new Iterator[(A, B)] {
     def hasNext = self.hasNext && that.hasNext
     def next = (self.next, that.next)
   }
 
-  /** Return a new iterator with a length equal or longer to `len`.
-   *  If the current iterator returns fewer than `len` elements
-   *  return `elem` until the required length `len` is reached.
+  /** Appends an element value to this iterator until a given target length is reached.
+   *  @param   len   the target length
+   *  @param   elem  the padding value
+   *  @return a new iterator consisting of producing all values of this iterator,
+   *          followed by the minimal number of occurrences of `elem` so
+   *          that the number of produced values is at least `len`.
+   *  @usecase def padTo(len: Int, elem: A): Iterator[A]
    */
   def padTo[A1 >: A](len: Int, elem: A1) = new Iterator[A1] {
     private var count = 0
@@ -511,9 +523,8 @@ trait Iterator[+A] { self =>
     }
   }
 
-  /** Return an iterator that pairs each element of this iterator
+  /** Creates an iterator that pairs each element produced by this iterator
    *  with its index, counting from 0.
-   *
    */
   def zipWithIndex = new Iterator[(A, Int)] {
     var idx = 0
@@ -525,9 +536,10 @@ trait Iterator[+A] { self =>
     }
   }
 
-  /** Returns an iterator formed from this iterator and the specified iterator
-   *  `that` by associating each element of the former with
-   *  the element at the same position in the latter.
+  /** Creates an iterator formed from this iterator and another iterator
+   *  by combining corresponding elements in pairs.
+   *  If one of the two iterators is shorter than the other,
+   *  placeholder elements are used to extend the shorter iterator to the length of the longer.
    *
    *  @param that     iterator `that` may have a different length
    *                  as the self iterator.
@@ -537,12 +549,12 @@ trait Iterator[+A] { self =>
    *  @param thatElem element `thatElem` is used to fill up the
    *                  resulting iterator if `that` is shorter than
    *                  the self iterator
-   *  @return         `Iterator((a<sub>0</sub>,b<sub>0</sub>), ...,
-   *                  (a<sub>n</sub>,b<sub>n</sub>), (elem,b<sub>n+1</sub>),
-   *                  ..., {elem,b<sub>m</sub>})`
-   *                  when `[a<sub>0</sub>, ..., a<sub>n</sub>] zip
-   *                  [b<sub>0</sub>, ..., b<sub>m</sub>]` is
-   *                  invoked where `m &gt; n`.
+   *  @return         a new iterator containing pairs consisting of
+   *                  corresponding values of this iterator and `that`. The length
+   *                  of the returned iterator is the maximum of the lengths of this iterator and `that`.
+   *                  If this iterator is shorter than `that`, `thisElem` values are used to pad the result.
+   *                  If `that` is shorter than this iterator, `thatElem` values are used to pad the result.
+   *  @usecase def zipAll[B](that: Iterator[B], thisElem: A, thatElem: B): Iterator[(A, B1)]
    */
   def zipAll[B, A1 >: A, B1 >: B](that: Iterator[B], thisElem: A1, thatElem: B1) = new Iterator[(A1, B1)] {
     def hasNext = self.hasNext || that.hasNext
@@ -556,20 +568,25 @@ trait Iterator[+A] { self =>
       }
   }
 
-  /** Execute a function `f` for all elements of this
-   *  iterator.
+  /** Applies a function `f` to all values produced by this iterator.
+   *
+   *  @param  f   the function that is applied for its side-effect to every element.
+   *              The result of function `f` is discarded.
    *
-   *  @param  f   a function that is applied to every element.
+   *  @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
    */
   def foreach[U](f: A =>  U) { while (hasNext) f(next()) }
 
-  /** Apply a predicate `p` to all elements of this
-   *  iterable object and return `true` iff the predicate yields
-   *  `true` for all elements.
+  /** Tests whether a predicate holds for all values produced by this iterator.
+   *  $mayNotTerminateInf
    *
-   *  @param p the predicate
-   *  @return  `true` iff the predicate yields `true`
-   *           for all elements.
+   *  @param   p     the predicate used to test elements.
+   *  @return        `true` if the given predicate `p` holds for all values
+   *                 produced by this iterator, otherwise `false`.
    */
   def forall(p: A => Boolean): Boolean = {
     var res = true
@@ -577,13 +594,12 @@ trait Iterator[+A] { self =>
     res
   }
 
-  /** Apply a predicate `p` to all elements of this
-   *  iterable object and return true iff there is at least one
-   *  element for which `p` yields `true`.
+  /** Tests whether a predicate holds for some of the values produced by this iterator.
+   *  $mayNotTerminateInf
    *
-   *  @param p the predicate
-   *  @return  `true` iff the predicate yields `true`
-   *           for at least one element.
+   *  @param   p     the predicate used to test elements.
+   *  @return        `true` if the given predicate `p` holds for some of the values
+   *                 produced by this iterator, otherwise `false`.
    */
   def exists(p: A => Boolean): Boolean = {
     var res = false
@@ -591,18 +607,22 @@ trait Iterator[+A] { self =>
     res
   }
 
- /** Tests if the given value `elem` is a member of this iterator.
+  /** Tests whether this iterator contains a given value as an element.
+   *  $mayNotTerminateInf
    *
-   *  @param elem element whose membership has to be tested.
+   *  @param elem  the element to test.
+   *  @return     `true` if this iterator produces some value that is
+   *               is equal (wrt `==`) to `elem`, `false` otherwise.
    */
   def contains(elem: Any): Boolean = exists(_ == elem)
 
-  /** Find and return the first value returned by the iterator satisfying a
+  /** Finds the first value produced by the iterator satisfying a
    *  predicate, if any.
+   *  $mayNotTerminateInf
    *
-   *  @param p the predicate
-   *  @return  the first element in the iterable object satisfying
-   *           `p`, or `None` if none exists.
+   *  @param p the predicate used to test values.
+   *  @return  an option value containing the first value produced by the iterator that satisfies
+   *           predicate `p`, or `None` if none exists.
    */
   def find(p: A => Boolean): Option[A] = {
     var res: Option[A] = None
@@ -628,12 +648,11 @@ trait Iterator[+A] { self =>
   }
    */
 
-  /** Returns index of the first element satisfying a predicate, or -1.
-   *
-   *  @note may not terminate for infinite-sized collections.
-   *  @param  p the predicate
-   *  @return   the index of the first element satisfying `p`,
-   *           or -1 if such an element does not exist
+  /** Returns the index of the first produced value satisfying a predicate, or -1.
+   *  $mayNotTerminateInf
+   *  @param  p the predicate to test values
+   *  @return   the index of the first produced value satisfying `p`,
+   *           or -1 if such an element does not exist until the end of the iterator is reached.
    */
   def indexWhere(p: A => Boolean): Int = {
     var i = 0
@@ -650,12 +669,11 @@ trait Iterator[+A] { self =>
 
   /** Returns the index of the first occurence of the specified
    *  object in this iterable object.
+   *  $mayNotTerminateInf
    *
-   *  @note may not terminate for infinite-sized collections.
    *  @param  elem  element to search for.
-   *  @return the index in this sequence of the first occurence of the
-   *          specified element, or -1 if the sequence does not contain
-   *          this element.
+   *  @return the index of the first occurence of `elem` in the values produced by this iterator,
+   *          or -1 if such an element does not exist until the end of the iterator is reached.
    */
   def indexOf[B >: A](elem: B): Int = {
     var i = 0
@@ -670,13 +688,17 @@ trait Iterator[+A] { self =>
     if (found) i else -1
   }
 
-  /** Combines the elements of this iterator together using the binary
-   *  operator `op`, from left to right, and starting with
-   *  the value `z`.
-   *
-   *  @return `op(... (op(op(z,a<sub>0</sub>),a<sub>1</sub>) ...),
-   *          a<sub>n</sub>)` if the iterator yields elements
-   *          `a<sub>0</sub>, a<sub>1</sub>, ..., a<sub>n</sub>`.
+  /** Applies a binary operator to a start value and all values produced by this iterator, going left to right.
+   *  $willNotTerminateInf
+   *  @param   z    the start value.
+   *  @param   op   the binary operator.
+   *  @tparam  B    the result type of the binary operator.
+   *  @return  the result of inserting `op` between consecutive values produced by this iterator
+   *           going left to right with the start value `z` on the left:
+   *           {{{
+   *             op(...op(z, x,,1,,), x,,2,,, ..., x,,n,,)
+   *           }}}
+   *           where `x,,1,,, ..., x,,n,,` are the values produced by this iterator.
    */
   def foldLeft[B](z: B)(op: (B, A) => B): B = {
     var acc = z
@@ -684,89 +706,116 @@ trait Iterator[+A] { self =>
     acc
   }
 
-  /** Combines the elements of this iterator together using the binary
-   *  operator `op`, from right to left, and starting with
-   *  the value `z`.
-   *
-   *  @return `a<sub>0</sub> op (... op (a<sub>n</sub> op z)...)`
-   *          if the iterator yields elements `a<sub>0</sub>, a<sub>1</sub>, ...,
-   *          a<sub>n</sub>`.
+  /** Applies a binary operator to all values produced by this iterator and a start value, going right to left.
+   *  $willNotTerminateInf
+   *  @param   z    the start value.
+   *  @param   op   the binary operator.
+   *  @tparam  B    the result type of the binary operator.
+   *  @return  the result of inserting `op` between consecutive values produced by this iterator
+   *           going right to left with the start value `z` on the right:
+   *           {{{
+   *             op(x,,1,,, op(x,,2,,, ... op(x,,n,,, z)...))
+   *           }}}
+   *           where `x,,1,,, ..., x,,n,,` are the values produced by this iterator.
    */
   def foldRight[B](z: B)(op: (A, B) => B): B =
     if (hasNext) op(next(), foldRight(z)(op)) else z
 
-  /** Similar to `foldLeft` but can be used as
-   *  an operator with the order of iterator and zero arguments reversed.
-   *  That is, `z /: xs` is the same as `xs foldLeft z`.
+  /** Applies a binary operator to a start value and all values produced by this iterator, going left to right.
+   *
+   *  Note: `/:` is alternate syntax for `foldLeft`; `z /: it` is the same as `it foldLeft z`.
+   *  $willNotTerminateInf
    *
-   *  @param z the left argument of the first application of `op`
-   *           (evaluation occurs from left to right).
-   *  @param op the applied operator.
-   *  @return  the result value
-   *  @see     `<a href="#foldLeft">foldLeft</a>`.
+   *  @param   z    the start value.
+   *  @param   op   the binary operator.
+   *  @tparam  B    the result type of the binary operator.
+   *  @return  the result of inserting `op` between consecutive values produced by this iterator
+   *           going left to right with the start value `z` on the left:
+   *           {{{
+   *             op(...op(z, x,,1,,), x,,2,,, ..., x,,n,,)
+   *           }}}
+   *           where `x,,1,,, ..., x,,n,,` are the values produced by this iterator.
    */
   def /:[B](z: B)(op: (B, A) => B): B = foldLeft(z)(op)
 
-  /** An alias for `foldRight`.
-   *  That is, `xs :\ z` is the same as `xs foldRight z`.
-   *
-   *  @param z the right argument of the first application of `op`
-   *           (evaluation occurs from right to left).
-   *  @param op the applied operator.
-   *  @return  the result value.
-   *  @see     `<a href="#foldRight">foldRight</a>`.
+  /** Applies a binary operator to all values produced by this iterator and a start value, going right to left.
+   *  Note: `:\` is alternate syntax for `foldRight`; `it :\ z` is the same as `it foldRight z`.
+   *  $willNotTerminateInf
+   *  @param   z    the start value.
+   *  @param   op   the binary operator.
+   *  @tparam  B    the result type of the binary operator.
+   *  @return  the result of inserting `op` between consecutive values produced by this iterator
+   *           going right to left with the start value `z` on the right:
+   *           {{{
+   *             op(x,,1,,, op(x,,2,,, ... op(x,,n,,, z)...))
+   *           }}}
+   *           where `x,,1,,, ..., x,,n,,` are the values produced by this iterator.
    */
   def :\[B](z: B)(op: (A, B) => B): B = foldRight(z)(op)
 
-  /** Combines the elements of this iterator together using the binary
-   *  operator `op`, from left to right.
+  /** Applies a binary operator to all values produced by this iterator, going left to right.
+   *  $willNotTerminateInf
    *
-   *  @param op  The operator to apply
-   *  @return `op(... op(a<sub>0</sub>,a<sub>1</sub>), ..., a<sub>n</sub>)`
-   *  if the iterator yields elements
-   *          `a<sub>0</sub>, a<sub>1</sub>, ..., a<sub>n</sub>`.
-   *  @throws Predef.UnsupportedOperationException if the iterator is empty.
+   *  @param  op    the binary operator.
+   *  @tparam  B    the result type of the binary operator.
+   *  @return  the result of inserting `op` between consecutive values produced by this iterator
+   *           going left to right:
+   *           {{{
+   *             op(...(op(x,,1,,, x,,2,,), ... ) , x,,n,,)
+   *           }}}
+   *           where `x,,1,,, ..., x,,n,,` are the values produced by this iterator.
+   *  @throws `UnsupportedOperationException` if this iterator is empty.
    */
   def reduceLeft[B >: A](op: (B, A) => B): B = {
     if (hasNext) foldLeft[B](next())(op)
     else throw new UnsupportedOperationException("empty.reduceLeft")
   }
 
-  /** Combines the elements of this iterator together using the binary
-   *  operator `op`, from right to left
-   *  @param op  The operator to apply
+  /** Applies a binary operator to all values produced by this iterator, going right to left.
+   *  $willNotTerminateInf
    *
-   *  @return `a<sub>0</sub> op (... op (a<sub>n-1</sub> op a<sub>n</sub>)...)`
-   *          if the iterator yields elements `a<sub>0</sub>, a<sub>1</sub>, ...,
-   *          a<sub>n</sub>`.
-
-   *  @throws Predef.UnsupportedOperationException if the iterator is empty.
+   *  @param  op    the binary operator.
+   *  @tparam  B    the result type of the binary operator.
+   *  @return  the result of inserting `op` between consecutive values produced by this iterator
+   *           going right to left:
+   *           {{{
+   *             op(x,,1,,, op(x,,2,,, ..., op(x,,n-1,,, x,,n,,)...))
+   *           }}}
+   *           where `x,,1,,, ..., x,,n,,` are the values produced by this iterator.
+   *  @throws `UnsupportedOperationException` if this iterator is empty.
    */
   def reduceRight[B >: A](op: (A, B) => B): B = {
     if (hasNext) foldRight[B](next())(op)
     else throw new UnsupportedOperationException("empty.reduceRight")
   }
 
-  /** Combines the elements of this iterator together using the binary
-   *  operator `op`, from left to right
-   *  @param op  The operator to apply
-   *  @return  If the iterable is non-empty, the result of the operations as an Option, otherwise None.
+  /** Optionally applies a binary operator to all values produced by this iterator, going left to right.
+   *  $willNotTerminateInf
+   *
+   *  @param  op    the binary operator.
+   *  @tparam  B    the result type of the binary operator.
+   *  @return  an option value containing the result of `reduceLeft(op)` is this iterator is nonempty,
+   *           `None` otherwise.
    */
   def reduceLeftOption[B >: A](op: (B, A) => B): Option[B] = {
     if (!hasNext) None else Some(reduceLeft(op))
   }
 
-  /** Combines the elements of this iterable object together using the binary
-   *  operator `op`, from right to left.
+  /** Optionally applies a binary operator to all values produced by this iterator, going right to left.
+   *  $willNotTerminateInf
    *
-   *  @param op  The operator to apply
-   *  @return  If the iterable is non-empty, the result of the operations as an Option, otherwise None.
+   *  @param  op    the binary operator.
+   *  @tparam  B    the result type of the binary operator.
+   *  @return  an option value containing the result of `reduceRight(op)` is this iterator is nonempty,
+   *           `None` otherwise.
    */
   def reduceRightOption[B >: A](op: (A, B) => B): Option[B] = {
     if (!hasNext) None else Some(reduceRight(op))
   }
 
-  /** Returns a buffered iterator from this iterator.
+  /** Creates a buffered iterator from this iterator.
+   *  @see BufferedIterator
+   *  @return  a buffered iterator producing the same values as this iterator.
    */
   def buffered = new BufferedIterator[A] {
     private var hd: A = _
@@ -794,6 +843,7 @@ trait Iterator[+A] { self =>
    *  iterator (it seems to depend on some ordering issue I don't
    *  understand) this method takes the way one might expect, leaving
    *  the original iterator with 'size' fewer elements.
+   *  todo: remove
    */
   private def takeDestructively(size: Int): Seq[A] = {
     val buf = new ArrayBuffer[A]
@@ -933,7 +983,9 @@ trait Iterator[+A] { self =>
     new GroupedIterator[B](self, size, step)
 
   /** Returns the number of elements in this iterator.
-   *  @note The iterator is at its end after this method returns.
+   *  $willNotTerminateInf
+   *
+   *  Note: The iterator is at its end after this method returns.
    */
   def length: Int = {
     var i = 0
@@ -988,13 +1040,21 @@ trait Iterator[+A] { self =>
     }
   }
 
-  /** Fills the given array `xs` with at most `len` elements of
-   *  this iterator starting at position `start` until either `len` elements have been copied,
-   *  or the end of the iterator is reached, or the end of the array `xs` is reached.
+  /** Copies selected values produced by this iterator to an array.
+   *  Fills the given array `xs` with at most `len` values produced by this
+   *  iterator, after skipping `start` values.
+   *  Copying will stop once either the end of the current iterator is reached,
+   *  or the end of the array is reached, or `len` elements have been copied.
+   *
+   *  $willNotTerminateInf
    *
-   *  @param  xs the array to fill.
-   *  @param  start starting index.
-   *  @param  len number of elements to copy
+   *  @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
    */
   def copyToArray[B >: A](xs: Array[B], start: Int, len: Int): Unit = {
     var i = start
@@ -1005,34 +1065,48 @@ trait Iterator[+A] { self =>
     }
   }
 
-  /** Fills the given array `xs` with the elements of
-   *  this iterator starting at position `start`
-   *  until either the end of the current iterator or the end of array `xs` is reached.
+  /** Copies values produced by this iterator to an array.
+   *  Fills the given array `xs` with values produced by this iterator, after skipping `start` values.
+   *  Copying will stop once either the end of the current iterator is reached,
+   *  or the end of the array is reached.
+   *
+   *  $willNotTerminateInf
    *
-   *  @param  xs the array to fill.
-   *  @param  start starting index.
+   *  @param  xs     the array to fill.
+   *  @param  start  the starting index.
+   *  @tparam B      the type of the elements of the array.
+   *
+   *  @usecase def copyToArray(xs: Array[A], start: Int, len: Int): Unit
    */
   def copyToArray[B >: A](xs: Array[B], start: Int): Unit =
     copyToArray(xs, start, xs.length - start)
 
-  /** Fills the given array `xs` with the elements of
-   *  this iterator starting at position `0`
-   *  until either the end of the current iterator or the end of array `xs` is reached.
+  /** Copies values produced by this iterator to an array.
+   *  Fills the given array `xs` with values produced by this iterator.
+   *  Copying will stop once either the end of the current iterator is reached,
+   *  or the end of the array is reached.
+   *
+   *  $willNotTerminateInf
    *
-   *  @param  xs the array to fill.
+   *  @param  xs     the array to fill.
+   *  @tparam B      the type of the elements of the array.
+   *
+   *  @usecase def copyToArray(xs: Array[A], start: Int, len: Int): Unit
    */
   def copyToArray[B >: A](xs: Array[B]): Unit = copyToArray(xs, 0, xs.length)
 
-  /** Copy all elements to a buffer
+  /** Copies all values produced by this iterator to a buffer.
+   *  $willNotTerminateInf
    *  @param  dest The buffer to which elements are copied
    */
   def copyToBuffer[B >: A](dest: Buffer[B]) {
     while (hasNext) dest += next
   }
 
-  /** Traverse this iterator and return all elements in a list.
+  /** Traverses this iterator and returns all produced values in a list.
+   *  $willNotTerminateInf
    *
-   *  @return  A list which enumerates all elements of this iterator.
+   *  @return  a list which contains all values produced by this iterator.
    */
   def toList: List[A] = {
     val res = new ListBuffer[A]
@@ -1040,16 +1114,17 @@ trait Iterator[+A] { self =>
     res.toList
   }
 
-  /** Traverse this iterator and return all elements in a stream.
+  /** Traverses this iterator and returns all produced values in a list.
    *
-   *  @return  A stream which enumerates all elements of this iterator.
+   *  @return  a stream which contains all values produced by this iterator.
    */
   def toStream: Stream[A] =
     if (hasNext) Stream.cons(next, toStream) else Stream.empty
 
-  /** Traverse this iterator and return all elements in a sequence.
+  /** Traverses this iterator and returns all produced values in a sequence.
+   *  $willNotTerminateInf
    *
-   *  @return  A sequence which enumerates all elements of this iterator.
+   *  @return  a list which contains all values produced by this iterator.
    */
   def toSeq: Seq[A] = {
     val buffer = new ArrayBuffer[A]
@@ -1057,11 +1132,10 @@ trait Iterator[+A] { self =>
     buffer
   }
 
-  /** Checks if the other iterator contains the same elements as this one.
-   *
-   *  @note will not terminate for infinite-sized iterators.
+  /** Tests if another iterator produces the same valeus as this one.
+   *  $willNotTerminateInf
    *  @param that  the other iterator
-   *  @return true, iff both iterators contain the same elements in the same order.
+   *  @return `true`, if both iterators produce the same elements in the same order, `false` otherwise.
    */
   def sameElements(that: Iterator[_]): Boolean = {
     while (hasNext && that.hasNext)
@@ -1071,47 +1145,47 @@ trait Iterator[+A] { self =>
     !hasNext && !that.hasNext
   }
 
-  /** Returns a string representation of the elements in this iterator. The resulting string
-   *  begins with the string `start` and is finished by the string
-   *  `end`. Inside, the string representations of elements (w.r.t.
-   *  the method `toString`) are separated by the string
-   *  `sep`.
-   *  <p/>
-   *  Ex: <br/>
-   *  `List(1, 2, 3).mkString("(", "; ", ")") = "(1; 2; 3)"`
+  /** Displays all values produced by this iterator in a string using start, end, and separator strings.
    *
-   *  @param start starting string.
-   *  @param sep separator string.
-   *  @param end ending string.
-   *  @return a string representation of this iterable object.
+   *  @param start the starting string.
+   *  @param sep   the separator string.
+   *  @param end   the ending string.
+   *  @return      a string representation of this iterator. The resulting string
+   *               begins with the string `start` and ends with the string
+   *               `end`. Inside, the string representations (w.r.t. the method `toString`)
+   *               of all values produced by this iterator are separated by the string `sep`.
    */
   def mkString(start: String, sep: String, end: String): String = {
     val buf = new StringBuilder
     addString(buf, start, sep, end).toString
   }
 
-  /** Returns a string representation of this iterable object. The string
-   *  representations of elements (w.r.t. the method `toString()`)
-   *  are separated by the string `sep`.
+  /** Displays all values produced by this iterator in a string using a separator string.
    *
-   *  @param sep separator string.
-   *  @return a string representation of this iterable object.
+   *  @param sep   the separator string.
+   *  @return      a string representation of this iterator. In the resulting string
+   *               the string representations (w.r.t. the method `toString`)
+   *               of all values produced by this iterator are separated by the string `sep`.
    */
   def mkString(sep: String): String = mkString("", sep, "")
 
-  /** Returns a string representation of this iterable object. The string
-   *  representations of elements (w.r.t. the method `toString()`)
-   *  are concatenated without any separator string.
-   *
-   *  @return a string representation of this iterable object.
+  /** Displays all values produced by this iterator in a string.
+   *  @return a string representation of this iterator. In the resulting string
+   *          the string representations (w.r.t. the method `toString`)
+   *          of all values produced by this iterator follow each other without any separator string.
    */
   def mkString: String = mkString("")
 
-  /** Write all elements of this iterator into given string builder.
-   *  The written text begins with the string `start` and is finished by the string
-   *  `end`. Inside, the string representations of elements (w.r.t.
-   *  the method `toString()`) are separated by the string
-   *  `sep`.
+  /** Appends all values produced by this iterator to a string builder using start, end, and separator strings.
+   *  The written text begins with the string `start` and ends with the string
+   *  `end`. Inside, the string representations (w.r.t. the method `toString`)
+   *  of all values produced by this iterator are separated by the string `sep`.
+   *
+   *  @param  b    the string builder to which elements are appended.
+   *  @param start the starting string.
+   *  @param sep   the separator string.
+   *  @param end   the ending string.
+   *  @return      the string builder `b` to which elements were appended.
    */
   def addString(buf: StringBuilder, start: String, sep: String, end: String): StringBuilder = {
     buf.append(start)
@@ -1123,17 +1197,28 @@ trait Iterator[+A] { self =>
     buf.append(end)
   }
 
-  /** Write all elements of this iterator into given string builder.
-   *  The string representations of elements (w.r.t. the method `toString()`)
-   *  are separated by the string `sep`.
+  /** Appends all values produced by this iterator to a string builder using a separator string.
+   *  The written text consists of the string representations (w.r.t. the method `toString`)
+   *  of all values produced by this iterator, separated by the string `sep`.
+   *
+   *  @param  b    the string builder to which elements are appended.
+   *  @param sep   the separator string.
+   *  @return      the string builder `b` to which elements were appended.
    */
   def addString(buf: StringBuilder, sep: String): StringBuilder = addString(buf, "", sep, "")
 
-  /** Write all elements of this string into given string builder without using
-   *  any separator between consecutive elements.
+  /** Appends all values produced by this iterator to a string builder.
+   *  The written text consists of the string representations (w.r.t. the method `toString`)
+   *  of all values produced by this iterator without any separator string.
+   *
+   *  @param  b    the string builder to which elements are appended.
+   *  @return      the string builder `b` to which elements were appended.
    */
   def addString(buf: StringBuilder): StringBuilder = addString(buf, "", "", "")
 
+  /** Converts this iterator to a string.
+   *  @return `"empty iterator"` or `"non-empty iterator"`, depending on whether or not the iterator is empty.
+   */
   override def toString = (if (hasNext) "non-empty" else "empty")+" iterator"
 
   /** Returns a new iterator that first yields the elements of this
diff --git a/src/library/scala/collection/SeqLike.scala b/src/library/scala/collection/SeqLike.scala
index 0462bdc93a..32aae28851 100644
--- a/src/library/scala/collection/SeqLike.scala
+++ b/src/library/scala/collection/SeqLike.scala
@@ -498,7 +498,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
   def lastIndexOfSlice[B >: A](that: Seq[B], end: Int): Int =
     SeqLike.lastIndexOf(thisCollection, 0, length, that, 0, that.length, end)
 
-
   /** Tests whether this $coll contains a given sequence as a slice.
    *  $mayNotTerminateInf
    *  @param  that    the sequence to test
diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index 069f45909d..8c8f619b5e 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -478,7 +478,6 @@ self =>
    *             op(...op(z, x,,1,,), x,,2,,, ..., x,,n,,)
    *           }}}
    *           where `x,,1,,, ..., x,,n,,` are the elements of this $coll.
-   *
    */
   def foldLeft[B](z: B)(op: (B, A) => B): B = {
     var result = z
@@ -506,6 +505,9 @@ self =>
   def /: [B](z: B)(op: (B, A) => B): B = foldLeft(z)(op)
 
   /** Applies a binary operator to all elements of this $coll and a start value, going right to left.
+   *
+   *  $willNotTerminateInf
+   *  $orderDependentFold
    *  @param   z    the start value.
    *  @param   op   the binary operator.
    *  @tparam  B    the result type of the binary operator.
@@ -515,9 +517,6 @@ self =>
    *             op(x,,1,,, op(x,,2,,, ... op(x,,n,,, z)...))
    *           }}}
    *           where `x,,1,,, ..., x,,n,,` are the elements of this $coll.
-   *
-   *  $willNotTerminateInf
-   *  $orderDependentFold
    */
   def foldRight[B](z: B)(op: (A, B) => B): B = {
     var elems: List[A] = Nil
@@ -609,7 +608,6 @@ self =>
    *  @tparam  B    the result type of the binary operator.
    *  @return  an option value containing the result of `reduceRight(op)` is this $coll is nonempty,
    *           `None` otherwise.
-   *  @throws `UnsupportedOperationException` if this $coll is empty.
    */
   def reduceRightOption[B >: A](op: (A, B) => B): Option[B] =
     if (isEmpty) None else Some(reduceRight(op))
@@ -899,7 +897,7 @@ self =>
     for (x <- this) dest += x
   }
 
-  /** Copies selected elements of this $coll to an array.
+  /** 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,
@@ -927,7 +925,7 @@ self =>
     }
   }
 
-  /** Copies selected suffix of this $coll to an array.
+  /** Copies elements of this $coll to an array.
    *  Fills the given array `xs` with all elements of
    *  this $coll, starting at position `start`.
    *  Copying will stop once either the end of the current $coll is reached,
@@ -945,6 +943,23 @@ self =>
     copyToArray(xs, start, xs.length - start)
   }
 
+  /** Copies elements of this $coll to an array.
+   *  Fills the given array `xs` with all elements of
+   *  this $coll, starting at position `0`.
+   *  Copying will stop once either the end of the current $coll is reached,
+   *  or the end of the array is reached.
+   *
+   *  $willNotTerminateInf
+   *
+   *  @param  xs     the array to fill.
+   *  @tparam B      the type of the elements of the array.
+   *
+   *  @usecase def copyToArray(xs: Array[A], start: Int): Unit
+   */
+  def copyToArray[B >: A](xs: Array[B]) {
+    copyToArray(xs, 0)
+  }
+
   /** Converts this $coll to an array.
    *  $willNotTerminateInf
    *
diff --git a/src/library/scala/collection/generic/GenericTraversableTemplate.scala b/src/library/scala/collection/generic/GenericTraversableTemplate.scala
index 0ebcbe6a8b..0e3c3c203b 100644
--- a/src/library/scala/collection/generic/GenericTraversableTemplate.scala
+++ b/src/library/scala/collection/generic/GenericTraversableTemplate.scala
@@ -86,10 +86,11 @@ trait GenericTraversableTemplate[+A, +CC[X] <: Traversable[X]] extends HasNewBui
 
   /** Converts this $coll of traversable collections into
    *  a $coll in which all element collections are concatenated.
-   *  @B the type of the elements of each traversable collection.
-   *  @asTraversable an implicit conversion which asserts that the element type of this
-   *          $coll is a `Traversable`.
-   *  @return a new $coll reuslting from concatenating all element ${coll}s.
+   *  @tparam B the type of the elements of each traversable collection.
+   *  @param asTraversable an implicit conversion which asserts that the element type of this
+   *         $coll is a `Traversable`.
+   *  @return a new $coll resulting from concatenating all element ${coll}s.
+   *  @usecase def flatten[B]: $Coll[B]
    */
   def flatten[B](implicit asTraversable: A => /*<:<!!!*/ Traversable[B]): CC[B] = {
     val b = genericBuilder[B]