Adapted usecases to full signature display

14 files changed, 359 insertions, 243 deletions

diff --git a/src/library/scala/collection/GenIterableLike.scala b/src/library/scala/collection/GenIterableLike.scala
index 7e68733afd..8fa5981969 100644
--- a/src/library/scala/collection/GenIterableLike.scala
+++ b/src/library/scala/collection/GenIterableLike.scala
@@ -40,17 +40,18 @@ trait GenIterableLike[+A, +Repr] extends Any with GenTraversableLike[A, Repr] {
 
   /** Checks if the other iterable collection contains the same elements in the same order as this $coll.
    *
-   *  $orderDependent
-   *  $willNotTerminateInf
-   *
    *  @param that  the collection to compare with.
    *  @tparam B    the type of the elements of collection `that`.
    *  @return `true`, if both collections contain the same elements in the same order, `false` otherwise.
    *
    *  @usecase  def sameElements(that: GenIterable[A]): Boolean
+   *    @inheritdoc
    *
-   *  @param that  the collection to compare with.
-   *  @return `true`, if both collections contain the same elements in the same order, `false` otherwise.
+   *    $orderDependent
+   *    $willNotTerminateInf
+   *
+   *    @param that  the collection to compare with.
+   *    @return `true`, if both collections contain the same elements in the same order, `false` otherwise.
    */
   def sameElements[A1 >: A](that: GenIterable[A1]): Boolean
 
@@ -58,8 +59,6 @@ trait GenIterableLike[+A, +Repr] extends Any with GenTraversableLike[A, Repr] {
    *  by combining corresponding elements in pairs.
    *  If one of the two collections is longer than the other, its remaining elements are ignored.
    *
-   *  $orderDependent
-   *
    *  @param   that  The iterable providing the second half of each result pair
    *  @tparam  A1    the type of the first half of the returned pairs (this is always a supertype
    *                 of the collection's element type `A`).
@@ -71,19 +70,20 @@ trait GenIterableLike[+A, +Repr] extends Any with GenTraversableLike[A, Repr] {
    *                 of the returned collection is the minimum of the lengths of this $coll and `that`.
    *
    *  @usecase def zip[B](that: GenIterable[B]): $Coll[(A, B)]
+   *    @inheritdoc
    *
-   *  @param   that  The iterable providing the second half of each result pair
-   *  @tparam  B     the type of the second half of the returned pairs
-   *  @return        a new $coll containing pairs consisting of
-   *                 corresponding elements of this $coll and `that`. The length
-   *                 of the returned collection is the minimum of the lengths of this $coll and `that`.
+   *    $orderDependent
+   *
+   *    @param   that  The iterable providing the second half of each result pair
+   *    @tparam  B     the type of the second half of the returned pairs
+   *    @return        a new $coll containing pairs consisting of
+   *                   corresponding elements of this $coll and `that`. The length
+   *                   of the returned collection is the minimum of the lengths of this $coll and `that`.
    */
   def zip[A1 >: A, B, That](that: GenIterable[B])(implicit bf: CBF[Repr, (A1, B), That]): That
 
   /** Zips this $coll with its indices.
    *
-   *  $orderDependent
-   *
    *  @tparam  A1    the type of the first half of the returned pairs (this is always a supertype
    *                 of the collection's element type `A`).
    *  @tparam  That  the class of the returned collection. Where possible, `That` is
@@ -98,11 +98,14 @@ trait GenIterableLike[+A, +Repr] extends Any with GenTraversableLike[A, Repr] {
    *                 $coll paired with their index. Indices start at `0`.
    *
    *  @usecase def zipWithIndex: $Coll[(A, Int)]
+   *    @inheritdoc
    *
-   *  @return        A new $coll containing pairs consisting of all elements of this
-   *                 $coll paired with their index. Indices start at `0`.
-   *  @example
-   *    `List("a", "b", "c").zipWithIndex = List(("a", 0), ("b", 1), ("c", 2))`
+   *    $orderDependent
+   *
+   *    @return        A new $coll containing pairs consisting of all elements of this
+   *                   $coll paired with their index. Indices start at `0`.
+   *    @example
+   *      `List("a", "b", "c").zipWithIndex = List(("a", 0), ("b", 1), ("c", 2))`
    *
    */
   def zipWithIndex[A1 >: A, That](implicit bf: CBF[Repr, (A1, Int), That]): That
@@ -112,8 +115,6 @@ trait GenIterableLike[+A, +Repr] extends Any with GenTraversableLike[A, Repr] {
    *  If one of the two collections is shorter than the other,
    *  placeholder elements are used to extend the shorter collection to the length of the longer.
    *
-   *  $orderDependent
-   *
    *  @param that     the iterable providing the second half of each result pair
    *  @param thisElem the element to be used to fill up the result if this $coll is shorter than `that`.
    *  @param thatElem the element to be used to fill up the result if `that` is shorter than this $coll.
@@ -124,16 +125,19 @@ trait GenIterableLike[+A, +Repr] extends Any with GenTraversableLike[A, Repr] {
    *                 If `that` is shorter than this $coll, `thatElem` values are used to pad the result.
    *
    *  @usecase def zipAll[B](that: Iterable[B], thisElem: A, thatElem: B): $Coll[(A, B)]
-   *
-   *  @param   that  The iterable providing the second half of each result pair
-   *  @param thisElem the element to be used to fill up the result if this $coll is shorter than `that`.
-   *  @param thatElem the element to be used to fill up the result if `that` is shorter than this $coll.
-   *  @tparam  B     the type of the second half of the returned pairs
-   *  @return        a new $coll containing pairs consisting of
-   *                 corresponding elements of this $coll and `that`. The length
-   *                 of the returned collection is the maximum of the lengths of this $coll and `that`.
-   *                 If this $coll is shorter than `that`, `thisElem` values are used to pad the result.
-   *                 If `that` is shorter than this $coll, `thatElem` values are used to pad the result.
+   *    @inheritdoc
+   *
+   *    $orderDependent
+   *
+   *    @param   that  The iterable providing the second half of each result pair
+   *    @param thisElem the element to be used to fill up the result if this $coll is shorter than `that`.
+   *    @param thatElem the element to be used to fill up the result if `that` is shorter than this $coll.
+   *    @tparam  B     the type of the second half of the returned pairs
+   *    @return        a new $coll containing pairs consisting of
+   *                   corresponding elements of this $coll and `that`. The length
+   *                   of the returned collection is the maximum of the lengths of this $coll and `that`.
+   *                   If this $coll is shorter than `that`, `thisElem` values are used to pad the result.
+   *                   If `that` is shorter than this $coll, `thatElem` values are used to pad the result.
    */
   def zipAll[B, A1 >: A, That](that: GenIterable[B], thisElem: A1, thatElem: B)(implicit bf: CBF[Repr, (A1, B), That]): That
 
diff --git a/src/library/scala/collection/GenMapLike.scala b/src/library/scala/collection/GenMapLike.scala
index 12ecbcf140..114169c849 100644
--- a/src/library/scala/collection/GenMapLike.scala
+++ b/src/library/scala/collection/GenMapLike.scala
@@ -41,6 +41,8 @@ trait GenMapLike[A, +B, +Repr] extends GenIterableLike[(A, B), Repr] with Equals
    *   @return  the value associated with `key` if it exists,
    *            otherwise the result of the `default` computation.
    *   @usecase def getOrElse(key: A, default: => B): B
+   *     @inheritdoc
+   *     @tparam  B        the result type of the default computation.
    */
   def getOrElse[B1 >: B](key: A, default: => B1): B1
 
diff --git a/src/library/scala/collection/GenSeqLike.scala b/src/library/scala/collection/GenSeqLike.scala
index cb0e96fcbb..755abcd2bf 100644
--- a/src/library/scala/collection/GenSeqLike.scala
+++ b/src/library/scala/collection/GenSeqLike.scala
@@ -115,21 +115,21 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
 
   /** Finds index of first occurrence of some value in this $coll.
    *
-   *  $mayNotTerminateInf
-   *
    *  @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 `==`)
    *           to `elem`, or `-1`, if none exists.
    *
    *  @usecase def indexOf(elem: A): Int
+   *    @inheritdoc
+   *
+   *    $mayNotTerminateInf
+   *
    */
   def indexOf[B >: A](elem: B): Int = indexOf(elem, 0)
 
   /** Finds index of first occurrence of some value in this $coll after or at some start index.
    *
-   *  $mayNotTerminateInf
-   *
    *  @param   elem   the element value to search for.
    *  @tparam  B      the type of the element `elem`.
    *  @param   from   the start index
@@ -137,19 +137,25 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
    *           to `elem`, or `-1`, if none exists.
    *
    *  @usecase def indexOf(elem: A, from: Int): Int
+   *    @inheritdoc
+   *    
+   *    $mayNotTerminateInf
+   *
    */
   def indexOf[B >: A](elem: B, from: Int): Int = indexWhere(elem ==, from)
 
   /** Finds index of last occurrence of some value in this $coll.
    *
-   *  $willNotTerminateInf
-   *
    *  @param   elem   the element value to search for.
    *  @tparam  B      the type of the element `elem`.
    *  @return  the index of the last element of this $coll that is equal (wrt `==`)
    *           to `elem`, or `-1`, if none exists.
    *
    *  @usecase def lastIndexOf(elem: A): Int
+   *    @inheritdoc
+   *
+   *    $willNotTerminateInf
+   *
    */
   def lastIndexOf[B >: A](elem: B): Int = lastIndexWhere(elem ==)
 
@@ -162,6 +168,7 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
    *           to `elem`, or `-1`, if none exists.
    *
    *  @usecase def lastIndexOf(elem: A, end: Int): Int
+   *    @inheritdoc
    */
   def lastIndexOf[B >: A](elem: B, end: Int): Int = lastIndexWhere(elem ==, end)
 
@@ -195,10 +202,6 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
    *  Builds a new collection by applying a function to all elements of this $coll and
    *  collecting the results in reversed order.
    *
-   *  $willNotTerminateInf
-   *
-   *  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.
    *  @tparam That  $thatinfo
@@ -207,10 +210,14 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
    *                `f` to each element of this $coll and collecting the results in reversed order.
    *
    *  @usecase def reverseMap[B](f: A => B): $Coll[B]
+   *    @inheritdoc
    *
-   *  Note: `xs.reverseMap(f)` is the same as `xs.reverse.map(f)` but might be more efficient.
-   *  @return       a new $coll resulting from applying the given function
-   *                `f` to each element of this $coll and collecting the results in reversed order.
+   *    $willNotTerminateInf
+   *
+   *    Note: `xs.reverseMap(f)` is the same as `xs.reverse.map(f)` but might be more efficient.
+   *
+   *    @return       a new $coll resulting from applying the given function
+   *                  `f` to each element of this $coll and collecting the results in reversed order.
    */
   def reverseMap[B, That](f: A => B)(implicit bf: CanBuildFrom[Repr, B, That]): That
 
@@ -254,10 +261,13 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
    *  @return          a new $coll consisting of all elements of this $coll
    *                   except that `replaced` elements starting from `from` are replaced
    *                   by `patch`.
+   *
    *  @usecase def patch(from: Int, that: GenSeq[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`.
+   *    @inheritdoc
+   *
+   *    @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: GenSeq[B], replaced: Int)(implicit bf: CanBuildFrom[Repr, B, That]): That
 
@@ -268,20 +278,33 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
    *  @tparam That     $thatinfo
    *  @param bf        $bfinfo
    *  @return a new $coll` which is a copy of this $coll with the element at position `index` replaced by `elem`.
+   *
    *  @usecase def updated(index: Int, elem: A): $Coll[A]
-   *  @return a copy of this $coll with the element at position `index` replaced by `elem`.
+   *    @inheritdoc
+   *
+   *    @return a copy of this $coll with the element at position `index` replaced by `elem`.
    */
   def updated[B >: A, That](index: Int, elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That
 
   /** A copy of the $coll with an element prepended.
    *
-   * Note that :-ending operators are right associative (see example).
-   * A mnemonic for `+:` vs. `:+` is: the COLon goes on the COLlection side.
+   *  @param  elem   the prepended element
+   *  @tparam B      the element type of the returned $coll.
+   *  @tparam That   $thatinfo
+   *  @param bf      $bfinfo
+   *  @return a new collection of type `That` consisting of `elem` followed
+   *          by all elements of this $coll.
+   *
+   *  @usecase def +:(elem: A): $Coll[A]
+   *    @inheritdoc
+   *
+   *    Note that :-ending operators are right associative (see example).
+   *    A mnemonic for `+:` vs. `:+` is: the COLon goes on the COLlection side.
    *
-   * Also, the original $coll is not modified, so you will want to capture the result.
+   *    Also, the original $coll is not modified, so you will want to capture the result.
    *
-   *  Example:
-   *  {{{
+   *    Example:
+   *    {{{
    *      scala> val x = LinkedList(1)
    *      x: scala.collection.mutable.LinkedList[Int] = LinkedList(1)
    *
@@ -290,17 +313,10 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
    *
    *      scala> println(x)
    *      LinkedList(1)
-   *  }}}
+   *    }}}
    *
-   *  @param  elem   the prepended element
-   *  @tparam B      the element type of the returned $coll.
-   *  @tparam That   $thatinfo
-   *  @param bf      $bfinfo
-   *  @return a new collection of type `That` consisting of `elem` followed
-   *          by all elements of this $coll.
-   *  @usecase def +:(elem: A): $Coll[A]
-   *  @return a new $coll consisting of `elem` followed
-   *          by all elements of this $coll.
+   *    @return a new $coll consisting of `elem` followed
+   *            by all elements of this $coll.
    */
   def +:[B >: A, That](elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That
 
@@ -308,18 +324,20 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
    *
    *  A mnemonic for `+:` vs. `:+` is: the COLon goes on the COLlection side.
    *
-   *  $willNotTerminateInf
    *  @param  elem   the appended element
    *  @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 followed by `elem`.
+   *
    *  @usecase def :+(elem: A): $Coll[A]
-   *  @return a new $coll consisting of
-   *          all elements of this $coll followed by `elem`.
-   *  @example
-   *  {{{
+   *    @inheritdoc
+   *
+   *    $willNotTerminateInf
+   *
+   *    Example:
+   *    {{{
    *       scala> import scala.collection.mutable.LinkedList
    *       import scala.collection.mutable.LinkedList
    *
@@ -331,7 +349,10 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
    *
    *       scala> println(a)
    *       LinkedList(1)
-   *  }}}
+   *    }}}
+   *
+   *    @return a new $coll consisting of
+   *            all elements of this $coll followed by `elem`.
    */
   def :+[B >: A, That](elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That
 
@@ -346,9 +367,11 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
    *          all elements of this $coll followed by the minimal number of occurrences of `elem` so
    *          that the resulting collection has a length of at least `len`.
    *  @usecase def padTo(len: Int, elem: A): $Coll[A]
-   *  @return a new $coll consisting of
-   *          all elements of this $coll followed by the minimal number of occurrences of `elem` so
-   *          that the resulting $coll has a length of at least `len`.
+   *    @inheritdoc
+   *
+   *    @return a new $coll consisting of
+   *            all elements of this $coll followed by the minimal number of occurrences of `elem` so
+   *            that the resulting $coll has a length of at least `len`.
    */
   def padTo[B >: A, That](len: Int, elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That
 
@@ -368,13 +391,6 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
 
   /** 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`.
-   *  $willNotTerminateInf
-   *
-   *  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-part of `diff` and `intersect` which also work on multi-sets.
-   *
-   *  $willNotTerminateInf
    *
    *  @param that   the sequence to add.
    *  @tparam B     the element type of the returned $coll.
@@ -382,9 +398,18 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
    *  @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: GenSeq[A]): $Coll[A]
-   *  @return       a new $coll which contains all elements of this $coll
-   *                followed by all elements of `that`.
+   *    @inheritdoc
+   *
+   *    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-part of `diff` and `intersect` which also work on multi-sets.
+   *
+   *    $willNotTerminateInf
+   *
+   *    @return       a new $coll which contains all elements of this $coll
+   *                  followed by all elements of `that`.
    */
   def union[B >: A, That](that: GenSeq[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = this ++ that
 
@@ -393,7 +418,6 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
     union(that: GenSeq[B])(bf)
 
   /** Computes the multiset difference between this $coll and another sequence.
-   *  $willNotTerminateInf
    *
    *  @param that   the sequence of elements to remove
    *  @tparam B     the element type of the returned $coll.
@@ -404,17 +428,21 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
    *                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 diff(that: GenSeq[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.
+   *    @inheritdoc
+   *
+   *    $willNotTerminateInf
+   *
+   *    @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: GenSeq[B]): Repr
 
   /** Computes the multiset intersection between this $coll and another sequence.
-   *  $mayNotTerminateInf
    *
    *  @param that   the sequence of elements to intersect with.
    *  @tparam B     the element type of the returned $coll.
@@ -425,12 +453,17 @@ trait GenSeqLike[+A, +Repr] extends Any with GenIterableLike[A, Repr] with Equal
    *                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 intersect(that: GenSeq[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.
+   *    @inheritdoc
+   *
+   *    $mayNotTerminateInf
+   *
+   *    @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: GenSeq[B]): Repr
 
diff --git a/src/library/scala/collection/GenTraversableLike.scala b/src/library/scala/collection/GenTraversableLike.scala
index dd5f602c41..fd03e0f446 100644
--- a/src/library/scala/collection/GenTraversableLike.scala
+++ b/src/library/scala/collection/GenTraversableLike.scala
@@ -136,6 +136,7 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
    *              but this is not necessary.
    *
    *  @usecase def foreach(f: A => Unit): Unit
+   *    @inheritdoc
    */
   def foreach[U](f: A => U): Unit
 
@@ -149,17 +150,15 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
    *                `f` to each element of this $coll and collecting the results.
    *
    *  @usecase def map[B](f: A => B): $Coll[B]
-   *
-   *  @return       a new $coll resulting from applying the given function
-   *                `f` to each element of this $coll and collecting the results.
+   *    @inheritdoc
+   *    @return       a new $coll resulting from applying the given function
+   *                  `f` to each element of this $coll and collecting the results.
    */
   def map[B, That](f: A => B)(implicit bf: CanBuildFrom[Repr, B, That]): That
 
   /** Builds a new collection by applying a partial function to all elements of this $coll
    *  on which the function is defined.
    *
-   *  $collectExample
-   *
    *  @param pf     the partial function which filters and maps the $coll.
    *  @tparam B     the element type of the returned collection.
    *  @tparam That  $thatinfo
@@ -169,36 +168,18 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
    *                The order of the elements is preserved.
    *
    *  @usecase def collect[B](pf: PartialFunction[A, B]): $Coll[B]
+   *    @inheritdoc
    *
-   *  @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.
+   *    $collectExample
+   *
+   *    @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.
    */
   def collect[B, That](pf: PartialFunction[A, B])(implicit bf: CanBuildFrom[Repr, B, That]): That
 
   /** Builds a new collection by applying a function to all elements of this $coll
-   *  and using the elements of the resulting collections. For example:
-   *
-   *  {{{
-   *  def getWords(lines: Seq[String]): Seq[String] = lines flatMap (line => line split "\\W+")
-   *  }}}
-   *
-   *  The type of the resulting collection is guided by the static type of $coll. This might
-   *  cause unexpected results sometimes. For example:
-   *
-   *  {{{
-   *  // lettersOf will return a Seq[Char] of likely repeated letters, instead of a Set
-   *  def lettersOf(words: Seq[String]) = words flatMap (word => word.toSet)
-   *
-   *  // lettersOf will return a Set[Char], not a Seq
-   *  def lettersOf(words: Seq[String]) = words.toSet flatMap (word => word.toSeq)
-   *
-   *  // xs will be a an Iterable[Int]
-   *  val xs = Map("a" -> List(11,111), "b" -> List(22,222)).flatMap(_._2)
-   *
-   *  // ys will be a Map[Int, Int]
-   *  val ys = Map("a" -> List(1 -> 11,1 -> 111), "b" -> List(2 -> 22,2 -> 222)).flatMap(_._2)
-   *  }}}
+   *  and using the elements of the resulting collections. 
    *
    *  @param f      the function to apply to each element.
    *  @tparam B     the element type of the returned collection.
@@ -208,33 +189,39 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
    *                `f` to each element of this $coll and concatenating the results.
    *
    *  @usecase def flatMap[B](f: A => GenTraversableOnce[B]): $Coll[B]
+   *    @inheritdoc
    *
-   *  @return       a new $coll resulting from applying the given collection-valued function
-   *                `f` to each element of this $coll and concatenating the results.
-   */
-  def flatMap[B, That](f: A => GenTraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That
-
-  /** Returns a new $coll containing the elements from the left hand operand followed by the elements from the
-   *  right hand operand. The element type of the $coll is the most specific superclass encompassing
-   *  the element types of the two operands (see example).
+   *    For example:
    *
-   * Example:
-   * {{{
-   *     scala> val a = LinkedList(1)
-   *     a: scala.collection.mutable.LinkedList[Int] = LinkedList(1)
+   *    {{{
+   *      def getWords(lines: Seq[String]): Seq[String] = lines flatMap (line => line split "\\W+")
+   *    }}}
    *
-   *     scala> val b = LinkedList(2)
-   *     b: scala.collection.mutable.LinkedList[Int] = LinkedList(2)
+   *    The type of the resulting collection is guided by the static type of $coll. This might
+   *    cause unexpected results sometimes. For example:
    *
-   *     scala> val c = a ++ b
-   *     c: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2)
+   *    {{{
+   *      // lettersOf will return a Seq[Char] of likely repeated letters, instead of a Set
+   *      def lettersOf(words: Seq[String]) = words flatMap (word => word.toSet)
    *
-   *     scala> val d = LinkedList('a')
-   *     d: scala.collection.mutable.LinkedList[Char] = LinkedList(a)
+   *      // lettersOf will return a Set[Char], not a Seq
+   *      def lettersOf(words: Seq[String]) = words.toSet flatMap (word => word.toSeq)
    *
-   *     scala> val e = c ++ d
-   *     e: scala.collection.mutable.LinkedList[AnyVal] = LinkedList(1, 2, a)
-   * }}}
+   *      // xs will be a an Iterable[Int]
+   *      val xs = Map("a" -> List(11,111), "b" -> List(22,222)).flatMap(_._2)
+   *
+   *      // ys will be a Map[Int, Int]
+   *      val ys = Map("a" -> List(1 -> 11,1 -> 111), "b" -> List(2 -> 22,2 -> 222)).flatMap(_._2)
+   *    }}}
+   *
+   *    @return       a new $coll resulting from applying the given collection-valued function
+   *                  `f` to each element of this $coll and concatenating the results.
+   */
+  def flatMap[B, That](f: A => GenTraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That
+
+  /** Returns a new $coll containing the elements from the left hand operand followed by the elements from the
+   *  right hand operand. The element type of the $coll is the most specific superclass encompassing
+   *  the element types of the two operands.
    *
    *  @param that   the traversable to append.
    *  @tparam B     the element type of the returned collection.
@@ -244,9 +231,28 @@ trait GenTraversableLike[+A, +Repr] extends Any with GenTraversableOnce[A] with
    *                of this $coll followed by all elements of `that`.
    *
    *  @usecase def ++[B](that: GenTraversableOnce[B]): $Coll[B]
+   *    @inheritdoc
+   *
+   *    Example:
+   *    {{{
+   *      scala> val a = LinkedList(1)
+   *      a: scala.collection.mutable.LinkedList[Int] = LinkedList(1)
+   *
+   *      scala> val b = LinkedList(2)
+   *      b: scala.collection.mutable.LinkedList[Int] = LinkedList(2)
+   *
+   *      scala> val c = a ++ b
+   *      c: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2)
+   *
+   *      scala> val d = LinkedList('a')
+   *      d: scala.collection.mutable.LinkedList[Char] = LinkedList(a)
+   *
+   *      scala> val e = c ++ d
+   *      e: scala.collection.mutable.LinkedList[AnyVal] = LinkedList(1, 2, a)
+   *    }}}
    *
-   *  @return       a new $coll which contains all elements of this $coll
-   *                followed by all elements of `that`.
+   *    @return       a new $coll which contains all elements of this $coll
+   *                  followed by all elements of `that`.
    */
   def ++[B >: A, That](that: GenTraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That
 
diff --git a/src/library/scala/collection/GenTraversableOnce.scala b/src/library/scala/collection/GenTraversableOnce.scala
index 67ea4cdb00..f18e2ab6bb 100644
--- a/src/library/scala/collection/GenTraversableOnce.scala
+++ b/src/library/scala/collection/GenTraversableOnce.scala
@@ -316,11 +316,12 @@ trait GenTraversableOnce[+A] extends Any {
    *   @return       the sum of all elements of this $coll with respect to the `+` operator in `num`.
    *
    *   @usecase def sum: A
+   *     @inheritdoc
    *
-   *   @return       the sum of all elements in this $coll of numbers of type `Int`.
-   *   Instead of `Int`, any other type `T` with an implicit `Numeric[T]` implementation
-   *   can be used as element type of the $coll and as result type of `sum`.
-   *   Examples of such types are: `Long`, `Float`, `Double`, `BigInt`.
+   *     @return       the sum of all elements in this $coll of numbers of type `Int`.
+   *     Instead of `Int`, any other type `T` with an implicit `Numeric[T]` implementation
+   *     can be used as element type of the $coll and as result type of `sum`.
+   *     Examples of such types are: `Long`, `Float`, `Double`, `BigInt`.
    *
    */
   def sum[A1 >: A](implicit num: Numeric[A1]): A1
@@ -333,11 +334,12 @@ trait GenTraversableOnce[+A] extends Any {
    *   @return       the product of all elements of this $coll with respect to the `*` operator in `num`.
    *
    *   @usecase def product: A
+   *     @inheritdoc
    *
-   *   @return       the product of all elements in this $coll of numbers of type `Int`.
-   *   Instead of `Int`, any other type `T` with an implicit `Numeric[T]` implementation
-   *   can be used as element type of the $coll and as result type of `product`.
-   *   Examples of such types are: `Long`, `Float`, `Double`, `BigInt`.
+   *     @return       the product of all elements in this $coll of numbers of type `Int`.
+   *     Instead of `Int`, any other type `T` with an implicit `Numeric[T]` implementation
+   *     can be used as element type of the $coll and as result type of `product`.
+   *     Examples of such types are: `Long`, `Float`, `Double`, `BigInt`.
    */
   def product[A1 >: A](implicit num: Numeric[A1]): A1
 
@@ -348,7 +350,9 @@ trait GenTraversableOnce[+A] extends Any {
    *  @return   the smallest element of this $coll with respect to the ordering `cmp`.
    *
    *  @usecase def min: A
-   *  @return   the smallest element of this $coll
+   *    @inheritdoc
+   *
+   *    @return   the smallest element of this $coll
    */
   def min[A1 >: A](implicit ord: Ordering[A1]): A
 
@@ -359,7 +363,9 @@ trait GenTraversableOnce[+A] extends Any {
    *  @return   the largest element of this $coll with respect to the ordering `cmp`.
    *
    *  @usecase def max: A
-   *  @return   the largest element of this $coll.
+   *    @inheritdoc
+   *
+   *    @return   the largest element of this $coll.
    */
   def max[A1 >: A](implicit ord: Ordering[A1]): A
 
@@ -387,12 +393,13 @@ trait GenTraversableOnce[+A] extends Any {
    *  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]): Unit
+   *    @inheritdoc
+   *
+   *    $willNotTerminateInf
    */
   def copyToArray[B >: A](xs: Array[B]): Unit
 
@@ -401,13 +408,14 @@ trait GenTraversableOnce[+A] extends Any {
    *  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.
    *  @param  start  the starting index.
    *  @tparam B      the type of the elements of the array.
    *
    *  @usecase def copyToArray(xs: Array[A], start: Int): Unit
+   *    @inheritdoc
+   *
+   *    $willNotTerminateInf
    */
   def copyToArray[B >: A](xs: Array[B], start: Int): Unit
 
@@ -450,15 +458,18 @@ trait GenTraversableOnce[+A] extends Any {
   def mkString: String
 
   /** Converts this $coll to an array.
-   *  $willNotTerminateInf
    *
    *  @tparam B the type of the elements of the array. A `ClassManifest` for
    *            this type must be available.
    *  @return   an array containing all elements of this $coll.
    *
    *  @usecase def toArray: Array[A]
-   *  @return  an array containing all elements of this $coll.
-   *           A `ClassManifest` must be available for the element type of this $coll.
+   *    @inheritdoc
+   *
+   *    $willNotTerminateInf
+   *
+   *    @return  an array containing all elements of this $coll.
+   *             A `ClassManifest` must be available for the element type of this $coll.
    */
   def toArray[A1 >: A: ClassManifest]: Array[A1]
 
@@ -530,11 +541,13 @@ trait GenTraversableOnce[+A] extends Any {
    *  pair in the map.  Duplicate keys will be overwritten by later keys:
    *  if this is an unordered collection, which key is in the resulting map
    *  is undefined.
-   *  $willNotTerminateInf
    *  @return    a map containing all elements of this $coll.
+   *
    *  @usecase   def toMap[T, U]: Map[T, U]
-   *  @return    a map of type `immutable.Map[T, U]`
-   *             containing all key/value pairs of type `(T, U)` of this $coll.
+   *    @inheritdoc
+   *    $willNotTerminateInf
+   *    @return    a map of type `immutable.Map[T, U]`
+   *               containing all key/value pairs of type `(T, U)` of this $coll.
    */
   def toMap[K, V](implicit ev: A <:< (K, V)): GenMap[K, V]
 }
diff --git a/src/library/scala/collection/IterableLike.scala b/src/library/scala/collection/IterableLike.scala
index 73d4efe125..fb6d154952 100644
--- a/src/library/scala/collection/IterableLike.scala
+++ b/src/library/scala/collection/IterableLike.scala
@@ -67,6 +67,7 @@ self =>
    *    Subclasses should re-implement this method if a more efficient implementation exists.
    *
    *  @usecase def foreach(f: A => Unit): Unit
+   *    @inheritdoc
    */
   def foreach[U](f: A => U): Unit =
     iterator.foreach(f)
diff --git a/src/library/scala/collection/Iterator.scala b/src/library/scala/collection/Iterator.scala
index d46d215e0c..7b57a91c41 100644
--- a/src/library/scala/collection/Iterator.scala
+++ b/src/library/scala/collection/Iterator.scala
@@ -322,7 +322,9 @@ trait Iterator[+A] extends TraversableOnce[A] {
    *  @return  a new iterator that first yields the values produced by this
    *  iterator followed by the values produced by iterator `that`.
    *  @note    Reuse: $consumesTwoAndProducesOneIterator
+   *
    *  @usecase def ++(that: => Iterator[A]): Iterator[A]
+   *    @inheritdoc
    */
   def ++[B >: A](that: => GenTraversableOnce[B]): Iterator[B] = new AbstractIterator[B] {
     // optimize a little bit to prevent n log n behavior.
@@ -609,7 +611,9 @@ trait Iterator[+A] extends TraversableOnce[A] {
    *          followed by the minimal number of occurrences of `elem` so
    *          that the number of produced values is at least `len`.
    *  @note    Reuse: $consumesAndProducesIterator
+   *
    *  @usecase def padTo(len: Int, elem: A): Iterator[A]
+   *    @inheritdoc
    */
   def padTo[A1 >: A](len: Int, elem: A1): Iterator[A1] = new AbstractIterator[A1] {
     private var count = 0
@@ -658,7 +662,9 @@ trait Iterator[+A] extends TraversableOnce[A] {
    *                  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.
    *  @note           Reuse: $consumesTwoAndProducesOneIterator
+   *
    *  @usecase def zipAll[B](that: Iterator[B], thisElem: A, thatElem: B): Iterator[(A, B)]
+   *    @inheritdoc
    */
   def zipAll[B, A1 >: A, B1 >: B](that: Iterator[B], thisElem: A1, thatElem: B1): Iterator[(A1, B1)] = new AbstractIterator[(A1, B1)] {
     def hasNext = self.hasNext || that.hasNext
@@ -682,7 +688,9 @@ trait Iterator[+A] extends TraversableOnce[A] {
    *              but this is not necessary.
    *
    *  @note    Reuse: $consumesIterator
+   *
    *  @usecase def foreach(f: A => Unit): Unit
+   *    @inheritdoc
    */
   def foreach[U](f: A =>  U) { while (hasNext) f(next()) }
 
@@ -1057,15 +1065,17 @@ trait Iterator[+A] extends TraversableOnce[A] {
    *  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  the starting index.
    *  @param  len    the maximal number of elements to copy.
    *  @tparam B      the type of the elements of the array.
    *
    *  @note    Reuse: $consumesIterator
+   *
    *  @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 = {
     var i = start
diff --git a/src/library/scala/collection/MapLike.scala b/src/library/scala/collection/MapLike.scala
index 07116e99dd..8f88e62791 100644
--- a/src/library/scala/collection/MapLike.scala
+++ b/src/library/scala/collection/MapLike.scala
@@ -91,14 +91,18 @@ self =>
    *  @param    kv the key/value pair
    *  @tparam   B1 the type of the value in the key/value pair.
    *  @return   a new map with the new binding added to this map
+   *
    *  @usecase  def + (kv: (A, B)): Map[A, B]
+   *    @inheritdoc
    */
   def + [B1 >: B] (kv: (A, B1)): Map[A, B1]
 
   /** Removes a key from this map, returning a new map.
    *  @param    key the key to be removed
    *  @return   a new map without a binding for `key`
+   *
    *  @usecase  def - (key: A): Map[A, B]
+   *    @inheritdoc
    */
   def - (key: A): This
 
@@ -115,7 +119,9 @@ self =>
    *   @tparam  B1       the result type of the default computation.
    *   @return  the value associated with `key` if it exists,
    *            otherwise the result of the `default` computation.
+   *
    *   @usecase def getOrElse(key: A, default: => B): B
+   *     @inheritdoc
    */
   def getOrElse[B1 >: B](key: A, default: => B1): B1 = get(key) match {
     case Some(v) => v
@@ -255,7 +261,9 @@ self =>
    *  @param    value the value
    *  @tparam   B1 the type of the added value
    *  @return   A new map with the new key/value mapping added to this map.
+   *
    *  @usecase  def updated(key: A, value: B): Map[A, B]
+   *    @inheritdoc
    */
   def updated [B1 >: B](key: A, value: B1): Map[A, B1] = this + ((key, value))
 
@@ -269,8 +277,10 @@ self =>
    *  @param    kvs the remaining key/value pairs
    *  @tparam   B1  the type of the added values
    *  @return   a new map with the given bindings added to this map
+   *
    *  @usecase  def + (kvs: (A, B)*): Map[A, B]
-   *  @param    the key/value pairs
+   *    @inheritdoc
+   *    @param    the key/value pairs
    */
   def + [B1 >: B] (kv1: (A, B1), kv2: (A, B1), kvs: (A, B1) *): Map[A, B1] =
     this + kv1 + kv2 ++ kvs
@@ -280,7 +290,9 @@ self =>
    *  @param    kvs the collection containing the added key/value pairs
    *  @tparam   B1  the type of the added values
    *  @return   a new map with the given bindings added to this map
+   *
    *  @usecase  def ++ (xs: Traversable[(A, B)]): Map[A, B]
+   *    @inheritdoc
    */
   def ++[B1 >: B](xs: GenTraversableOnce[(A, B1)]): Map[A, B1] =
     ((repr: Map[A, B1]) /: xs.seq) (_ + _)
diff --git a/src/library/scala/collection/SeqLike.scala b/src/library/scala/collection/SeqLike.scala
index 526ea7e240..fd1d42d7e9 100644
--- a/src/library/scala/collection/SeqLike.scala
+++ b/src/library/scala/collection/SeqLike.scala
@@ -410,13 +410,6 @@ trait SeqLike[+A, +Repr] extends Any with IterableLike[A, Repr] with GenSeqLike[
 
   /** 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`.
-   *  $willNotTerminateInf
-   *
-   *  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-part of `diff` and `intersect` which also work on multi-sets.
-   *
-   *  $willNotTerminateInf
    *
    *  @param that   the sequence to add.
    *  @tparam B     the element type of the returned $coll.
@@ -425,14 +418,21 @@ trait SeqLike[+A, +Repr] extends Any with IterableLike[A, Repr] with GenSeqLike[
    *  @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`.
+   *    @inheritdoc
+   *
+   *    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-part of `diff` and `intersect` which also work on multi-sets.
+   *
+   *    $willNotTerminateInf
+   *
+   *    @return       a new $coll which contains all elements of this $coll
+   *                  followed by all elements of `that`.
    */
   override def union[B >: A, That](that: GenSeq[B])(implicit bf: CanBuildFrom[Repr, B, That]): That =
     this ++ that
 
   /** Computes the multiset difference between this $coll and another sequence.
-   *  $willNotTerminateInf
    *
    *  @param that   the sequence of elements to remove
    *  @tparam B     the element type of the returned $coll.
@@ -444,11 +444,15 @@ trait SeqLike[+A, +Repr] extends Any with IterableLike[A, Repr] with GenSeqLike[
    *                ''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 diff(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.
+   *    @inheritdoc
+   *
+   *    $willNotTerminateInf
+   *
+   *    @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: GenSeq[B]): Repr = {
     val occ = occCounts(that.seq)
@@ -463,7 +467,6 @@ trait SeqLike[+A, +Repr] extends Any with IterableLike[A, Repr] with GenSeqLike[
   def diff[B >: A](that: Seq[B]): Repr = diff(that: GenSeq[B])
 
   /** Computes the multiset intersection between this $coll and another sequence.
-   *  $mayNotTerminateInf
    *
    *  @param that   the sequence of elements to intersect with.
    *  @tparam B     the element type of the returned $coll.
@@ -475,11 +478,15 @@ trait SeqLike[+A, +Repr] extends Any with IterableLike[A, Repr] with GenSeqLike[
    *                ''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 intersect(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.
+   *    @inheritdoc
+   *
+   *    $mayNotTerminateInf
+   *
+   *    @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: GenSeq[B]): Repr = {
     val occ = occCounts(that.seq)
diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index 0da1cfb913..1f5beb5109 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -103,10 +103,6 @@ trait TraversableLike[+A, +Repr] extends Any
 
   /** Applies a function `f` to all elements of this $coll.
    *
-   *    Note: this method underlies the implementation of most other bulk operations.
-   *    It's important to implement this method in an efficient way.
-   *
-   *
    *  @param  f   the function that is applied for its side-effect to every element.
    *              The result of function `f` is discarded.
    *
@@ -115,6 +111,11 @@ trait TraversableLike[+A, +Repr] extends Any
    *              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
 
@@ -165,17 +166,6 @@ trait TraversableLike[+A, +Repr] extends Any
    *  the resulting collection rather than the left one.
    *  Mnemonic: the COLon is on the side of the new COLlection type.
    *
-   *  Example:
-   *  {{{
-   *     scala> val x = List(1)
-   *     x: List[Int] = List(1)
-   *
-   *     scala> val y = LinkedList(2)
-   *     y: scala.collection.mutable.LinkedList[Int] = LinkedList(2)
-   *
-   *     scala> val z = x ++: y
-   *     z: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2)
-   *  }}}
    *  @param that   the traversable to append.
    *  @tparam B     the element type of the returned collection.
    *  @tparam That  $thatinfo
@@ -184,9 +174,22 @@ trait TraversableLike[+A, +Repr] extends Any
    *                of this $coll followed by all elements of `that`.
    *
    *  @usecase def ++:[B](that: TraversableOnce[B]): $Coll[B]
-   *
-   *  @return       a new $coll which contains all elements of this $coll
-   *                followed by all elements of `that`.
+   *    @inheritdoc
+   * 
+   *    Example:
+   *    {{{
+   *      scala> val x = List(1)
+   *      x: List[Int] = List(1)
+   *
+   *      scala> val y = LinkedList(2)
+   *      y: scala.collection.mutable.LinkedList[Int] = LinkedList(2)
+   *
+   *      scala> val z = x ++: y
+   *      z: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2)
+   *    }}}
+   *
+   *    @return       a new $coll which contains all elements of this $coll
+   *                  followed by all elements of `that`.
    */
   def ++:[B >: A, That](that: TraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = {
     val b = bf(repr)
@@ -284,11 +287,12 @@ trait TraversableLike[+A, +Repr] extends Any
    *                The order of the elements is preserved.
    *
    *  @usecase def filterMap[B](f: A => Option[B]): $Coll[B]
+   *    @inheritdoc
    *
-   *  @param pf     the partial function which filters and maps the $coll.
-   *  @return       a new $coll resulting from applying the given option-valued function
-   *                `f` to each element and collecting all defined results.
-   *                The order of the elements is preserved.
+   *    @param pf     the partial function which filters and maps the $coll.
+   *    @return       a new $coll resulting from applying the given option-valued function
+   *                  `f` to each element and collecting all defined results.
+   *                  The order of the elements is preserved.
   def filterMap[B, That](f: A => Option[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = {
     val b = bf(repr)
     for (x <- this)
@@ -588,8 +592,6 @@ trait TraversableLike[+A, +Repr] extends Any
    *  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.
    *
-   *  $willNotTerminateInf
-   *
    *  @param  xs     the array to fill.
    *  @param  start  the starting index.
    *  @param  len    the maximal number of elements to copy.
@@ -597,6 +599,9 @@ trait TraversableLike[+A, +Repr] extends Any
    *
    *
    *  @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
@@ -694,10 +699,11 @@ trait TraversableLike[+A, +Repr] extends Any
      *                that satisfies predicate `p` and collecting the results.
      *
      *  @usecase def map[B](f: A => B): $Coll[B]
+     *    @inheritdoc
      *
-     *  @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.
+     *    @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.
      */
     def map[B, That](f: A => B)(implicit bf: CanBuildFrom[Repr, B, That]): That = {
       val b = bf(repr)
@@ -710,9 +716,6 @@ trait TraversableLike[+A, +Repr] extends Any
      *  outer $coll containing this `WithFilter` instance that satisfy
      *  predicate `p` and concatenating the results.
      *
-     *  The type of the resulting collection will be guided by the static type
-     *  of the outer $coll.
-     *
      *  @param f      the function to apply to each element.
      *  @tparam B     the element type of the returned collection.
      *  @tparam That  $thatinfo
@@ -723,11 +726,15 @@ trait TraversableLike[+A, +Repr] extends Any
      *                concatenating the results.
      *
      *  @usecase def flatMap[B](f: A => TraversableOnce[B]): $Coll[B]
+     *    @inheritdoc
+     *
+     *    The type of the resulting collection will be guided by the static type
+     *    of the outer $coll.
      *
-     *  @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.
+     *    @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.
      */
     def flatMap[B, That](f: A => GenTraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That = {
       val b = bf(repr)
@@ -747,6 +754,7 @@ trait TraversableLike[+A, +Repr] extends Any
      *              but this is not necessary.
      *
      *  @usecase def foreach(f: A => Unit): Unit
+     *    @inheritdoc
      */
     def foreach[U](f: A => U): Unit =
       for (x <- self)
diff --git a/src/library/scala/collection/generic/GenericTraversableTemplate.scala b/src/library/scala/collection/generic/GenericTraversableTemplate.scala
index 7333074778..6586434924 100644
--- a/src/library/scala/collection/generic/GenericTraversableTemplate.scala
+++ b/src/library/scala/collection/generic/GenericTraversableTemplate.scala
@@ -119,22 +119,25 @@ trait GenericTraversableTemplate[+A, +CC[X] <: GenTraversable[X]] extends HasNew
    *  a $coll formed by the elements of these traversable
    *  collections.
    *
-   *  The resulting collection's type will be guided by the
-   *  static type of $coll. For example:
-   *
-   *  {{{
-   *  val xs = List(Set(1, 2, 3), Set(1, 2, 3))
-   *  // xs == List(1, 2, 3, 1, 2, 3)
-   *
-   *  val ys = Set(List(1, 2, 3), List(3, 2, 1))
-   *  // ys == Set(1, 2, 3)
-   *  }}}
-   *
    *  @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 `GenTraversable`.
    *  @return a new $coll resulting from concatenating all element ${coll}s.
+   *
    *  @usecase def flatten[B]: $Coll[B]
+   *
+   *    @inheritdoc
+   *  
+   *    The resulting collection's type will be guided by the
+   *    static type of $coll. For example:
+   *
+   *    {{{
+   *    val xs = List(Set(1, 2, 3), Set(1, 2, 3))
+   *    // xs == List(1, 2, 3, 1, 2, 3)
+   *
+   *    val ys = Set(List(1, 2, 3), List(3, 2, 1))
+   *    // ys == Set(1, 2, 3)
+   *    }}} 
    */
   def flatten[B](implicit asTraversable: A => /*<:<!!!*/ GenTraversableOnce[B]): CC[B] = {
     val b = genericBuilder[B]
diff --git a/src/library/scala/collection/immutable/List.scala b/src/library/scala/collection/immutable/List.scala
index 381fcf3117..870c179b2d 100644
--- a/src/library/scala/collection/immutable/List.scala
+++ b/src/library/scala/collection/immutable/List.scala
@@ -93,8 +93,12 @@ sealed abstract class List[+A] extends AbstractSeq[A]
    *  @param x the element to prepend.
    *  @return  a list which contains `x` as first element and
    *           which continues with this list.
-   *  @example `1 :: List(2, 3) = List(2, 3).::(1) = List(1, 2, 3)`
+   *
    *  @usecase def ::(x: A): List[A]
+   *    @inheritdoc
+   *    
+   *    Example:
+   *    {{{1 :: List(2, 3) = List(2, 3).::(1) = List(1, 2, 3)}}}
    */
   def ::[B >: A] (x: B): List[B] =
     new scala.collection.immutable.::(x, this)
@@ -103,8 +107,12 @@ sealed abstract class List[+A] extends AbstractSeq[A]
    *  @param prefix  The list elements to prepend.
    *  @return a list resulting from the concatenation of the given
    *    list `prefix` and this list.
-   *  @example `List(1, 2) ::: List(3, 4) = List(3, 4).:::(List(1, 2)) = List(1, 2, 3, 4)`
+   *
    *  @usecase def :::(prefix: List[A]): List[A]
+   *    @inheritdoc
+   *
+   *    Example:
+   *    {{{List(1, 2) ::: List(3, 4) = List(3, 4).:::(List(1, 2)) = List(1, 2, 3, 4)}}}
    */
   def :::[B >: A](prefix: List[B]): List[B] =
     if (isEmpty) prefix
@@ -117,7 +125,9 @@ sealed abstract class List[+A] extends AbstractSeq[A]
    *
    *  @param prefix the prefix to reverse and then prepend
    *  @return       the concatenation of the reversed prefix and the current list.
+   *
    *  @usecase def reverse_:::(prefix: List[A]): List[A]
+   *    @inheritdoc
    */
   def reverse_:::[B >: A](prefix: List[B]): List[B] = {
     var these: List[B] = this
@@ -137,7 +147,9 @@ sealed abstract class List[+A] extends AbstractSeq[A]
    *  @tparam B     the element type of the returned collection.
    *  @return       a list resulting from applying the given function
    *                `f` to each element of this list and collecting the results.
+   *
    *  @usecase def mapConserve(f: A => A): List[A]
+   *    @inheritdoc
    */
   def mapConserve[B >: A <: AnyRef](f: A => B): List[B] = {
     @tailrec
diff --git a/src/library/scala/collection/parallel/ParIterableLike.scala b/src/library/scala/collection/parallel/ParIterableLike.scala
index 7e0fa366ab..5551c04ce2 100644
--- a/src/library/scala/collection/parallel/ParIterableLike.scala
+++ b/src/library/scala/collection/parallel/ParIterableLike.scala
@@ -668,8 +668,9 @@ self: ParIterableLike[T, Repr, Sequential] =>
    *  @return           a collection containing the prefix scan of the elements in the original collection
    *
    *  @usecase def scan(z: T)(op: (T, T) => T): $Coll[T]
+   *    @inheritdoc
    *
-   *  @return           a new $coll containing the prefix scan of the elements in this $coll
+   *    @return           a new $coll containing the prefix scan of the elements in this $coll
    */
   def scan[U >: T, That](z: U)(op: (U, U) => U)(implicit bf: CanBuildFrom[Repr, U, That]): That = if (bf(repr).isCombiner) {
     if (tasksupport.parallelismLevel > 1) {
diff --git a/src/library/scala/collection/parallel/ParSeqLike.scala b/src/library/scala/collection/parallel/ParSeqLike.scala
index 9f28a286ca..b3c527da84 100644
--- a/src/library/scala/collection/parallel/ParSeqLike.scala
+++ b/src/library/scala/collection/parallel/ParSeqLike.scala
@@ -285,7 +285,6 @@ self =>
   }
 
   /** Computes the multiset intersection between this $coll and another sequence.
-   *  $mayNotTerminateInf
    *
    *  @param that   the sequence of elements to intersect with.
    *  @tparam B     the element type of the returned $coll.
@@ -296,12 +295,17 @@ self =>
    *                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 intersect(that: Seq[T]): $Coll[T]
-   *  @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.
+   *    @inheritdoc
+   *
+   *    $mayNotTerminateInf
+   *
+   *    @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[U >: T](that: GenSeq[U]) = sequentially {
     _ intersect that