Fixes #3385. No review.

3 files changed, 74 insertions, 37 deletions

diff --git a/src/library/scala/collection/mutable/BufferLike.scala b/src/library/scala/collection/mutable/BufferLike.scala
index 9cbc6c0f05..a12ac1a1e6 100644
--- a/src/library/scala/collection/mutable/BufferLike.scala
+++ b/src/library/scala/collection/mutable/BufferLike.scala
@@ -268,10 +268,11 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
     repr
   }
 
-  /** Adds a number of elements provided by a traversable object and returns
-   *  either the collection itself.
+  /** Creates a new collection containing both the elements of this collection and the provided
+   *  traversable object.
    *
    *  @param xs     the traversable object.
+   *  @return       a new collection consisting of all the elements of this collection and `xs`.
    */
   @migration(2, 8,
     "As of 2.8, ++ always creates a new collection, even on Buffers.\n"+
@@ -279,10 +280,10 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
   )
   def ++(xs: TraversableOnce[A]): This = clone() ++= xs
 
-  /** Removes a single element from this collection and returns
-   *  the collection itself.
+  /** Creates a new collection with all the elements of this collection except `elem`.
    *
    *  @param elem  the element to remove.
+   *  @return      a new collection consisting of all the elements of this collection except `elem`.
    */
   @migration(2, 8,
     "As of 2.8, - always creates a new collection, even on Buffers.\n"+
@@ -290,12 +291,14 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
   )
   override def -(elem: A): This = clone() -= elem
 
-  /** Removes two or more elements from this collection and returns
-   *  the collection itself.
+  /** Creates a new collection with all the elements of this collection except the two
+   *  or more specified elements.
    *
    *  @param elem1 the first element to remove.
    *  @param elem2 the second element to remove.
    *  @param elems the remaining elements to remove.
+   *  @return      a new collection consisting of all the elements of this collection except
+   *               `elem1`, `elem2` and those in `elems`.
    */
   @migration(2, 8,
     "As of 2.8, - always creates a new collection, even on Buffers.\n"+
@@ -303,10 +306,12 @@ trait BufferLike[A, +This <: BufferLike[A, This] with Buffer[A]]
   )
   override def -(elem1: A, elem2: A, elems: A*): This = clone() -= elem1 -= elem2 --= elems
 
