Specify which element Iterable.distinctBy(selector) retains #KT-36356

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

@@ -9828,6 +9828,7 @@ public fun CharArray.withIndex(): Iterable<IndexedValue<Char>> {
 /**
  * Returns a list containing only distinct elements from the given array.
  * 
+ * Among equal elements of the given array, only the first one will be present in the resulting list.
  * The elements in the resulting list are in the same order as they were in the source array.
  * 
  * @sample samples.collections.Collections.Transformations.distinctAndDistinctBy
@@ -9928,6 +9929,7 @@ public fun CharArray.distinct(): List<Char> {
  * Returns a list containing only elements from the given array
  * having distinct keys returned by the given [selector] function.
  * 
+ * Among elements of the given array with equal keys, only the first one will be present in the resulting list.
  * The elements in the resulting list are in the same order as they were in the source array.
  * 
  * @sample samples.collections.Collections.Transformations.distinctAndDistinctBy

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

@@ -1442,6 +1442,7 @@ public fun <T> Iterable<T>.withIndex(): Iterable<IndexedValue<T>> {
 /**
  * Returns a list containing only distinct elements from the given collection.
  * 
+ * Among equal elements of the given collection, only the first one will be present in the resulting list.
  * The elements in the resulting list are in the same order as they were in the source collection.
  * 
  * @sample samples.collections.Collections.Transformations.distinctAndDistinctBy
@@ -1454,6 +1455,7 @@ public fun <T> Iterable<T>.distinct(): List<T> {
  * Returns a list containing only elements from the given collection
  * having distinct keys returned by the given [selector] function.
  * 
+ * Among elements of the given collection with equal keys, only the first one will be present in the resulting list.
  * The elements in the resulting list are in the same order as they were in the source collection.
  * 
  * @sample samples.collections.Collections.Transformations.distinctAndDistinctBy

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

@@ -975,6 +975,7 @@ public fun <T> Sequence<T>.withIndex(): Sequence<IndexedValue<T>> {
 /**
  * Returns a sequence containing only distinct elements from the given sequence.
  * 
+ * Among equal elements of the given sequence, only the first one will be present in the resulting sequence.
  * The elements in the resulting sequence are in the same order as they were in the source sequence.
  *
  * The operation is _intermediate_ and _stateful_.
@@ -989,6 +990,7 @@ public fun <T> Sequence<T>.distinct(): Sequence<T> {
  * Returns a sequence containing only elements from the given sequence
  * having distinct keys returned by the given [selector] function.
  * 
+ * Among elements of the given sequence with equal keys, only the first one will be present in the resulting sequence.
  * The elements in the resulting sequence are in the same order as they were in the source sequence.
  *
  * The operation is _intermediate_ and _stateful_.

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

@@ -5,6 +5,10 @@
 
 package templates
 
+import templates.DocExtensions.collection
+import templates.DocExtensions.element
+import templates.DocExtensions.mapResult
+import templates.DocExtensions.pluralize
 import templates.Family.*
 import templates.SequenceClass.*
 
@@ -52,7 +56,8 @@ object SetOps : TemplateGroupBase() {
         doc {
             """
                 Returns a ${f.mapResult} containing only distinct ${f.element.pluralize()} from the given ${f.collection}.
-
+                ${if (f.isPrimitiveSpecialization) "" else "\n" +
+                "Among equal ${f.element.pluralize()} of the given ${f.collection}, only the first one will be present in the resulting ${f.mapResult}."}
                 The ${f.element.pluralize()} in the resulting ${f.mapResult} are in the same order as they were in the source ${f.collection}.
                 """
         }
@@ -74,7 +79,8 @@ object SetOps : TemplateGroupBase() {
             """
                 Returns a ${f.mapResult} containing only ${f.element.pluralize()} from the given ${f.collection}
                 having distinct keys returned by the given [selector] function.
-
+                ${if (f.isPrimitiveSpecialization) "" else "\n" +
+                "Among ${f.element.pluralize()} of the given ${f.collection} with equal keys, only the first one will be present in the resulting ${f.mapResult}."}
                 The ${f.element.pluralize()} in the resulting ${f.mapResult} are in the same order as they were in the source ${f.collection}.
                 """
         }