Document the requirement for 'minus(elements)' to have stable hashCode

#KT-24536

libraries/stdlib/common/src/generated/_Collections.kt

@@ -1921,6 +1921,9 @@ public operator fun <T> Iterable<T>.minus(element: T): List<T> {
 
 /**
  * Returns a list containing all elements of the original collection except the elements contained in the given [elements] array.
+ * 
+ * The [elements] array may be converted to a [HashSet] to speed up the operation, thus the elements are required to have
+ * a correct and stable implementation of `hashCode()` that doesn't change between successive invocations.
  */
 public operator fun <T> Iterable<T>.minus(elements: Array<out T>): List<T> {
     if (elements.isEmpty()) return this.toList()
@@ -1930,6 +1933,9 @@ public operator fun <T> Iterable<T>.minus(elements: Array<out T>): List<T> {
 
 /**
  * Returns a list containing all elements of the original collection except the elements contained in the given [elements] collection.
+ * 
+ * The [elements] collection may be converted to a [HashSet] to speed up the operation, thus the elements are required to have
+ * a correct and stable implementation of `hashCode()` that doesn't change between successive invocations.
  */
 public operator fun <T> Iterable<T>.minus(elements: Iterable<T>): List<T> {
     val other = elements.convertToSetForSetOperationWith(this)
@@ -1940,6 +1946,9 @@ public operator fun <T> Iterable<T>.minus(elements: Iterable<T>): List<T> {
 
 /**
  * Returns a list containing all elements of the original collection except the elements contained in the given [elements] sequence.
+ * 
+ * The [elements] sequence may be converted to a [HashSet] to speed up the operation, thus the elements are required to have
+ * a correct and stable implementation of `hashCode()` that doesn't change between successive invocations.
  */
 public operator fun <T> Iterable<T>.minus(elements: Sequence<T>): List<T> {
     val other = elements.toHashSet()

libraries/stdlib/common/src/generated/_Sequences.kt

@@ -1430,6 +1430,9 @@ public operator fun <T> Sequence<T>.minus(element: T): Sequence<T> {
  * 
  * Note that the source sequence and the array being subtracted are iterated only when an `iterator` is requested from
  * the resulting sequence. Changing any of them between successive calls to `iterator` may affect the result.
+ * 
+ * The [elements] array may be converted to a [HashSet] to speed up the operation, thus the elements are required to have
+ * a correct and stable implementation of `hashCode()` that doesn't change between successive invocations.
  *
  * The operation is _intermediate_ and _stateful_.
  */
@@ -1448,6 +1451,9 @@ public operator fun <T> Sequence<T>.minus(elements: Array<out T>): Sequence<T> {
  * 
  * Note that the source sequence and the collection being subtracted are iterated only when an `iterator` is requested from
  * the resulting sequence. Changing any of them between successive calls to `iterator` may affect the result.
+ * 
+ * The [elements] collection may be converted to a [HashSet] to speed up the operation, thus the elements are required to have
+ * a correct and stable implementation of `hashCode()` that doesn't change between successive invocations.
  *
  * The operation is _intermediate_ and _stateful_.
  */
@@ -1470,6 +1476,9 @@ public operator fun <T> Sequence<T>.minus(elements: Iterable<T>): Sequence<T> {
  * the resulting sequence. Changing any of them between successive calls to `iterator` may affect the result.
  * 
  * The operation is _intermediate_ for this sequence and _terminal_ and _stateful_ for the [elements] sequence.
+ * 
+ * The [elements] sequence may be converted to a [HashSet] to speed up the operation, thus the elements are required to have
+ * a correct and stable implementation of `hashCode()` that doesn't change between successive invocations.
  */
 public operator fun <T> Sequence<T>.minus(elements: Sequence<T>): Sequence<T> {
     return object: Sequence<T> {

libraries/stdlib/common/src/generated/_Sets.kt

@@ -30,6 +30,9 @@ public operator fun <T> Set<T>.minus(element: T): Set<T> {
  * Returns a set containing all elements of the original set except the elements contained in the given [elements] array.
  * 
  * The returned set preserves the element iteration order of the original set.
+ * 
+ * The [elements] array may be converted to a [HashSet] to speed up the operation, thus the elements are required to have
+ * a correct and stable implementation of `hashCode()` that doesn't change between successive invocations.
  */
 public operator fun <T> Set<T>.minus(elements: Array<out T>): Set<T> {
     val result = LinkedHashSet<T>(this)
@@ -41,6 +44,9 @@ public operator fun <T> Set<T>.minus(elements: Array<out T>): Set<T> {
  * Returns a set containing all elements of the original set except the elements contained in the given [elements] collection.
  * 
  * The returned set preserves the element iteration order of the original set.
+ * 
+ * The [elements] collection may be converted to a [HashSet] to speed up the operation, thus the elements are required to have
+ * a correct and stable implementation of `hashCode()` that doesn't change between successive invocations.
  */
 public operator fun <T> Set<T>.minus(elements: Iterable<T>): Set<T> {
     val other = elements.convertToSetForSetOperationWith(this)
@@ -57,6 +63,9 @@ public operator fun <T> Set<T>.minus(elements: Iterable<T>): Set<T> {
  * Returns a set containing all elements of the original set except the elements contained in the given [elements] sequence.
  * 
  * The returned set preserves the element iteration order of the original set.
+ * 
+ * The [elements] sequence may be converted to a [HashSet] to speed up the operation, thus the elements are required to have
+ * a correct and stable implementation of `hashCode()` that doesn't change between successive invocations.
  */
 public operator fun <T> Set<T>.minus(elements: Sequence<T>): Set<T> {
     val result = LinkedHashSet<T>(this)

libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt

@@ -358,13 +358,18 @@ object Generators : TemplateGroupBase() {
         }
     }
 
+    private fun elementsConversionClause(elements: Family) =
+            """
+            The [elements] ${elements.doc.collection} may be converted to a [HashSet] to speed up the operation, thus the elements are required to have
+            a correct and stable implementation of `hashCode()` that doesn't change between successive invocations.
+            """
 
     val f_minus_iterable = fn("minus(elements: Iterable<T>)") {
         include(Iterables, Sets, Sequences)
     } builder {
         operator(true)
 
-        doc { "Returns a list containing all elements of the original collection except the elements contained in the given [elements] collection." }
+        doc { "Returns a list containing all elements of the original collection except the elements contained in the given [elements] collection.\n" }
         returns("List<T>")
         specialFor(Sets, Sequences) { returns("SELF") }
         body {
@@ -425,6 +430,9 @@ object Generators : TemplateGroupBase() {
             }
 
         }
+        doc {
+            doc + elementsConversionClause(Iterables)
+        }
     }
 
     val f_minus_array = fn("minus(elements: Array<out T>)") {
@@ -432,7 +440,7 @@ object Generators : TemplateGroupBase() {
     } builder {
         operator(true)
 
-        doc { "Returns a list containing all elements of the original collection except the elements contained in the given [elements] array." }
+        doc { "Returns a list containing all elements of the original collection except the elements contained in the given [elements] array.\n" }
         returns("List<T>")
         specialFor(Sets, Sequences) { returns("SELF") }
         body {
@@ -481,6 +489,9 @@ object Generators : TemplateGroupBase() {
                 """
             }
         }
+        doc {
+            doc + elementsConversionClause(ArraysOfObjects)
+        }
     }
 
     val f_minus_sequence = fn("minus(elements: Sequence<T>)") {
@@ -488,7 +499,7 @@ object Generators : TemplateGroupBase() {
     } builder {
         operator(true)
 
-        doc { "Returns a list containing all elements of the original collection except the elements contained in the given [elements] sequence." }
+        doc { "Returns a list containing all elements of the original collection except the elements contained in the given [elements] sequence.\n" }
         returns("List<T>")
         specialFor(Sets, Sequences) { returns("SELF") }
         body {
@@ -542,6 +553,9 @@ object Generators : TemplateGroupBase() {
                 """
             }
         }
+        doc {
+            doc + elementsConversionClause(Sequences)
+        }
     }
 
     val f_partition = fn("partition(predicate: (T) -> Boolean)") {