refined doc comments generation; refactored cod...

refined doc comments generation; refactored code into new Chars,
DocStrings classes in util. Added some more doc comments to collection
classes.

3 files changed, 118 insertions, 136 deletions

diff --git a/src/library/scala/collection/IterableLike.scala b/src/library/scala/collection/IterableLike.scala
index 66f63dd2f5..41dc774cd9 100644
--- a/src/library/scala/collection/IterableLike.scala
+++ b/src/library/scala/collection/IterableLike.scala
@@ -79,17 +79,7 @@ self =>
    *    Note: this method underlies the implementation of most other bulk operations.
    *    Subclasses should re-implement this method if a more efficient implementation exists.
    *
-   *  @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
-   *
-   *  @param  f   the function that is applied for its side-effect to every element.
-   *              The result of function `f` is discarded.
    */
   def foreach[U](f: A => U): Unit =
     iterator.foreach(f)
diff --git a/src/library/scala/collection/SeqLike.scala b/src/library/scala/collection/SeqLike.scala
index 5e7ea8ebfa..7e07a6460f 100644
--- a/src/library/scala/collection/SeqLike.scala
+++ b/src/library/scala/collection/SeqLike.scala
@@ -196,8 +196,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
   /** The size of this $coll, equivalent to `length`.
    *
    *  $willNotTerminateInf
-   *
-   *  @return    the number of elements in this $coll.
    */
   override def size = length
 
@@ -277,13 +275,9 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
    *  @param   elem   the element value to search for.
    *  @tparam  B      the type of the element `elem`.
    *  @return  the index of the first element of this $coll that is equal (wrt `==`)
-   *           tp `elem`, or `-1`, if none exists.
+   *           to `elem`, or `-1`, if none exists.
    *
    *  @usecase def indexOf(elem: A): Int
-   *
-   *  @param   elem   the element value to search for.
-   *  @return  the index of the first element of this $coll that is equal (wrt `==`)
-   *           to `elem`, or `-1`, if none exists.
    */
   def indexOf[B >: A](elem: B): Int = indexOf(elem, 0)
 
@@ -295,14 +289,9 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
    *  @tparam  B      the type of the element `elem`.
    *  @param   from   the start index
    *  @return  the index `>= from` of the first element of this $coll that is equal (wrt `==`)
-   *           tp `elem`, or `-1`, if none exists.
+   *           to `elem`, or `-1`, if none exists.
    *
    *  @usecase def indexOf(elem: A): Int
-   *
-   *  @param   elem   the element value to search for.
-   *  @param   from   the start index
-   *  @return  the index `>= from` of the first element of this $coll that is equal (wrt `==`)
-   *           to `elem`, or `-1`, if none exists.
    */
   def indexOf[B >: A](elem: B, from: Int): Int = indexWhere(elem ==, from)
 
@@ -316,10 +305,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
    *           to `elem`, or `-1`, if none exists.
    *
    *  @usecase def lastIndexOf(elem: A): Int
-   *
-   *  @param   elem   the element value to search for.
-   *  @return  the index of the last element of this $coll that is equal (wrt `==`)
-   *           to `elem`, or `-1`, if none exists.
    */
   def lastIndexOf[B >: A](elem: B): Int = lastIndexWhere(elem ==)
 
@@ -332,10 +317,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
    *           to `elem`, or `-1`, if none exists.
    *
    *  @usecase def lastIndexOf(elem: A): Int
-   *
-   *  @param   elem   the element value to search for.
-   *  @return  the index `<= end` of the last element of this $coll that is equal (wrt `==`)
-   *           to `elem`, or `-1`, if none exists.
    */
   def lastIndexOf[B >: A](elem: B, end: Int): Int = lastIndexWhere(elem ==, end)
 
@@ -396,9 +377,6 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
    *  @usecase def reverseMap[B](f: A => B): $Coll[B]
    *
    *  Note: `xs.reverseMap(f)` is the same as `xs.reverse.map(f)` but might be more efficient.
-   *
-   *  @param f      the function to apply to each element.
-   *  @tparam B     the element type of the returned collection.
    *  @return       a new $coll resulting from applying the given function
    *                `f` to each element of this $coll and collecting the results in reversed order.
    */
