Adds comments for #3471, and a test case which ...

Adds comments for #3471, and a test case which should have been added
earlier. Review by extempore.

2 files changed, 33 insertions, 11 deletions

diff --git a/src/library/scala/collection/mutable/BufferLike.scala b/src/library/scala/collection/mutable/BufferLike.scala
index a12ac1a1e6..80a8824a3b 100644
--- a/src/library/scala/collection/mutable/BufferLike.scala
+++ b/src/library/scala/collection/mutable/BufferLike.scala
@@ -53,6 +53,10 @@ import annotation.migration
  *  @define Add  Append
  *  @define willNotTerminateInf
  *  @define mayNotTerminateInf
+ *  @define compatMutate
+ *  Note that for backward compatibility reasons, this method
+ *  mutates the collection in place, unlike similar but
+ *  undeprecated methods throughout the collections hierarchy.
  */
 @cloneable
 trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
@@ -232,17 +236,36 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
     }
   }
 
+
+  /** This method prepends elements to the buffer and
+   *  returns the same buffer.
+   *
+   *  $compatMutate
+   *  You are strongly recommended to use `++=:` instead.
+   *
+   *  @param xs   elements to prepend
+   *  @return     this buffer
+   */
   @deprecated("use ++=: instead")
-  final def ++:(iter: Traversable[A]): This = ++=:(iter)
+  final def ++:(xs: Traversable[A]): This = ++=:(xs)
 
+  /** This method prepends elements to the buffer and
+   *  returns the same buffer.
+   *
+   *  $compatMutate
+   *  You are strongly recommended to use `+=:` instead.
+   *
+   *  @param xs   elements to prepend
+   *  @return     this buffer
+   */
   @deprecated("use `+=:' instead")
   final def +:(elem: A): This = +=:(elem)
 
   /** Adds a single element to this collection and returns
-   *  the collection itself.  Note that for backward compatibility
-   *  reasons, this method mutates the collection in place, unlike
-   *  similar but undeprecated methods throughout the collections
-   *  hierarchy.  You are strongly recommended to use '+=' instead.
+   *  the collection itself.
+   *
+   *  $compatMutate
+   *  You are strongly recommended to use '+=' instead.
    *
    *  @param elem  the element to add.
    */
@@ -251,11 +274,10 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
   def + (elem: A): This = { +=(elem); repr }
 
   /** Adds two or more elements to this collection and returns
-   *  the collection itself.  Note that for backward compatibility
-   *  reasons, this method mutates the collection in place, unlike
-   *  all similar methods throughout the collections hierarchy.
-   *  similar but undeprecated methods throughout the collections
-   *  hierarchy.  You are strongly recommended to use '++=' instead.
+   *  the collection itself.
+   *
+   *  $compatMutate
+   *  You are strongly recommended to use '++=' instead.
    *
    *  @param elem1 the first element to add.
    *  @param elem2 the second element to add.
diff --git a/test/files/run/groupby.scala b/test/files/run/groupby.scala
index 895410e34d..a751e65e80 100644
--- a/test/files/run/groupby.scala
+++ b/test/files/run/groupby.scala
@@ -10,7 +10,7 @@ object Test {
     val v1 = map(0)
     val v2 = map(0)
     // this should hold, of course, assuming also that group by returns a regular
-    // map implementation, and does nothing fancy - and it should default just a
+    // map implementation, and does nothing fancy - and it should return just a
     // hash map by default.
     assert(v1 eq v2)
   }