-  /** Removes a number of elements provided by a Traversable object and returns
-   *  the collection itself.
+  /** Creates a new collection with all the elements of this collection except those
+   *  provided by the specified traversable object.
    *
-   *  @param iter     the Traversable object.
+   *  @param xs       the traversable object.
+   *  @return         a new collection with all the elements of this collection except
+   *                  those in `xs`
    */
   @migration(2, 8,
     "As of 2.8, -- always creates a new collection, even on Buffers.\n"+
diff --git a/src/library/scala/collection/mutable/MapLike.scala b/src/library/scala/collection/mutable/MapLike.scala
index 4c05cdd5c6..11677aca43 100644
--- a/src/library/scala/collection/mutable/MapLike.scala
+++ b/src/library/scala/collection/mutable/MapLike.scala
@@ -79,9 +79,13 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
    */
   override def updated[B1 >: B](key: A, value: B1): Map[A, B1] = this + ((key, value))
 
-  /** Add a new key/value mapping and return the map itself.
+  /** Creates a new map containing a new key/value mapping and all the key/value mappings
+   *  of this map.
+   *
+   *  Mapping `kv` will override existing mappings from this map with the same key.
    *
    *  @param kv    the key/value mapping to be added
+   *  @return      a new map containing mappings of this map and the mapping `kv`.
    */
   @migration(2, 8,
     "As of 2.8, this operation creates a new map.  To add an element as a\n"+
@@ -89,12 +93,15 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
   )
   def + [B1 >: B] (kv: (A, B1)): Map[A, B1] = clone().asInstanceOf[Map[A, B1]] += kv
 
-  /** Adds two or more key/value mappings and return the map itself.
-   *  with the added elements.
+  /** Creates a new map containing two or more key/value mappings and all the key/value
+   *  mappings of this map.
+   *
+   *  Specified mappings will override existing mappings from this map with the same keys.
    *
    *  @param elem1 the first element to add.
    *  @param elem2 the second element to add.
    *  @param elems the remaining elements to add.
+   *  @return      a new map containing mappings of this map and two or more specified mappings.
    */
   @migration(2, 8,
     "As of 2.8, this operation creates a new map.  To add an element as a\n"+
@@ -103,12 +110,13 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
   override def + [B1 >: B] (elem1: (A, B1), elem2: (A, B1), elems: (A, B1) *): Map[A, B1] =
     clone().asInstanceOf[Map[A, B1]] += elem1 += elem2 ++= elems
 
-  /** Adds a number of elements provided by a traversable object
-   *  via its `iterator` method and returns
-   *  either the collection itself (if it is mutable), or a new collection
-   *  with the added elements.
+  /** Creates a new map containing the key/value mappings provided by the specified traversable object
+   *  and all the key/value mappings of this map.
    *
-   *  @param iter     the traversable object.
+   *  Note that existing mappings from this map with the same key as those in `xs` will be overriden.
+   *
+   *  @param xs     the traversable object.
+   *  @return       a new map containing mappings of this map and those provided by `xs`.
    */
   @migration(2, 8,
     "As of 2.8, this operation creates a new map.  To add the elements as a\n"+
@@ -135,8 +143,11 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
    */
   def -= (key: A): this.type
 
-  /** Delete a key from this map if it is present and return the map itself.
+  /** Creates a new map with all the key/value mappings of this map except the key/value mapping
+   *  with the specified key.
+   *
    *  @param    key the key to be removed
+   *  @return   a new map with all the mappings of this map except that with a key `key`.
    */
   @migration(2, 8,
     "As of 2.8, this operation creates a new map.  To remove an element as a\n"+
@@ -204,12 +215,14 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
    */
   def result: This = repr
 
-  /** Removes two or more elements from this collection and returns
-   *  the collection itself.
+  /** Creates a new map with all the key/value mappings of this map except mappings with keys
+   *  equal to any of the two or more specified keys.
    *
    *  @param elem1 the first element to remove.
    *  @param elem2 the second element to remove.
    *  @param elems the remaining elements to remove.
+   *  @return      a new map containing all the mappings of this map except mappings
+   *               with a key equal to `elem1`, `elem2` or any of `elems`.
    */
   @migration(2, 8,
     "As of 2.8, this operation creates a new map.  To remove an element as a\n"+
@@ -218,10 +231,12 @@ trait MapLike[A, B, +This <: MapLike[A, B, This] with Map[A, B]]
   override def -(elem1: A, elem2: A, elems: A*): This =
     clone() -= elem1 -= elem2 --= elems
 
-  /** Removes a number of elements provided by a Traversable object and returns
-   *  the collection itself.
+  /** Creates a new map with all the key/value mappings of this map except mappings with keys
+   *  equal to any of those provided by the specified traversable object.
    *
-   *  @param iter     the Traversable object.
+   *  @param xs       the traversable object.
+   *  @return         a new map with all the key/value mappings of this map except mappings
+   *                  with a key equal to a key from `xs`.
    */
   @migration(2, 8,
     "As of 2.8, this operation creates a new map.  To remove the elements as a\n"+
diff --git a/src/library/scala/collection/mutable/SetLike.scala b/src/library/scala/collection/mutable/SetLike.scala
index 6f91997b83..78e82eb06b 100644
--- a/src/library/scala/collection/mutable/SetLike.scala
+++ b/src/library/scala/collection/mutable/SetLike.scala
@@ -46,6 +46,10 @@ import scala.annotation.migration
  *    }}}
  *    It is also good idea to override methods `foreach` and
  *    `size` for efficiency.
+ *  @define addDuplicates
+ *    Note that duplicates (elements for which `equals` yields true) will be
+ *    removed, but it is not specified whether it will be an element of this
+ *    set or a newly added element.
  *  @define coll mutable set
  *  @define Coll mutable.Set
  */
@@ -131,10 +135,12 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
    */
   def result: This = repr
 
-  /** Adds a single element to this collection and returns
-   *  the collection itself.
+  /** Creates a new set consisting of all the elements of this set and `elem`.
+   *
+   *  $addDuplicates
    *
    *  @param elem  the element to add.
+   *  @return      a new set consisting of elements of this set and `elem`.
    */
   @migration(2, 8,
     "As of 2.8, this operation creates a new set.  To add an element as a\n"+
@@ -142,12 +148,16 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
   )
   override def + (elem: A): This = clone() += elem
 
-  /** Adds two or more elements to this collection and returns
-   *  the collection itself.
+  /** Creates a new set consisting of all the elements of this set and two or more
+   *  specified elements.
+   *
+   *  $addDuplicates
    *
    *  @param elem1 the first element to add.
    *  @param elem2 the second element to add.
    *  @param elems the remaining elements to add.
+   *  @return      a new set consisting of all the elements of this set, `elem1`,
+   *               `elem2` and those in `elems`.
    */
   @migration(2, 8,
     "As of 2.8, this operation creates a new set.  To add the elements as a\n"+
@@ -156,10 +166,13 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
   override def + (elem1: A, elem2: A, elems: A*): This =
     clone() += elem1 += elem2 ++= elems
 
-  /** Adds a number of elements provided by a traversable object and returns
-   *  either the collection itself.
+  /** Creates a new set consisting of all the elements of this set and those
+   *  provided by the specified traversable object.
+   *
+   *  $addDuplicates
    *
-   *  @param iter     the iterable object.
+   *  @param xs        the traversable object.
+   *  @return          a new set cconsisting of elements of this set and those in `xs`.
    */
   @migration(2, 8,
     "As of 2.8, this operation creates a new set.  To add the elements as a\n"+
@@ -167,10 +180,10 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
   )
   override def ++(xs: TraversableOnce[A]): This = clone() ++= xs
 
-  /** Removes a single element from this collection and returns
-   *  the collection itself.
+  /** Creates a new set consisting of all the elements of this set except `elem`.
    *
    *  @param elem  the element to remove.
+   *  @return      a new set consisting of all the elements of this set except `elem`.
    */
   @migration(2, 8,
     "As of 2.8, this operation creates a new set.  To remove the element as a\n"+
@@ -178,12 +191,14 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
   )
   override def -(elem: A): This = clone() -= elem
 
-  /** Removes two or more elements from this collection and returns
-   *  the collection itself.
+  /** Creates a new set consisting of all the elements of this set except the two
+   *  or more specified elements.
    *
    *  @param elem1 the first element to remove.
    *  @param elem2 the second element to remove.
    *  @param elems the remaining elements to remove.
+   *  @return      a new set consisting of all the elements of this set except
+   *               `elem1`, `elem2` and `elems`.
    */
   @migration(2, 8,
     "As of 2.8, this operation creates a new set.  To remove the elements as a\n"+
@@ -192,10 +207,12 @@ trait SetLike[A, +This <: SetLike[A, This] with Set[A]]
   override def -(elem1: A, elem2: A, elems: A*): This =
     clone() -= elem1 -= elem2 --= elems
 
-  /** Removes a number of elements provided by a Traversable object and returns
-   *  the collection itself.
+  /** Creates a new set consisting of all the elements of this set except those
+   *  provided by the specified traversable object.
    *
-   *  @param iter     the Traversable object.
+   *  @param xs       the traversable object.
+   *  @return         a new set consisting of all the elements of this set except
+   *                  elements from `xs`.
    */
   @migration(2, 8,
     "As of 2.8, this operation creates a new set.  To remove the elements as a\n"+