@@ -427,13 +405,13 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
   @deprecated("use `reverseIterator' instead")
   def reversedElements = reverseIterator
 
-  /** Checks whether this $coll contains the given sequence at a given index.
+  /** Tests whether this $coll contains the given sequence at a given index.
    *
    * If the both the receiver object, <code>this</code> and
    * the argument, <code>that</code> are infinite sequences
    * this method may not terminate.
    *
-   * @param  that    the candidate sequence
+   * @param  that    the sequence to test
    * @param  offset  the index where the sequence is searched.
    * @return `true` if the sequence `that` is contained in this $coll at index `offset`,
    *         otherwise `false`.
@@ -448,16 +426,18 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
     !j.hasNext
   }
 
-  /** Checks whether this $coll starts with the given sequence.
+  /** Tests whether this $coll starts with the given sequence.
    *
-   * @param  that    the candidate sequence
+   * @param  that    the sequence to test
    * @return `true` if this collection has `that` as a prefix, `false` otherwise.
    * otherwise false
    */
   def startsWith[B](that: Seq[B]): Boolean = startsWith(that, 0)
 
-  /** @return true if this sequence end with that sequence
-   *  @see String.endsWith
+  /** Tests whether this $coll ends with the given sequence.
+   *  $willNotTerminateInf
+   *  @param  that    the sequence to test
+   *  @return `true` if this $coll has `that` as a suffix, `false` otherwise.
    */
   def endsWith[B](that: Seq[B]): Boolean = {
     val i = this.iterator.drop(length - that.length)
@@ -469,16 +449,26 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
     !j.hasNext
   }
 
-  /** @return -1 if <code>that</code> not contained in this, otherwise the
-   *  first index where <code>that</code> is contained.
+  /** Finds first index where this $coll contains a given sequence.
+   *  $mayNotTerminateInf
+   *  @param  that    the sequence to test
+   *  @return  the first index such that the elements of this $coll starting at this index
+   *           match the elements of sequence `that`, or `-1` of no such subsequence exists.
    */
   def indexOfSlice[B >: A](that: Seq[B]): Int = indexOfSlice(that, 0)
 
-  def indexOfSlice[B >: A](that: Seq[B], fromIndex: Int): Int =
+  /** Finds first index where this $coll contains a given sequence after or at a start index.
+   *  $mayNotTerminateInf
+   *  @param  that    the sequence to test
+   *  @param  from    the start index
+   *  @return  the first index `>= from` such that the elements of this $coll starting at this index
+   *           match the elements of sequence `that`, or `-1` of no such subsequence exists.
+   */
+  def indexOfSlice[B >: A](that: Seq[B], from: Int): Int =
     if (this.hasDefiniteSize && that.hasDefiniteSize)
