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_.