SI-7660: Document behaviour of Set#++ for duplicate elements

Updated documentation of + and ++ in SetLike to explicitly state that duplicate elements
are not added to the set.

1 files changed, 21 insertions, 7 deletions

diff --git a/src/library/scala/collection/SetLike.scala b/src/library/scala/collection/SetLike.scala
index 3e549f72cd..c98ab6ecb1 100644
--- a/src/library/scala/collection/SetLike.scala
+++ b/src/library/scala/collection/SetLike.scala
@@ -107,22 +107,36 @@ self =>
    */
   def + (elem: A): This
 
-  /** Creates a new $coll with additional elements.
+  /** Creates a new $coll with additional elements, omitting duplicates.
    *
-   *  This method takes two or more elements to be added. Another overloaded
-   *  variant of this method handles the case where a single element is added.
+   *  This method takes two or more elements to be added. Elements that already exist in the $coll will
+   *  not be added. Another overloaded variant of this method handles the case where a single element is added.
+   *
+   *  Example:
+   *   {{{
+   *    scala> val a = Set(1, 3) + 2 + 3
+   *    a: scala.collection.immutable.Set[Int] = Set(1, 3, 2)
+   *   }}}
    *
    *  @param elem1 the first element to add.
    *  @param elem2 the second element to add.
    *  @param elems the remaining elements to add.
-   *  @return   a new $coll with the given elements added.
+   *  @return   a new $coll with the given elements added, omitting duplicates.
    */
   def + (elem1: A, elem2: A, elems: A*): This = this + elem1 + elem2 ++ elems
 
-  /** Creates a new $coll by adding all elements contained in another collection to this $coll.
+  /** Creates a new $coll by adding all elements contained in another collection to this $coll, omitting duplicates.
+   *
+   * This method takes a collection of elements and adds all elements, omitting duplicates, into $coll.
+   *
+   * Example:
+   *  {{{
+   *    scala> val a = Set(1, 2) ++ Set(2, "a")
+   *    a: scala.collection.immutable.Set[Any] = Set(1, 2, a)
+   *  }}}
    *
-   *  @param elems     the collection containing the added elements.
-   *  @return a new $coll with the given elements added.
+   *  @param elems     the collection containing the elements to add.
+   *  @return a new $coll with the given elements added, omitting duplicates.
    */
   def ++ (elems: GenTraversableOnce[A]): This = (repr /: elems.seq)(_ + _)