-      SeqLike.indexOf(thisCollection, 0, length, that, 0, that.length, fromIndex)
+      SeqLike.indexOf(thisCollection, 0, length, that, 0, that.length, from)
     else {
-      var i = fromIndex
+      var i = from
       var s: Seq[A] = thisCollection drop i
       while (!s.isEmpty) {
         if (s startsWith that)
@@ -490,61 +480,71 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
       -1
     }
 
-  /** @return -1 if <code>that</code> not contained in this, otherwise the
-  *  last index where <code>that</code> is contained.
-  *  @note may not terminate for infinite-sized collections.
-  */
+  /** Finds last index where this $coll contains a given sequence.
+   *  $willNotTerminateInf
+   *  @param  that    the sequence to test
+   *  @return  the last index such that the elements of this $coll starting a this index
+   *           match the elements of sequence `that`, or `-1` of no such subsequence exists.
+   */
   def lastIndexOfSlice[B >: A](that: Seq[B]): Int = lastIndexOfSlice(that, that.length)
 
-  // since there's no way to find the last index in an infinite sequence,
-  // we just document it may not terminate and assume it will.
-  def lastIndexOfSlice[B >: A](that: Seq[B], fromIndex: Int): Int =
-    SeqLike.lastIndexOf(thisCollection, 0, length, that, 0, that.length, fromIndex)
+  /** Finds last index where this $coll contains a given sequence before or at a given end index.
+   *  @param  that    the sequence to test
+   *  @param  end     the end idnex
+   *  @return  the last index `<= end` such that the elements of this $coll starting at this index
+   *           match the elements of sequence `that`, or `-1` of no such subsequence exists.
+   */
+  def lastIndexOfSlice[B >: A](that: Seq[B], end: Int): Int =
+    SeqLike.lastIndexOf(thisCollection, 0, length, that, 0, that.length, end)
 
-  /** Tests if the given value <code>elem</code> is a member of this
-   *  sequence.
+  /** Tests whether this $coll contains a given value as an element.
+   *  $mayNotTerminateInf
    *
-   *  @param elem element whose membership has to be tested.
-   *  @return     <code>true</code> iff there is an element of this sequence
-   *              which is equal (w.r.t. <code>==</code>) to <code>elem</code>.
+   *  @param elem  the element to test.
+   *  @return     `true` if this $coll has an element that is
+   *               is equal (wrt `==`) to `elem`, `false` otherwise.
    */
   def contains(elem: Any): Boolean = exists (_ == elem)
 
-  /** <p>
-   *    Computes the multiset union of this sequence and the given sequence
-   *    <code>that</code>. For example:
-   *  </p><pre>
-   *    <b>val</b> xs = List(1, 1, 2)
-   *    <b>val</b> ys = List(1, 2, 2, 3)
-   *    println(xs union ys)  // prints "List(1, 1, 2, 1, 2, 2, 3)"
-   *    println(ys union xs)  // prints "List(1, 2, 2, 3, 1, 1, 2)"
-   *  </pre>
+  /** Produces a new sequence which contains all elements of this $coll and also all elements of
+   *  a given sequence. `xs union ys`  is equivalent to `xs ++ ys`.
+   *
+   *  Another way to express this
+   *  is that `xs union ys` computes the order-presevring multi-set union of `xs` and `ys`.
+   *  `union` is hence a counter-oart of `diff` and `intersect` which also work on multi-sets.
+   *
+   *  $willNotTerminateInf
    *
-   *  @param that the sequence of elements to add to the sequence.
-   *  @return     a sequence containing the elements of this
-   *              sequence and those of the given sequence <code>that</code>.
+   *  @param that   the sequence to add.
+   *  @tparam B     the element type of the returned $coll.
+   *  @tparam That  $thatinfo
+   *  @param bf     $bfinfo
+   *  @return       a new collection of type `That` which contains all elements of this $coll
+   *                followed by all elements of `that`.
+   *  @usecase def union(that: Seq[A]): $Coll[A]
+   *  @return       a new $coll which contains all elements of this $coll
+   *                followed by all elements of `that`.
    */
   def union[B >: A, That](that: Seq[B])(implicit bf: CanBuildFrom[Repr, B, That]): That =
     this ++ that
 
-  /** <p>
-   *    Computes the multiset difference between this sequence and the
-   *    given sequence <code>that</code>. If an element appears more
-   *    than once in both sequences, the difference contains <i>m</i> copies
-   *    of that element, where <i>m</i> is the difference between the
-   *    number of times the element appears in this sequence and the number
-   *    of times it appears in <code>that</code>. For example:
-   *  </p><pre>
-   *    <b>val</b> xs = List(1, 1, 2)
-   *    <b>val</b> ys = List(1, 2, 2, 3)
-   *    println(xs diff ys)  // prints "List(1)"
-   *    println(xs -- ys)    // prints "List()"
-   *  </pre>
-   *
-   *  @param that the sequence of elements to remove from this sequence.
-   *  @return     the sequence of elements contained only in this sequence plus
-   *              <i>m</i> copies of each element present in both sequences,
-   *              where <i>m</i> is defined as above.
+  /** Computes the multiset difference between this $coll and another sequence.
+   *
+   *  @param that   the sequence of elements to remove
+   *  @tparam B     the element type of the returned $coll.
+   *  @tparam That  $thatinfo
+   *  @param bf     $bfinfo
+   *  @return       a new collection of type `That` which contains all elements of this $coll
+   *                except some of occurrences of elements that also appear in `that`.
+   *                If an element value `x` appears
+   *                ''n'' times in `that`, then the first ''n'' occurrences of `x` will not form
+   *                part of the result, but any following occurrences will.
+   *  @usecase def union(that: Seq[A]): $Coll[A]
+   *  @return       a new $coll which contains all elements of this $coll
+   *                except some of occurrences of elements that also appear in `that`.
+   *                If an element value `x` appears
+   *                ''n'' times in `that`, then the first ''n'' occurrences of `x` will not form
+   *                part of the result, but any following occurrences will.
    */
   def diff[B >: A, That](that: Seq[B]): Repr = {
     val occ = occCounts(that)
@@ -555,22 +555,23 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
     b.result
   }
 
-  /** <p>
-   *    Computes the multiset intersection between this sequence and the
-   *    given sequence <code>that</code>; the intersection contains <i>m</i>
-   *    copies of an element contained in both sequences, where <i>m</i> is
-   *    the smaller of the number of times the element appears in this
-   *    sequence or in <code>that</code>. For example:
-   *  </p><pre>
-   *    <b>val</b> xs = List(1, 1, 2)
-   *    <b>val</b> ys = List(3, 2, 2, 1)
-   *    println(xs intersect ys)  // prints "List(1, 2)"
-   *    println(ys intersect xs)  // prints "List(2, 1)"
-   *  </pre>
-   *
-   *  @param that the sequence to intersect.
-   *  @return     the sequence of elements contained both in this sequence and
-   *              in the given sequence <code>that</code>.
+  /** Computes the multiset intersection between this $coll and another sequence.
+   *
+   *  @param that   the sequence of elements to intersect with.
+   *  @tparam B     the element type of the returned $coll.
+   *  @tparam That  $thatinfo
+   *  @param bf     $bfinfo
+   *  @return       a new collection of type `That` which contains all elements of this $coll
+   *                which also appear in `that`.
+   *                If an element value `x` appears
+   *                ''n'' times in `that`, then the first ''n'' occurrences of `x` will be retained
+   *                in the result, but any following occurrences will be omitted.
+   *  @usecase def union(that: Seq[A]): $Coll[A]
+   *  @return       a new $coll which contains all elements of this $coll
+   *                which also appear in `that`.
+   *                If an element value `x` appears
+   *                ''n'' times in `that`, then the first ''n'' occurrences of `x` will be retained
+   *                in the result, but any following occurrences will be omitted.
    */
   def intersect[B >: A, That](that: Seq[B]): Repr = {
     val occ = occCounts(that)
@@ -589,8 +590,9 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
     occ
   }
 
-  /** Builds a new sequence from this sequence in which any duplicates (wrt to ==) removed.
-   *  Among duplicate elements, only the first one is retained in the result sequence
+  /** Builds a new $coll from this $coll without any duplicate elements.
+   *
+   *  @return  A new $coll which contains the first occurrence of every element of this $coll.
    */
   def removeDuplicates: Repr = {
     val b = newBuilder
@@ -604,9 +606,21 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
     b.result
   }
 
-  /** A new sequence, consisting of all elements of current sequence
-   *  except that `replaced` elements starting from `from` are replaced
-   *  by `patch`.
+  /** Produces a new $coll where a slice of elements in this $coll is replaced by another sequence.
+   *
+   *  @param  from     the index of the first replaced element
+   *  @param  patch    the replacement sequence
+   *  @param  replaced the number of elements to drop in the original $coll
+   *  @tparam B        the element type of the returned $coll.
+   *  @tparam That     $thatinfo
+   *  @param bf        $bfinfo
+   *  @return          a new collection of type `That` consisting of all elements of this $coll
+   *                   except that `replaced` elements starting from `from` are replaced
+   *                   by `patch`.
+   *  @usecase def patch(from: Int, that: Seq[A], replaced: Int): $Coll[A]
+   *  @return          a new $coll consisting of all elements of this $coll
+   *                   except that `replaced` elements starting from `from` are replaced
+   *                   by `patch`.
    */
   def patch[B >: A, That](from: Int, patch: Seq[B], replaced: Int)(implicit bf: CanBuildFrom[Repr, B, That]): That = {
     val b = bf(repr)
@@ -711,10 +725,10 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] { self =>
    */
   def sortBy[B](f: A => B)(implicit ord: Ordering[B]): Repr = sortWith(ord on f)
 
-  /**
-   *  Overridden for efficiency.
+  /** Converts this $coll to a sequence.
+   *  $willNotTerminateInf
    *
-   *  @return  the sequence itself
+   *  Overridden for efficiency.
    */
   override def toSeq: Seq[A] = thisCollection
 
diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index 0ff6227a3a..fe3dbb7dcf 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -127,9 +127,6 @@ self =>
    *              but this is not necessary.
    *
    *  @usecase def foreach(f: A => Unit): Unit
-   *
-   *  @param  f   the function that is applied for its side-effect to every element.
-   *              The result of function `f` is discarded.
    */
   def foreach[U](f: A => U): Unit
 
@@ -156,6 +153,8 @@ self =>
 
   /** The size of this $coll.
    *
+   *  $willNotTerminateInf
+   *
    *  @return    the number of elements in this $coll.
    */
   def size: Int = {
@@ -186,7 +185,6 @@ self =>
    *
    *  @usecase def ++(that: Traversable[A]): $Coll[A]
    *
-   *  @param that   the traversable to append.
    *  @return       a new $coll which contains all elements of this $coll
    *                followed by all elements of `that`.
    */
@@ -208,7 +206,6 @@ self =>
    *
    *  @usecase def ++(that: Iterator[A]): $Coll[A]
    *
-   *  @param that   the iterator to append.
    *  @return       a new $coll which contains all elements of this $coll
    *                followed by all elements of `that`.
    */
@@ -230,8 +227,6 @@ self =>
    *
    *  @usecase def map[B](f: A => B): $Coll[B]
    *
-   *  @param f      the function to apply to each element.
-   *  @tparam B     the element type of the returned collection.
    *  @return       a new $coll resulting from applying the given function
    *                `f` to each element of this $coll and collecting the results.
    */
@@ -253,8 +248,6 @@ self =>
    *
    *  @usecase def flatMap[B](f: A => Traversable[B]): $Coll[B]
    *
-   *  @param f      the function to apply to each element.
-   *  @tparam B     the element type of the returned collection.
    *  @return       a new $coll resulting from applying the given collection-valued function
    *                `f` to each element of this $coll and concatenating the results.
    */
@@ -298,7 +291,6 @@ self =>
    *
    *  @usecase def partialMap[B](pf: PartialFunction[Any, B]): $Coll[B]
    *
-   *  @param pf     the partial function which filters and maps the $coll.
    *  @return       a new $coll resulting from applying the given partial function
    *                `pf` to each element on which it is defined and collecting the results.
    *                The order of the elements is preserved.
@@ -919,10 +911,6 @@ self =>
    *
    *
    *  @usecase def copyToArray(xs: Array[A], start: Int, len: Int): Unit
-   *
-   *  @param  xs     the array to fill.
-   *  @param  start  the starting index.
-   *  @param  len    the maximal number of elements to copy.
    */
   def copyToArray[B >: A](xs: Array[B], start: Int, len: Int) {
     var i = start
@@ -949,9 +937,6 @@ self =>
    *  @tparam B      the type of the elements of the array.
    *
    *  @usecase def copyToArray(xs: Array[A], start: Int): Unit
-   *
-   *  @param  xs     the array to fill.
-   *  @param  start  the starting index.
    */
   def copyToArray[B >: A](xs: Array[B], start: Int) {
     copyToArray(xs, start, xs.length - start)
@@ -1165,8 +1150,6 @@ self =>
      *
      *  @usecase def map[B](f: A => B): $Coll[B]
      *
-     *  @param f      the function to apply to each element.
-     *  @tparam B     the element type of the returned collection.
      *  @return       a new $coll resulting from applying the given function
      *                `f` to each element of the outer $coll that satisfies predicate `p`
      *                and collecting the results.
@@ -1190,8 +1173,6 @@ self =>
      *
      *  @usecase def flatMap[B](f: A => Traversable[B]): $Coll[B]
      *
-     *  @param f      the function to apply to each element.
-     *  @tparam B     the element type of the returned collection.
      *  @return       a new $coll resulting from applying the given collection-valued function
      *                `f` to each element of the outer $coll that satisfies predicate `p` and concatenating the results.
      */
@@ -1213,9 +1194,6 @@ self =>
      *              but this is not necessary.
      *
      *  @usecase def foreach(f: A => Unit): Unit
-     *
-     *  @param  f   the function that is applied for its side-effect to every element.
-     *              The result of function `f` is discarded.
      */
     def foreach[U](f: A => U): Unit =
       for (x <- self)