Adapted usecases to full signature display

1 files changed, 42 insertions, 34 deletions

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)