Document functions which return set or map preserving the order of elements/entries.

#KT-11632 Fixed

libraries/stdlib/src/generated/_Arrays.kt

@@ -5486,6 +5486,7 @@ public fun Array<out Short>.toShortArray(): ShortArray {
  * Returns a [Map] containing key-value pairs provided by [transform] function
  * applied to elements of the given array.
  * If any of two pairs would have the same key the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <T, K, V> Array<out T>.associate(transform: (T) -> Pair<K, V>): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5497,6 +5498,7 @@ public inline fun <T, K, V> Array<out T>.associate(transform: (T) -> Pair<K, V>)
  * Returns a [Map] containing key-value pairs provided by [transform] function
  * applied to elements of the given array.
  * If any of two pairs would have the same key the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K, V> ByteArray.associate(transform: (Byte) -> Pair<K, V>): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5508,6 +5510,7 @@ public inline fun <K, V> ByteArray.associate(transform: (Byte) -> Pair<K, V>): M
  * Returns a [Map] containing key-value pairs provided by [transform] function
  * applied to elements of the given array.
  * If any of two pairs would have the same key the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K, V> ShortArray.associate(transform: (Short) -> Pair<K, V>): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5519,6 +5522,7 @@ public inline fun <K, V> ShortArray.associate(transform: (Short) -> Pair<K, V>):
  * Returns a [Map] containing key-value pairs provided by [transform] function
  * applied to elements of the given array.
  * If any of two pairs would have the same key the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K, V> IntArray.associate(transform: (Int) -> Pair<K, V>): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5530,6 +5534,7 @@ public inline fun <K, V> IntArray.associate(transform: (Int) -> Pair<K, V>): Map
  * Returns a [Map] containing key-value pairs provided by [transform] function
  * applied to elements of the given array.
  * If any of two pairs would have the same key the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K, V> LongArray.associate(transform: (Long) -> Pair<K, V>): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5541,6 +5546,7 @@ public inline fun <K, V> LongArray.associate(transform: (Long) -> Pair<K, V>): M
  * Returns a [Map] containing key-value pairs provided by [transform] function
  * applied to elements of the given array.
  * If any of two pairs would have the same key the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K, V> FloatArray.associate(transform: (Float) -> Pair<K, V>): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5552,6 +5558,7 @@ public inline fun <K, V> FloatArray.associate(transform: (Float) -> Pair<K, V>):
  * Returns a [Map] containing key-value pairs provided by [transform] function
  * applied to elements of the given array.
  * If any of two pairs would have the same key the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K, V> DoubleArray.associate(transform: (Double) -> Pair<K, V>): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5563,6 +5570,7 @@ public inline fun <K, V> DoubleArray.associate(transform: (Double) -> Pair<K, V>
  * Returns a [Map] containing key-value pairs provided by [transform] function
  * applied to elements of the given array.
  * If any of two pairs would have the same key the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K, V> BooleanArray.associate(transform: (Boolean) -> Pair<K, V>): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5574,6 +5582,7 @@ public inline fun <K, V> BooleanArray.associate(transform: (Boolean) -> Pair<K,
  * Returns a [Map] containing key-value pairs provided by [transform] function
  * applied to elements of the given array.
  * If any of two pairs would have the same key the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K, V> CharArray.associate(transform: (Char) -> Pair<K, V>): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5585,6 +5594,7 @@ public inline fun <K, V> CharArray.associate(transform: (Char) -> Pair<K, V>): M
  * Returns a [Map] containing the elements from the given array indexed by the key
  * returned from [keySelector] function applied to each element.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <T, K> Array<out T>.associateBy(keySelector: (T) -> K): Map<K, T> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5596,6 +5606,7 @@ public inline fun <T, K> Array<out T>.associateBy(keySelector: (T) -> K): Map<K,
  * Returns a [Map] containing the elements from the given array indexed by the key
  * returned from [keySelector] function applied to each element.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K> ByteArray.associateBy(keySelector: (Byte) -> K): Map<K, Byte> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5607,6 +5618,7 @@ public inline fun <K> ByteArray.associateBy(keySelector: (Byte) -> K): Map<K, By
  * Returns a [Map] containing the elements from the given array indexed by the key
  * returned from [keySelector] function applied to each element.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K> ShortArray.associateBy(keySelector: (Short) -> K): Map<K, Short> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5618,6 +5630,7 @@ public inline fun <K> ShortArray.associateBy(keySelector: (Short) -> K): Map<K,
  * Returns a [Map] containing the elements from the given array indexed by the key
  * returned from [keySelector] function applied to each element.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K> IntArray.associateBy(keySelector: (Int) -> K): Map<K, Int> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5629,6 +5642,7 @@ public inline fun <K> IntArray.associateBy(keySelector: (Int) -> K): Map<K, Int>
  * Returns a [Map] containing the elements from the given array indexed by the key
  * returned from [keySelector] function applied to each element.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K> LongArray.associateBy(keySelector: (Long) -> K): Map<K, Long> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5640,6 +5654,7 @@ public inline fun <K> LongArray.associateBy(keySelector: (Long) -> K): Map<K, Lo
  * Returns a [Map] containing the elements from the given array indexed by the key
  * returned from [keySelector] function applied to each element.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K> FloatArray.associateBy(keySelector: (Float) -> K): Map<K, Float> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5651,6 +5666,7 @@ public inline fun <K> FloatArray.associateBy(keySelector: (Float) -> K): Map<K,
  * Returns a [Map] containing the elements from the given array indexed by the key
  * returned from [keySelector] function applied to each element.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K> DoubleArray.associateBy(keySelector: (Double) -> K): Map<K, Double> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5662,6 +5678,7 @@ public inline fun <K> DoubleArray.associateBy(keySelector: (Double) -> K): Map<K
  * Returns a [Map] containing the elements from the given array indexed by the key
  * returned from [keySelector] function applied to each element.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K> BooleanArray.associateBy(keySelector: (Boolean) -> K): Map<K, Boolean> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5673,6 +5690,7 @@ public inline fun <K> BooleanArray.associateBy(keySelector: (Boolean) -> K): Map
  * Returns a [Map] containing the elements from the given array indexed by the key
  * returned from [keySelector] function applied to each element.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K> CharArray.associateBy(keySelector: (Char) -> K): Map<K, Char> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5683,6 +5701,7 @@ public inline fun <K> CharArray.associateBy(keySelector: (Char) -> K): Map<K, Ch
 /**
  * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <T, K, V> Array<out T>.associateBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5693,6 +5712,7 @@ public inline fun <T, K, V> Array<out T>.associateBy(keySelector: (T) -> K, valu
 /**
  * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K, V> ByteArray.associateBy(keySelector: (Byte) -> K, valueTransform: (Byte) -> V): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5703,6 +5723,7 @@ public inline fun <K, V> ByteArray.associateBy(keySelector: (Byte) -> K, valueTr
 /**
  * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K, V> ShortArray.associateBy(keySelector: (Short) -> K, valueTransform: (Short) -> V): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5713,6 +5734,7 @@ public inline fun <K, V> ShortArray.associateBy(keySelector: (Short) -> K, value
 /**
  * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K, V> IntArray.associateBy(keySelector: (Int) -> K, valueTransform: (Int) -> V): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5723,6 +5745,7 @@ public inline fun <K, V> IntArray.associateBy(keySelector: (Int) -> K, valueTran
 /**
  * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K, V> LongArray.associateBy(keySelector: (Long) -> K, valueTransform: (Long) -> V): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5733,6 +5756,7 @@ public inline fun <K, V> LongArray.associateBy(keySelector: (Long) -> K, valueTr
 /**
  * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K, V> FloatArray.associateBy(keySelector: (Float) -> K, valueTransform: (Float) -> V): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5743,6 +5767,7 @@ public inline fun <K, V> FloatArray.associateBy(keySelector: (Float) -> K, value
 /**
  * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K, V> DoubleArray.associateBy(keySelector: (Double) -> K, valueTransform: (Double) -> V): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5753,6 +5778,7 @@ public inline fun <K, V> DoubleArray.associateBy(keySelector: (Double) -> K, val
 /**
  * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K, V> BooleanArray.associateBy(keySelector: (Boolean) -> K, valueTransform: (Boolean) -> V): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -5763,6 +5789,7 @@ public inline fun <K, V> BooleanArray.associateBy(keySelector: (Boolean) -> K, v
 /**
  * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given array.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original array.
  */
 public inline fun <K, V> CharArray.associateBy(keySelector: (Char) -> K, valueTransform: (Char) -> V): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -6445,6 +6472,7 @@ public fun CharArray.toMutableList(): MutableList<Char> {
 
 /**
  * Returns a [Set] of all elements.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun <T> Array<out T>.toSet(): Set<T> {
     return when (size) {
@@ -6456,6 +6484,7 @@ public fun <T> Array<out T>.toSet(): Set<T> {
 
 /**
  * Returns a [Set] of all elements.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun ByteArray.toSet(): Set<Byte> {
     return when (size) {
@@ -6467,6 +6496,7 @@ public fun ByteArray.toSet(): Set<Byte> {
 
 /**
  * Returns a [Set] of all elements.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun ShortArray.toSet(): Set<Short> {
     return when (size) {
@@ -6478,6 +6508,7 @@ public fun ShortArray.toSet(): Set<Short> {
 
 /**
  * Returns a [Set] of all elements.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun IntArray.toSet(): Set<Int> {
     return when (size) {
@@ -6489,6 +6520,7 @@ public fun IntArray.toSet(): Set<Int> {
 
 /**
  * Returns a [Set] of all elements.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun LongArray.toSet(): Set<Long> {
     return when (size) {
@@ -6500,6 +6532,7 @@ public fun LongArray.toSet(): Set<Long> {
 
 /**
  * Returns a [Set] of all elements.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun FloatArray.toSet(): Set<Float> {
     return when (size) {
@@ -6511,6 +6544,7 @@ public fun FloatArray.toSet(): Set<Float> {
 
 /**
  * Returns a [Set] of all elements.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun DoubleArray.toSet(): Set<Double> {
     return when (size) {
@@ -6522,6 +6556,7 @@ public fun DoubleArray.toSet(): Set<Double> {
 
 /**
  * Returns a [Set] of all elements.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun BooleanArray.toSet(): Set<Boolean> {
     return when (size) {
@@ -6533,6 +6568,7 @@ public fun BooleanArray.toSet(): Set<Boolean> {
 
 /**
  * Returns a [Set] of all elements.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun CharArray.toSet(): Set<Char> {
     return when (size) {
@@ -6788,6 +6824,7 @@ public inline fun <R, C : MutableCollection<in R>> CharArray.flatMapTo(destinati
 /**
  * Groups elements of the original array by the key returned by the given [keySelector] function
  * applied to each element and returns a map where each group key is associated with a list of corresponding elements.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupBy
  */
 public inline fun <T, K> Array<out T>.groupBy(keySelector: (T) -> K): Map<K, List<T>> {
@@ -6797,6 +6834,7 @@ public inline fun <T, K> Array<out T>.groupBy(keySelector: (T) -> K): Map<K, Lis
 /**
  * Groups elements of the original array by the key returned by the given [keySelector] function
  * applied to each element and returns a map where each group key is associated with a list of corresponding elements.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupBy
  */
 public inline fun <K> ByteArray.groupBy(keySelector: (Byte) -> K): Map<K, List<Byte>> {
@@ -6806,6 +6844,7 @@ public inline fun <K> ByteArray.groupBy(keySelector: (Byte) -> K): Map<K, List<B
 /**
  * Groups elements of the original array by the key returned by the given [keySelector] function
  * applied to each element and returns a map where each group key is associated with a list of corresponding elements.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupBy
  */
 public inline fun <K> ShortArray.groupBy(keySelector: (Short) -> K): Map<K, List<Short>> {
@@ -6815,6 +6854,7 @@ public inline fun <K> ShortArray.groupBy(keySelector: (Short) -> K): Map<K, List
 /**
  * Groups elements of the original array by the key returned by the given [keySelector] function
  * applied to each element and returns a map where each group key is associated with a list of corresponding elements.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupBy
  */
 public inline fun <K> IntArray.groupBy(keySelector: (Int) -> K): Map<K, List<Int>> {
@@ -6824,6 +6864,7 @@ public inline fun <K> IntArray.groupBy(keySelector: (Int) -> K): Map<K, List<Int
 /**
  * Groups elements of the original array by the key returned by the given [keySelector] function
  * applied to each element and returns a map where each group key is associated with a list of corresponding elements.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupBy
  */
 public inline fun <K> LongArray.groupBy(keySelector: (Long) -> K): Map<K, List<Long>> {
@@ -6833,6 +6874,7 @@ public inline fun <K> LongArray.groupBy(keySelector: (Long) -> K): Map<K, List<L
 /**
  * Groups elements of the original array by the key returned by the given [keySelector] function
  * applied to each element and returns a map where each group key is associated with a list of corresponding elements.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupBy
  */
 public inline fun <K> FloatArray.groupBy(keySelector: (Float) -> K): Map<K, List<Float>> {
@@ -6842,6 +6884,7 @@ public inline fun <K> FloatArray.groupBy(keySelector: (Float) -> K): Map<K, List
 /**
  * Groups elements of the original array by the key returned by the given [keySelector] function
  * applied to each element and returns a map where each group key is associated with a list of corresponding elements.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupBy
  */
 public inline fun <K> DoubleArray.groupBy(keySelector: (Double) -> K): Map<K, List<Double>> {
@@ -6851,6 +6894,7 @@ public inline fun <K> DoubleArray.groupBy(keySelector: (Double) -> K): Map<K, Li
 /**
  * Groups elements of the original array by the key returned by the given [keySelector] function
  * applied to each element and returns a map where each group key is associated with a list of corresponding elements.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupBy
  */
 public inline fun <K> BooleanArray.groupBy(keySelector: (Boolean) -> K): Map<K, List<Boolean>> {
@@ -6860,6 +6904,7 @@ public inline fun <K> BooleanArray.groupBy(keySelector: (Boolean) -> K): Map<K,
 /**
  * Groups elements of the original array by the key returned by the given [keySelector] function
  * applied to each element and returns a map where each group key is associated with a list of corresponding elements.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupBy
  */
 public inline fun <K> CharArray.groupBy(keySelector: (Char) -> K): Map<K, List<Char>> {
@@ -6870,6 +6915,7 @@ public inline fun <K> CharArray.groupBy(keySelector: (Char) -> K): Map<K, List<C
  * Groups values returned by the [valueTransform] function applied to each element of the original array
  * by the key returned by the given [keySelector] function applied to the element
  * and returns a map where each group key is associated with a list of corresponding values.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupByKeysAndValues
  */
 public inline fun <T, K, V> Array<out T>.groupBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map<K, List<V>> {
@@ -6880,6 +6926,7 @@ public inline fun <T, K, V> Array<out T>.groupBy(keySelector: (T) -> K, valueTra
  * Groups values returned by the [valueTransform] function applied to each element of the original array
  * by the key returned by the given [keySelector] function applied to the element
  * and returns a map where each group key is associated with a list of corresponding values.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupByKeysAndValues
  */
 public inline fun <K, V> ByteArray.groupBy(keySelector: (Byte) -> K, valueTransform: (Byte) -> V): Map<K, List<V>> {
@@ -6890,6 +6937,7 @@ public inline fun <K, V> ByteArray.groupBy(keySelector: (Byte) -> K, valueTransf
  * Groups values returned by the [valueTransform] function applied to each element of the original array
  * by the key returned by the given [keySelector] function applied to the element
  * and returns a map where each group key is associated with a list of corresponding values.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupByKeysAndValues
  */
 public inline fun <K, V> ShortArray.groupBy(keySelector: (Short) -> K, valueTransform: (Short) -> V): Map<K, List<V>> {
@@ -6900,6 +6948,7 @@ public inline fun <K, V> ShortArray.groupBy(keySelector: (Short) -> K, valueTran
  * Groups values returned by the [valueTransform] function applied to each element of the original array
  * by the key returned by the given [keySelector] function applied to the element
  * and returns a map where each group key is associated with a list of corresponding values.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupByKeysAndValues
  */
 public inline fun <K, V> IntArray.groupBy(keySelector: (Int) -> K, valueTransform: (Int) -> V): Map<K, List<V>> {
@@ -6910,6 +6959,7 @@ public inline fun <K, V> IntArray.groupBy(keySelector: (Int) -> K, valueTransfor
  * Groups values returned by the [valueTransform] function applied to each element of the original array
  * by the key returned by the given [keySelector] function applied to the element
  * and returns a map where each group key is associated with a list of corresponding values.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupByKeysAndValues
  */
 public inline fun <K, V> LongArray.groupBy(keySelector: (Long) -> K, valueTransform: (Long) -> V): Map<K, List<V>> {
@@ -6920,6 +6970,7 @@ public inline fun <K, V> LongArray.groupBy(keySelector: (Long) -> K, valueTransf
  * Groups values returned by the [valueTransform] function applied to each element of the original array
  * by the key returned by the given [keySelector] function applied to the element
  * and returns a map where each group key is associated with a list of corresponding values.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupByKeysAndValues
  */
 public inline fun <K, V> FloatArray.groupBy(keySelector: (Float) -> K, valueTransform: (Float) -> V): Map<K, List<V>> {
@@ -6930,6 +6981,7 @@ public inline fun <K, V> FloatArray.groupBy(keySelector: (Float) -> K, valueTran
  * Groups values returned by the [valueTransform] function applied to each element of the original array
  * by the key returned by the given [keySelector] function applied to the element
  * and returns a map where each group key is associated with a list of corresponding values.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupByKeysAndValues
  */
 public inline fun <K, V> DoubleArray.groupBy(keySelector: (Double) -> K, valueTransform: (Double) -> V): Map<K, List<V>> {
@@ -6940,6 +6992,7 @@ public inline fun <K, V> DoubleArray.groupBy(keySelector: (Double) -> K, valueTr
  * Groups values returned by the [valueTransform] function applied to each element of the original array
  * by the key returned by the given [keySelector] function applied to the element
  * and returns a map where each group key is associated with a list of corresponding values.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupByKeysAndValues
  */
 public inline fun <K, V> BooleanArray.groupBy(keySelector: (Boolean) -> K, valueTransform: (Boolean) -> V): Map<K, List<V>> {
@@ -6950,6 +7003,7 @@ public inline fun <K, V> BooleanArray.groupBy(keySelector: (Boolean) -> K, value
  * Groups values returned by the [valueTransform] function applied to each element of the original array
  * by the key returned by the given [keySelector] function applied to the element
  * and returns a map where each group key is associated with a list of corresponding values.
+ * The returned map preserves the entry iteration order of the keys produced from the original array.
  * @sample test.collections.CollectionTest.groupByKeysAndValues
  */
 public inline fun <K, V> CharArray.groupBy(keySelector: (Char) -> K, valueTransform: (Char) -> V): Map<K, List<V>> {
@@ -7923,6 +7977,7 @@ public inline fun <K> CharArray.distinctBy(selector: (Char) -> K): List<Char> {
 
 /**
  * Returns a set containing all elements that are contained by both this set and the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun <T> Array<out T>.intersect(other: Iterable<T>): Set<T> {
     val set = this.toMutableSet()
@@ -7932,6 +7987,7 @@ public infix fun <T> Array<out T>.intersect(other: Iterable<T>): Set<T> {
 
 /**
  * Returns a set containing all elements that are contained by both this set and the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun ByteArray.intersect(other: Iterable<Byte>): Set<Byte> {
     val set = this.toMutableSet()
@@ -7941,6 +7997,7 @@ public infix fun ByteArray.intersect(other: Iterable<Byte>): Set<Byte> {
 
 /**
  * Returns a set containing all elements that are contained by both this set and the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun ShortArray.intersect(other: Iterable<Short>): Set<Short> {
     val set = this.toMutableSet()
@@ -7950,6 +8007,7 @@ public infix fun ShortArray.intersect(other: Iterable<Short>): Set<Short> {
 
 /**
  * Returns a set containing all elements that are contained by both this set and the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun IntArray.intersect(other: Iterable<Int>): Set<Int> {
     val set = this.toMutableSet()
@@ -7959,6 +8017,7 @@ public infix fun IntArray.intersect(other: Iterable<Int>): Set<Int> {
 
 /**
  * Returns a set containing all elements that are contained by both this set and the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun LongArray.intersect(other: Iterable<Long>): Set<Long> {
     val set = this.toMutableSet()
@@ -7968,6 +8027,7 @@ public infix fun LongArray.intersect(other: Iterable<Long>): Set<Long> {
 
 /**
  * Returns a set containing all elements that are contained by both this set and the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun FloatArray.intersect(other: Iterable<Float>): Set<Float> {
     val set = this.toMutableSet()
@@ -7977,6 +8037,7 @@ public infix fun FloatArray.intersect(other: Iterable<Float>): Set<Float> {
 
 /**
  * Returns a set containing all elements that are contained by both this set and the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun DoubleArray.intersect(other: Iterable<Double>): Set<Double> {
     val set = this.toMutableSet()
@@ -7986,6 +8047,7 @@ public infix fun DoubleArray.intersect(other: Iterable<Double>): Set<Double> {
 
 /**
  * Returns a set containing all elements that are contained by both this set and the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun BooleanArray.intersect(other: Iterable<Boolean>): Set<Boolean> {
     val set = this.toMutableSet()
@@ -7995,6 +8057,7 @@ public infix fun BooleanArray.intersect(other: Iterable<Boolean>): Set<Boolean>
 
 /**
  * Returns a set containing all elements that are contained by both this set and the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun CharArray.intersect(other: Iterable<Char>): Set<Char> {
     val set = this.toMutableSet()
@@ -8003,7 +8066,8 @@ public infix fun CharArray.intersect(other: Iterable<Char>): Set<Char> {
 }
 
 /**
- * Returns a set containing all elements that are contained by this set and not contained by the specified collection.
+ * Returns a set containing all elements that are contained by this array and not contained by the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun <T> Array<out T>.subtract(other: Iterable<T>): Set<T> {
     val set = this.toMutableSet()
@@ -8012,7 +8076,8 @@ public infix fun <T> Array<out T>.subtract(other: Iterable<T>): Set<T> {
 }
 
 /**
- * Returns a set containing all elements that are contained by this set and not contained by the specified collection.
+ * Returns a set containing all elements that are contained by this array and not contained by the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun ByteArray.subtract(other: Iterable<Byte>): Set<Byte> {
     val set = this.toMutableSet()
@@ -8021,7 +8086,8 @@ public infix fun ByteArray.subtract(other: Iterable<Byte>): Set<Byte> {
 }
 
 /**
- * Returns a set containing all elements that are contained by this set and not contained by the specified collection.
+ * Returns a set containing all elements that are contained by this array and not contained by the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun ShortArray.subtract(other: Iterable<Short>): Set<Short> {
     val set = this.toMutableSet()
@@ -8030,7 +8096,8 @@ public infix fun ShortArray.subtract(other: Iterable<Short>): Set<Short> {
 }
 
 /**
- * Returns a set containing all elements that are contained by this set and not contained by the specified collection.
+ * Returns a set containing all elements that are contained by this array and not contained by the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun IntArray.subtract(other: Iterable<Int>): Set<Int> {
     val set = this.toMutableSet()
@@ -8039,7 +8106,8 @@ public infix fun IntArray.subtract(other: Iterable<Int>): Set<Int> {
 }
 
 /**
- * Returns a set containing all elements that are contained by this set and not contained by the specified collection.
+ * Returns a set containing all elements that are contained by this array and not contained by the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun LongArray.subtract(other: Iterable<Long>): Set<Long> {
     val set = this.toMutableSet()
@@ -8048,7 +8116,8 @@ public infix fun LongArray.subtract(other: Iterable<Long>): Set<Long> {
 }
 
 /**
- * Returns a set containing all elements that are contained by this set and not contained by the specified collection.
+ * Returns a set containing all elements that are contained by this array and not contained by the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun FloatArray.subtract(other: Iterable<Float>): Set<Float> {
     val set = this.toMutableSet()
@@ -8057,7 +8126,8 @@ public infix fun FloatArray.subtract(other: Iterable<Float>): Set<Float> {
 }
 
 /**
- * Returns a set containing all elements that are contained by this set and not contained by the specified collection.
+ * Returns a set containing all elements that are contained by this array and not contained by the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun DoubleArray.subtract(other: Iterable<Double>): Set<Double> {
     val set = this.toMutableSet()
@@ -8066,7 +8136,8 @@ public infix fun DoubleArray.subtract(other: Iterable<Double>): Set<Double> {
 }
 
 /**
- * Returns a set containing all elements that are contained by this set and not contained by the specified collection.
+ * Returns a set containing all elements that are contained by this array and not contained by the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun BooleanArray.subtract(other: Iterable<Boolean>): Set<Boolean> {
     val set = this.toMutableSet()
@@ -8075,7 +8146,8 @@ public infix fun BooleanArray.subtract(other: Iterable<Boolean>): Set<Boolean> {
 }
 
 /**
- * Returns a set containing all elements that are contained by this set and not contained by the specified collection.
+ * Returns a set containing all elements that are contained by this array and not contained by the specified collection.
+ * The returned set preserves the element iteration order of the original array.
  */
 public infix fun CharArray.subtract(other: Iterable<Char>): Set<Char> {
     val set = this.toMutableSet()
@@ -8085,6 +8157,7 @@ public infix fun CharArray.subtract(other: Iterable<Char>): Set<Char> {
 
 /**
  * Returns a mutable set containing all distinct elements from the given array.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun <T> Array<out T>.toMutableSet(): MutableSet<T> {
     val set = LinkedHashSet<T>(mapCapacity(size))
@@ -8094,6 +8167,7 @@ public fun <T> Array<out T>.toMutableSet(): MutableSet<T> {
 
 /**
  * Returns a mutable set containing all distinct elements from the given array.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun ByteArray.toMutableSet(): MutableSet<Byte> {
     val set = LinkedHashSet<Byte>(mapCapacity(size))
@@ -8103,6 +8177,7 @@ public fun ByteArray.toMutableSet(): MutableSet<Byte> {
 
 /**
  * Returns a mutable set containing all distinct elements from the given array.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun ShortArray.toMutableSet(): MutableSet<Short> {
     val set = LinkedHashSet<Short>(mapCapacity(size))
@@ -8112,6 +8187,7 @@ public fun ShortArray.toMutableSet(): MutableSet<Short> {
 
 /**
  * Returns a mutable set containing all distinct elements from the given array.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun IntArray.toMutableSet(): MutableSet<Int> {
     val set = LinkedHashSet<Int>(mapCapacity(size))
@@ -8121,6 +8197,7 @@ public fun IntArray.toMutableSet(): MutableSet<Int> {
 
 /**
  * Returns a mutable set containing all distinct elements from the given array.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun LongArray.toMutableSet(): MutableSet<Long> {
     val set = LinkedHashSet<Long>(mapCapacity(size))
@@ -8130,6 +8207,7 @@ public fun LongArray.toMutableSet(): MutableSet<Long> {
 
 /**
  * Returns a mutable set containing all distinct elements from the given array.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun FloatArray.toMutableSet(): MutableSet<Float> {
     val set = LinkedHashSet<Float>(mapCapacity(size))
@@ -8139,6 +8217,7 @@ public fun FloatArray.toMutableSet(): MutableSet<Float> {
 
 /**
  * Returns a mutable set containing all distinct elements from the given array.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun DoubleArray.toMutableSet(): MutableSet<Double> {
     val set = LinkedHashSet<Double>(mapCapacity(size))
@@ -8148,6 +8227,7 @@ public fun DoubleArray.toMutableSet(): MutableSet<Double> {
 
 /**
  * Returns a mutable set containing all distinct elements from the given array.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun BooleanArray.toMutableSet(): MutableSet<Boolean> {
     val set = LinkedHashSet<Boolean>(mapCapacity(size))
@@ -8157,6 +8237,7 @@ public fun BooleanArray.toMutableSet(): MutableSet<Boolean> {
 
 /**
  * Returns a mutable set containing all distinct elements from the given array.
+ * The returned set preserves the element iteration order of the original array.
  */
 public fun CharArray.toMutableSet(): MutableSet<Char> {
     val set = LinkedHashSet<Char>(mapCapacity(size))
@@ -8166,6 +8247,9 @@ public fun CharArray.toMutableSet(): MutableSet<Char> {
 
 /**
  * Returns a set containing all distinct elements from both collections.
+ * The returned set preserves the element iteration order of the original array.
+ * Those elements of the [other] collection that are unique are iterated in the end
+ * in the order of the [other] collection.
  */
 public infix fun <T> Array<out T>.union(other: Iterable<T>): Set<T> {
     val set = this.toMutableSet()
@@ -8175,6 +8259,9 @@ public infix fun <T> Array<out T>.union(other: Iterable<T>): Set<T> {
 
 /**
  * Returns a set containing all distinct elements from both collections.
+ * The returned set preserves the element iteration order of the original array.
+ * Those elements of the [other] collection that are unique are iterated in the end
+ * in the order of the [other] collection.
  */
 public infix fun ByteArray.union(other: Iterable<Byte>): Set<Byte> {
     val set = this.toMutableSet()
@@ -8184,6 +8271,9 @@ public infix fun ByteArray.union(other: Iterable<Byte>): Set<Byte> {
 
 /**
  * Returns a set containing all distinct elements from both collections.
+ * The returned set preserves the element iteration order of the original array.
+ * Those elements of the [other] collection that are unique are iterated in the end
+ * in the order of the [other] collection.
  */
 public infix fun ShortArray.union(other: Iterable<Short>): Set<Short> {
     val set = this.toMutableSet()
@@ -8193,6 +8283,9 @@ public infix fun ShortArray.union(other: Iterable<Short>): Set<Short> {
 
 /**
  * Returns a set containing all distinct elements from both collections.
+ * The returned set preserves the element iteration order of the original array.
+ * Those elements of the [other] collection that are unique are iterated in the end
+ * in the order of the [other] collection.
  */
 public infix fun IntArray.union(other: Iterable<Int>): Set<Int> {
     val set = this.toMutableSet()
@@ -8202,6 +8295,9 @@ public infix fun IntArray.union(other: Iterable<Int>): Set<Int> {
 
 /**
  * Returns a set containing all distinct elements from both collections.
+ * The returned set preserves the element iteration order of the original array.
+ * Those elements of the [other] collection that are unique are iterated in the end
+ * in the order of the [other] collection.
  */
 public infix fun LongArray.union(other: Iterable<Long>): Set<Long> {
     val set = this.toMutableSet()
@@ -8211,6 +8307,9 @@ public infix fun LongArray.union(other: Iterable<Long>): Set<Long> {
 
 /**
  * Returns a set containing all distinct elements from both collections.
+ * The returned set preserves the element iteration order of the original array.
+ * Those elements of the [other] collection that are unique are iterated in the end
+ * in the order of the [other] collection.
  */
 public infix fun FloatArray.union(other: Iterable<Float>): Set<Float> {
     val set = this.toMutableSet()
@@ -8220,6 +8319,9 @@ public infix fun FloatArray.union(other: Iterable<Float>): Set<Float> {
 
 /**
  * Returns a set containing all distinct elements from both collections.
+ * The returned set preserves the element iteration order of the original array.
+ * Those elements of the [other] collection that are unique are iterated in the end
+ * in the order of the [other] collection.
  */
 public infix fun DoubleArray.union(other: Iterable<Double>): Set<Double> {
     val set = this.toMutableSet()
@@ -8229,6 +8331,9 @@ public infix fun DoubleArray.union(other: Iterable<Double>): Set<Double> {
 
 /**
  * Returns a set containing all distinct elements from both collections.
+ * The returned set preserves the element iteration order of the original array.
+ * Those elements of the [other] collection that are unique are iterated in the end
+ * in the order of the [other] collection.
  */
 public infix fun BooleanArray.union(other: Iterable<Boolean>): Set<Boolean> {
     val set = this.toMutableSet()
@@ -8238,6 +8343,9 @@ public infix fun BooleanArray.union(other: Iterable<Boolean>): Set<Boolean> {
 
 /**
  * Returns a set containing all distinct elements from both collections.
+ * The returned set preserves the element iteration order of the original array.
+ * Those elements of the [other] collection that are unique are iterated in the end
+ * in the order of the [other] collection.
  */
 public infix fun CharArray.union(other: Iterable<Char>): Set<Char> {
     val set = this.toMutableSet()

libraries/stdlib/src/generated/_Collections.kt

@@ -958,6 +958,7 @@ public fun Collection<Short>.toShortArray(): ShortArray {
  * Returns a [Map] containing key-value pairs provided by [transform] function
  * applied to elements of the given collection.
  * If any of two pairs would have the same key the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original collection.
  */
 public inline fun <T, K, V> Iterable<T>.associate(transform: (T) -> Pair<K, V>): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -969,6 +970,7 @@ public inline fun <T, K, V> Iterable<T>.associate(transform: (T) -> Pair<K, V>):
  * Returns a [Map] containing the elements from the given collection indexed by the key
  * returned from [keySelector] function applied to each element.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original collection.
  */
 public inline fun <T, K> Iterable<T>.associateBy(keySelector: (T) -> K): Map<K, T> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -979,6 +981,7 @@ public inline fun <T, K> Iterable<T>.associateBy(keySelector: (T) -> K): Map<K,
 /**
  * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given collection.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original collection.
  */
 public inline fun <T, K, V> Iterable<T>.associateBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -1073,6 +1076,7 @@ public fun <T> Collection<T>.toMutableList(): MutableList<T> {
 
 /**
  * Returns a [Set] of all elements.
+ * The returned set preserves the element iteration order of the original collection.
  */
 public fun <T> Iterable<T>.toSet(): Set<T> {
     if (this is Collection) {
@@ -1123,6 +1127,7 @@ public inline fun <T, R, C : MutableCollection<in R>> Iterable<T>.flatMapTo(dest
 /**
  * Groups elements of the original collection by the key returned by the given [keySelector] function
  * applied to each element and returns a map where each group key is associated with a list of corresponding elements.
+ * The returned map preserves the entry iteration order of the keys produced from the original collection.
  * @sample test.collections.CollectionTest.groupBy
  */
 public inline fun <T, K> Iterable<T>.groupBy(keySelector: (T) -> K): Map<K, List<T>> {
@@ -1133,6 +1138,7 @@ public inline fun <T, K> Iterable<T>.groupBy(keySelector: (T) -> K): Map<K, List
  * Groups values returned by the [valueTransform] function applied to each element of the original collection
  * by the key returned by the given [keySelector] function applied to the element
  * and returns a map where each group key is associated with a list of corresponding values.
+ * The returned map preserves the entry iteration order of the keys produced from the original collection.
  * @sample test.collections.CollectionTest.groupByKeysAndValues
  */
 public inline fun <T, K, V> Iterable<T>.groupBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map<K, List<V>> {
@@ -1284,6 +1290,7 @@ public inline fun <T, K> Iterable<T>.distinctBy(selector: (T) -> K): List<T> {
 
 /**
  * Returns a set containing all elements that are contained by both this set and the specified collection.
+ * The returned set preserves the element iteration order of the original collection.
  */
 public infix fun <T> Iterable<T>.intersect(other: Iterable<T>): Set<T> {
     val set = this.toMutableSet()
@@ -1292,7 +1299,8 @@ public infix fun <T> Iterable<T>.intersect(other: Iterable<T>): Set<T> {
 }
 
 /**
- * Returns a set containing all elements that are contained by this set and not contained by the specified collection.
+ * Returns a set containing all elements that are contained by this collection and not contained by the specified collection.
+ * The returned set preserves the element iteration order of the original collection.
  */
 public infix fun <T> Iterable<T>.subtract(other: Iterable<T>): Set<T> {
     val set = this.toMutableSet()
@@ -1302,6 +1310,7 @@ public infix fun <T> Iterable<T>.subtract(other: Iterable<T>): Set<T> {
 
 /**
  * Returns a mutable set containing all distinct elements from the given collection.
+ * The returned set preserves the element iteration order of the original collection.
  */
 public fun <T> Iterable<T>.toMutableSet(): MutableSet<T> {
     return when (this) {
@@ -1312,6 +1321,9 @@ public fun <T> Iterable<T>.toMutableSet(): MutableSet<T> {
 
 /**
  * Returns a set containing all distinct elements from both collections.
+ * The returned set preserves the element iteration order of the original collection.
+ * Those elements of the [other] collection that are unique are iterated in the end
+ * in the order of the [other] collection.
  */
 public infix fun <T> Iterable<T>.union(other: Iterable<T>): Set<T> {
     val set = this.toMutableSet()

libraries/stdlib/src/generated/_Sequences.kt

@@ -457,6 +457,7 @@ public fun <T> Sequence<T>.sortedWith(comparator: Comparator<in T>): Sequence<T>
  * Returns a [Map] containing key-value pairs provided by [transform] function
  * applied to elements of the given sequence.
  * If any of two pairs would have the same key the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original sequence.
  */
 public inline fun <T, K, V> Sequence<T>.associate(transform: (T) -> Pair<K, V>): Map<K, V> {
     return associateTo(LinkedHashMap<K, V>(), transform)
@@ -466,6 +467,7 @@ public inline fun <T, K, V> Sequence<T>.associate(transform: (T) -> Pair<K, V>):
  * Returns a [Map] containing the elements from the given sequence indexed by the key
  * returned from [keySelector] function applied to each element.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original sequence.
  */
 public inline fun <T, K> Sequence<T>.associateBy(keySelector: (T) -> K): Map<K, T> {
     return associateByTo(LinkedHashMap<K, T>(), keySelector)
@@ -474,6 +476,7 @@ public inline fun <T, K> Sequence<T>.associateBy(keySelector: (T) -> K): Map<K,
 /**
  * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to elements of the given sequence.
  * If any two elements would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original sequence.
  */
 public inline fun <T, K, V> Sequence<T>.associateBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map<K, V> {
     return associateByTo(LinkedHashMap<K, V>(), keySelector, valueTransform)
@@ -550,6 +553,7 @@ public fun <T> Sequence<T>.toMutableList(): MutableList<T> {
 
 /**
  * Returns a [Set] of all elements.
+ * The returned set preserves the element iteration order of the original sequence.
  */
 public fun <T> Sequence<T>.toSet(): Set<T> {
     return toCollection(LinkedHashSet<T>()).optimizeReadOnlySet()
@@ -593,6 +597,7 @@ public inline fun <T, R, C : MutableCollection<in R>> Sequence<T>.flatMapTo(dest
 /**
  * Groups elements of the original sequence by the key returned by the given [keySelector] function
  * applied to each element and returns a map where each group key is associated with a list of corresponding elements.
+ * The returned map preserves the entry iteration order of the keys produced from the original sequence.
  * @sample test.collections.CollectionTest.groupBy
  */
 public inline fun <T, K> Sequence<T>.groupBy(keySelector: (T) -> K): Map<K, List<T>> {
@@ -603,6 +608,7 @@ public inline fun <T, K> Sequence<T>.groupBy(keySelector: (T) -> K): Map<K, List
  * Groups values returned by the [valueTransform] function applied to each element of the original sequence
  * by the key returned by the given [keySelector] function applied to the element
  * and returns a map where each group key is associated with a list of corresponding values.
+ * The returned map preserves the entry iteration order of the keys produced from the original sequence.
  * @sample test.collections.CollectionTest.groupByKeysAndValues
  */
 public inline fun <T, K, V> Sequence<T>.groupBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map<K, List<V>> {
@@ -745,6 +751,7 @@ public fun <T, K> Sequence<T>.distinctBy(selector: (T) -> K): Sequence<T> {
 
 /**
  * Returns a mutable set containing all distinct elements from the given sequence.
+ * The returned set preserves the element iteration order of the original sequence.
  */
 public fun <T> Sequence<T>.toMutableSet(): MutableSet<T> {
     val set = LinkedHashSet<T>()

libraries/stdlib/src/generated/_Sets.kt

@@ -15,6 +15,7 @@ import java.util.Collections // TODO: it's temporary while we have java.util.Col
 
 /**
  * Returns a set containing all elements of the original set except the given [element].
+ * The returned set preserves the element iteration order of the original set.
  */
 public operator fun <T> Set<T>.minus(element: T): Set<T> {
     val result = LinkedHashSet<T>(mapCapacity(size))
@@ -24,6 +25,7 @@ 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.
  */
 public operator fun <T> Set<T>.minus(elements: Array<out T>): Set<T> {
     val result = LinkedHashSet<T>(this)
@@ -33,6 +35,7 @@ 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.
  */
 public operator fun <T> Set<T>.minus(elements: Iterable<T>): Set<T> {
     val other = elements.convertToSetForSetOperationWith(this)
@@ -47,6 +50,7 @@ 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.
  */
 public operator fun <T> Set<T>.minus(elements: Sequence<T>): Set<T> {
     val result = LinkedHashSet<T>(this)
@@ -56,6 +60,7 @@ public operator fun <T> Set<T>.minus(elements: Sequence<T>): Set<T> {
 
 /**
  * Returns a set containing all elements of the original set except the given [element].
+ * The returned set preserves the element iteration order of the original set.
  */
 @kotlin.internal.InlineOnly
 public inline fun <T> Set<T>.minusElement(element: T): Set<T> {
@@ -63,7 +68,8 @@ public inline fun <T> Set<T>.minusElement(element: T): Set<T> {
 }
 
 /**
- * Returns a set containing all elements of the original set and then the given [element].
+ * Returns a set containing all elements of the original set and then the given [element] if it isn't already in this set.
+ * The returned set preserves the element iteration order of the original set.
  */
 public operator fun <T> Set<T>.plus(element: T): Set<T> {
     val result = LinkedHashSet<T>(mapCapacity(size + 1))
@@ -73,7 +79,9 @@ public operator fun <T> Set<T>.plus(element: T): Set<T> {
 }
 
 /**
- * Returns a set containing all elements both of the original set and the given [elements] array.
+ * Returns a set containing all elements of the original set and the given [elements] array,
+ * which aren't already in this set.
+ * The returned set preserves the element iteration order of the original set.
  */
 public operator fun <T> Set<T>.plus(elements: Array<out T>): Set<T> {
     val result = LinkedHashSet<T>(mapCapacity(this.size + elements.size))
@@ -83,7 +91,9 @@ public operator fun <T> Set<T>.plus(elements: Array<out T>): Set<T> {
 }
 
 /**
- * Returns a set containing all elements both of the original set and the given [elements] collection.
+ * Returns a set containing all elements of the original set and the given [elements] collection,
+ * which aren't already in this set.
+ * The returned set preserves the element iteration order of the original set.
  */
 public operator fun <T> Set<T>.plus(elements: Iterable<T>): Set<T> {
     val result = LinkedHashSet<T>(mapCapacity(elements.collectionSizeOrNull()?.let { this.size + it } ?: this.size * 2))
@@ -93,7 +103,9 @@ public operator fun <T> Set<T>.plus(elements: Iterable<T>): Set<T> {
 }
 
 /**
- * Returns a set containing all elements both of the original set and the given [elements] sequence.
+ * Returns a set containing all elements of the original set and the given [elements] sequence,
+ * which aren't already in this set.
+ * The returned set preserves the element iteration order of the original set.
  */
 public operator fun <T> Set<T>.plus(elements: Sequence<T>): Set<T> {
     val result = LinkedHashSet<T>(mapCapacity(this.size * 2))
@@ -103,7 +115,8 @@ public operator fun <T> Set<T>.plus(elements: Sequence<T>): Set<T> {
 }
 
 /**
- * Returns a set containing all elements of the original set and then the given [element].
+ * Returns a set containing all elements of the original set and then the given [element] if it isn't already in this set.
+ * The returned set preserves the element iteration order of the original set.
  */
 @kotlin.internal.InlineOnly
 public inline fun <T> Set<T>.plusElement(element: T): Set<T> {

libraries/stdlib/src/generated/_Strings.kt

@@ -503,6 +503,7 @@ public inline fun String.reversed(): String {
  * Returns a [Map] containing key-value pairs provided by [transform] function
  * applied to characters of the given char sequence.
  * If any of two pairs would have the same key the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original char sequence.
  */
 public inline fun <K, V> CharSequence.associate(transform: (Char) -> Pair<K, V>): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -514,6 +515,7 @@ public inline fun <K, V> CharSequence.associate(transform: (Char) -> Pair<K, V>)
  * Returns a [Map] containing the characters from the given char sequence indexed by the key
  * returned from [keySelector] function applied to each character.
  * If any two characters would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original char sequence.
  */
 public inline fun <K> CharSequence.associateBy(keySelector: (Char) -> K): Map<K, Char> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -524,6 +526,7 @@ public inline fun <K> CharSequence.associateBy(keySelector: (Char) -> K): Map<K,
 /**
  * Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to characters of the given char sequence.
  * If any two characters would have the same key returned by [keySelector] the last one gets added to the map.
+ * The returned map preserves the entry iteration order of the original char sequence.
  */
 public inline fun <K, V> CharSequence.associateBy(keySelector: (Char) -> K, valueTransform: (Char) -> V): Map<K, V> {
     @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -606,6 +609,7 @@ public fun CharSequence.toMutableList(): MutableList<Char> {
 
 /**
  * Returns a [Set] of all characters.
+ * The returned set preserves the element iteration order of the original char sequence.
  */
 public fun CharSequence.toSet(): Set<Char> {
     return when (length) {
@@ -644,6 +648,7 @@ public inline fun <R, C : MutableCollection<in R>> CharSequence.flatMapTo(destin
 /**
  * Groups characters of the original char sequence by the key returned by the given [keySelector] function
  * applied to each character and returns a map where each group key is associated with a list of corresponding characters.
+ * The returned map preserves the entry iteration order of the keys produced from the original char sequence.
  * @sample test.collections.CollectionTest.groupBy
  */
 public inline fun <K> CharSequence.groupBy(keySelector: (Char) -> K): Map<K, List<Char>> {
@@ -654,6 +659,7 @@ public inline fun <K> CharSequence.groupBy(keySelector: (Char) -> K): Map<K, Lis
  * Groups values returned by the [valueTransform] function applied to each character of the original char sequence
  * by the key returned by the given [keySelector] function applied to the character
  * and returns a map where each group key is associated with a list of corresponding values.
+ * The returned map preserves the entry iteration order of the keys produced from the original char sequence.
  * @sample test.collections.CollectionTest.groupByKeysAndValues
  */
 public inline fun <K, V> CharSequence.groupBy(keySelector: (Char) -> K, valueTransform: (Char) -> V): Map<K, List<V>> {

libraries/stdlib/src/kotlin/collections/Maps.kt

@@ -32,6 +32,7 @@ public fun <K, V> emptyMap(): Map<K, V> = @Suppress("CAST_NEVER_SUCCEEDS") (Empt
  * where the first value is the key and the second is the value. If multiple pairs have
  * the same key, the resulting map will contain the value from the last of those pairs.
  *
+ * Entries of the map are iterated in the order they were specified.
  * The returned map is serializable (JVM).
  */
 public fun <K, V> mapOf(vararg pairs: Pair<K, V>): Map<K, V> = if (pairs.size > 0) linkedMapOf(*pairs) else emptyMap()
@@ -49,8 +50,9 @@ public fun <K, V> mapOf(pair: Pair<K, V>): Map<K, V> = Collections.singletonMap(
 
 /**
  * Returns a new [MutableMap] with the specified contents, given as a list of pairs
- * where the first component is the key and the second is the value.
+ * where the first component is the key and the second is the value. If multiple pairs have
- * This map preserves insertion order so iterating through the map's entries will be in the same order.
+ * the same key, the resulting map will contain the value from the last of those pairs.
+ * Entries of the map are iterated in the order they were specified.
  */
 public fun <K, V> mutableMapOf(vararg pairs: Pair<K, V>): MutableMap<K, V>
         = LinkedHashMap<K, V>(mapCapacity(pairs.size)).apply { putAll(pairs) }
@@ -67,8 +69,9 @@ public fun <K, V> hashMapOf(vararg pairs: Pair<K, V>): HashMap<K, V>
 
 /**
  * Returns a new [LinkedHashMap] with the specified contents, given as a list of pairs
- * where the first component is the key and the second is the value.
+ * where the first component is the key and the second is the value. If multiple pairs have
- * This map preserves insertion order so iterating through the map's entries will be in the same order.
+ * the same key, the resulting map will contain the value from the last of those pairs.
+ * Entries of the map are iterated in the order they were specified.
  *
  * @sample test.collections.MapTest.createLinkedMap
  */
@@ -232,16 +235,19 @@ public inline operator fun <K, V> Map<K, V>.iterator(): Iterator<Map.Entry<K, V>
 public inline operator fun <K, V> MutableMap<K, V>.iterator(): MutableIterator<MutableMap.MutableEntry<K, V>> = entries.iterator()
 
 /**
- * Populates the given `destination` [Map] with entries having the keys of this map and the values obtained
+ * Populates the given [destination] map with entries having the keys of this map and the values obtained
- * by applying the `transform` function to each entry in this [Map].
+ * by applying the [transform] function to each entry in this [Map].
  */
 public inline fun <K, V, R, C : MutableMap<in K, in R>> Map<K, V>.mapValuesTo(destination: C, transform: (Map.Entry<K, V>) -> R): C {
     return entries.associateByTo(destination, { it.key }, transform)
 }
 
 /**
- * Populates the given `destination` [Map] with entries having the keys obtained
+ * Populates the given [destination] map with entries having the keys obtained
- * by applying the `transform` function to each entry in this [Map] and the values of this map.
+ * by applying the [transform] function to each entry in this [Map] and the values of this map.
+ *
+ * In case if any two entries are mapped to the equal keys, the value of the latter one will overwrite
+ * the value associated with the former one.
  */
 public inline fun <K, V, R, C : MutableMap<in R, in V>> Map<K, V>.mapKeysTo(destination: C, transform: (Map.Entry<K, V>) -> R): C {
     return entries.associateByTo(destination, transform, { it.value })
@@ -275,9 +281,11 @@ public fun <K, V> MutableMap<in K, in V>.putAll(pairs: Sequence<Pair<K,V>>): Uni
 }
 
 /**
- * Returns a new map with entries having the keys of this map and the values obtained by applying the `transform`
+ * Returns a new map with entries having the keys of this map and the values obtained by applying the [transform]
  * function to each entry in this [Map].
  *
+ * The returned map preserves the entry iteration order of the original map.
+ *
  * @sample test.collections.MapTest.mapValues
  */
 @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -286,9 +294,14 @@ public inline fun <K, V, R> Map<K, V>.mapValues(transform: (Map.Entry<K, V>) ->
 }
 
 /**
- * Returns a new Map with entries having the keys obtained by applying the `transform` function to each entry in this
+ * Returns a new Map with entries having the keys obtained by applying the [transform] function to each entry in this
  * [Map] and the values of this map.
  *
+ * In case if any two entries are mapped to the equal keys, the value of the latter one will overwrite
+ * the value associated with the former one.
+ *
+ * The returned map preserves the entry iteration order of the original map.
+ *
  * @sample test.collections.MapTest.mapKeys
  */
 @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
@@ -298,6 +311,8 @@ public inline fun <K, V, R> Map<K, V>.mapKeys(transform: (Map.Entry<K, V>) -> R)
 
 /**
  * Returns a map containing all key-value pairs with keys matching the given [predicate].
+ *
+ * The returned map preserves the entry iteration order of the original map.
  */
 public inline fun <K, V> Map<K, V>.filterKeys(predicate: (K) -> Boolean): Map<K, V> {
     val result = LinkedHashMap<K, V>()
@@ -311,6 +326,8 @@ public inline fun <K, V> Map<K, V>.filterKeys(predicate: (K) -> Boolean): Map<K,
 
 /**
  * Returns a map containing all key-value pairs with values matching the given [predicate].
+ *
+ * The returned map preserves the entry iteration order of the original map.
  */
 public inline fun <K, V> Map<K, V>.filterValues(predicate: (V) -> Boolean): Map<K, V> {
     val result = LinkedHashMap<K, V>()
@@ -339,6 +356,8 @@ public inline fun <K, V, C : MutableMap<in K, in V>> Map<K, V>.filterTo(destinat
 
 /**
  * Returns a new map containing all key-value pairs matching the given [predicate].
+ *
+ * The returned map preserves the entry iteration order of the original map.
  */
 public inline fun <K, V> Map<K, V>.filter(predicate: (Map.Entry<K, V>) -> Boolean): Map<K, V> {
     return filterTo(LinkedHashMap<K, V>(), predicate)
@@ -360,6 +379,8 @@ public inline fun <K, V, C : MutableMap<in K, in V>> Map<K, V>.filterNotTo(desti
 
 /**
  * Returns a new map containing all key-value pairs not matching the given [predicate].
+ *
+ * The returned map preserves the entry iteration order of the original map.
  */
 public inline fun <K, V> Map<K, V>.filterNot(predicate: (Map.Entry<K, V>) -> Boolean): Map<K, V> {
     return filterNotTo(LinkedHashMap<K, V>(), predicate)
@@ -367,6 +388,8 @@ public inline fun <K, V> Map<K, V>.filterNot(predicate: (Map.Entry<K, V>) -> Boo
 
 /**
  * Returns a new map containing all key-value pairs from the given collection of pairs.
+ *
+ * The returned map preserves the entry iteration order of the original collection.
  */
 public fun <K, V> Iterable<Pair<K, V>>.toMap(): Map<K, V> {
     if (this is Collection) {
@@ -387,6 +410,8 @@ public fun <K, V, M : MutableMap<in K, in V>> Iterable<Pair<K, V>>.toMap(destina
 
 /**
  * Returns a new map containing all key-value pairs from the given array of pairs.
+ *
+ * The returned map preserves the entry iteration order of the original array.
  */
 public fun <K, V> Array<out Pair<K, V>>.toMap(): Map<K, V> = when(size) {
     0 -> emptyMap()
@@ -402,43 +427,58 @@ public fun <K, V, M : MutableMap<in K, in V>> Array<out Pair<K, V>>.toMap(destin
 
 /**
  * Returns a new map containing all key-value pairs from the given sequence of pairs.
+ *
+ * The returned map preserves the entry iteration order of the original sequence.
  */
-
 public fun <K, V> Sequence<Pair<K, V>>.toMap(): Map<K, V> = toMap(LinkedHashMap<K, V>()).optimizeReadOnlyMap()
 
 /**
  * Populates and returns the [destination] mutable map with key-value pairs from the given sequence of pairs.
  */
-
 public fun <K, V, M : MutableMap<in K, in V>> Sequence<Pair<K, V>>.toMap(destination: M): M
         = destination.apply { putAll(this@toMap) }
 
 /**
  * Creates a new read-only map by replacing or adding an entry to this map from a given key-value [pair].
+ *
+ * The returned map preserves the entry iteration order of the original map.
+ * The [pair] is iterated in the end if it has a unique key.
  */
 public operator fun <K, V> Map<out K, V>.plus(pair: Pair<K, V>): Map<K, V>
         = if (this.isEmpty()) mapOf(pair) else LinkedHashMap(this).apply { put(pair.first, pair.second) }
 
 /**
  * Creates a new read-only map by replacing or adding entries to this map from a given collection of key-value [pairs].
+ *
+ * The returned map preserves the entry iteration order of the original map.
+ * Those [pairs] with unique keys are iterated in the end in the order of [pairs] collection.
  */
 public operator fun <K, V> Map<out K, V>.plus(pairs: Iterable<Pair<K, V>>): Map<K, V>
         = if (this.isEmpty()) pairs.toMap() else LinkedHashMap(this).apply { putAll(pairs) }
 
 /**
  * Creates a new read-only map by replacing or adding entries to this map from a given array of key-value [pairs].
+ *
+ * The returned map preserves the entry iteration order of the original map.
+ * Those [pairs] with unique keys are iterated in the end in the order of [pairs] array.
  */
 public operator fun <K, V> Map<out K, V>.plus(pairs: Array<out Pair<K, V>>): Map<K, V>
         = if (this.isEmpty()) pairs.toMap() else LinkedHashMap(this).apply { putAll(pairs) }
 
 /**
  * Creates a new read-only map by replacing or adding entries to this map from a given sequence of key-value [pairs].
+ *
+ * The returned map preserves the entry iteration order of the original map.
+ * Those [pairs] with unique keys are iterated in the end in the order of [pairs] sequence.
  */
 public operator fun <K, V> Map<out K, V>.plus(pairs: Sequence<Pair<K, V>>): Map<K, V>
         = LinkedHashMap(this).apply { putAll(pairs) }.optimizeReadOnlyMap()
 
 /**
  * Creates a new read-only map by replacing or adding entries to this map from another [map].
+ *
+ * The returned map preserves the entry iteration order of the original map.
+ * Those entries of another [map] that are missing in this map are iterated in the end in the order of that [map].
  */
 public operator fun <K, V> Map<out K, V>.plus(map: Map<out K, V>): Map<K, V>
         = LinkedHashMap(this).apply { putAll(map) }

libraries/stdlib/src/kotlin/collections/Sets.kt

@@ -25,20 +25,30 @@ internal object EmptySet : Set<Nothing>, Serializable {
 
 /** Returns an empty read-only set.  The returned set is serializable (JVM). */
 public fun <T> emptySet(): Set<T> = EmptySet
-/** Returns a new read-only ordered set with the given elements.  The returned set is serializable (JVM). */
+/**
+ * Returns a new read-only set with the given elements.
+ * Elements of the set are iterated in the order they were specified.
+ * The returned set is serializable (JVM).
+ */
 public fun <T> setOf(vararg elements: T): Set<T> = if (elements.size > 0) elements.toSet() else emptySet()
 
 /** Returns an empty read-only set.  The returned set is serializable (JVM). */
 @kotlin.internal.InlineOnly
 public inline fun <T> setOf(): Set<T> = emptySet()
 
-/** Returns a new [MutableSet] with the given elements. */
+/**
+ * Returns a new [MutableSet] with the given elements.
+ * Elements of the set are iterated in the order they were specified.
+ */
 public fun <T> mutableSetOf(vararg elements: T): MutableSet<T> = elements.toCollection(LinkedHashSet(mapCapacity(elements.size)))
 
 /** Returns a new [HashSet] with the given elements. */
 public fun <T> hashSetOf(vararg elements: T): HashSet<T> = elements.toCollection(HashSet(mapCapacity(elements.size)))
 
-/** Returns a new [LinkedHashSet] with the given elements. */
+/**
+ * Returns a new [LinkedHashSet] with the given elements.
+ * Elements of the set are iterated in the order they were specified.
+ */
 public fun <T> linkedSetOf(vararg elements: T): LinkedHashSet<T> = elements.toCollection(LinkedHashSet(mapCapacity(elements.size)))
 
 /** Returns this Set if it's not `null` and the empty set otherwise. */

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

@@ -10,7 +10,12 @@ fun generators(): List<GenericFunction> {
 
         only(Iterables, Collections, Sets, Sequences)
         doc { "Returns a list containing all elements of the original collection and then the given [element]." }
-        doc(Sets) { "Returns a set containing all elements of the original set and then the given [element]." }
+        doc(Sets) {
+            """
+            Returns a set containing all elements of the original set and then the given [element] if it isn't already in this set.
+            The returned set preserves the element iteration order of the original set.
+            """
+        }
         doc(Sequences) { "Returns a sequence containing all elements of the original sequence and then the given [element]." }
 
         returns("List<T>")
@@ -45,7 +50,12 @@ fun generators(): List<GenericFunction> {
         // TODO: use build scope function when available
         // TODO: use immutable sets when available
         returns("SELF", Sets, Sequences)
-        doc(Sets) { "Returns a set containing all elements of the original set and then the given [element]." }
+        doc(Sets) {
+            """
+            Returns a set containing all elements of the original set and then the given [element] if it isn't already in this set.
+            The returned set preserves the element iteration order of the original set.
+            """
+        }
         body(Sets) {
             """
             val result = LinkedHashSet<T>(mapCapacity(size + 1))
@@ -95,7 +105,13 @@ fun generators(): List<GenericFunction> {
         }
 
         // TODO: use immutable set builder when available
-        doc(Sets) { "Returns a set containing all elements both of the original set and the given [elements] collection." }
+        doc(Sets) {
+            """
+            Returns a set containing all elements of the original set and the given [elements] collection,
+            which aren't already in this set.
+            The returned set preserves the element iteration order of the original set.
+            """
+        }
         body(Sets) {
             """
             val result = LinkedHashSet<T>(mapCapacity(elements.collectionSizeOrNull()?.let { this.size + it } ?: this.size * 2))
@@ -144,7 +160,13 @@ fun generators(): List<GenericFunction> {
             return result
             """
         }
-        doc(Sets) { "Returns a set containing all elements both of the original set and the given [elements] array." }
+        doc(Sets) {
+            """
+            Returns a set containing all elements of the original set and the given [elements] array,
+            which aren't already in this set.
+            The returned set preserves the element iteration order of the original set.
+            """
+        }
         body(Sets) {
             """
             val result = LinkedHashSet<T>(mapCapacity(this.size + elements.size))
@@ -194,7 +216,13 @@ fun generators(): List<GenericFunction> {
         }
 
         // TODO: use immutable set builder when available
-        doc(Sets) { "Returns a set containing all elements both of the original set and the given [elements] sequence." }
+        doc(Sets) {
+            """
+            Returns a set containing all elements of the original set and the given [elements] sequence,
+            which aren't already in this set.
+            The returned set preserves the element iteration order of the original set.
+            """
+        }
         body(Sets) {
             """
             val result = LinkedHashSet<T>(mapCapacity(this.size * 2))
@@ -224,7 +252,12 @@ fun generators(): List<GenericFunction> {
 
         only(Iterables, Sets, Sequences)
         doc { "Returns a list containing all elements of the original collection without the first occurrence of the given [element]." }
-        doc(Sets) { "Returns a set containing all elements of the original set except the given [element]." }
+        doc(Sets) {
+            """
+            Returns a set containing all elements of the original set except the given [element].
+            The returned set preserves the element iteration order of the original set.
+            """
+        }
         doc(Sequences) { "Returns a sequence containing all elements of the original sequence without the first occurrence of the given [element]." }
 
         returns("List<T>")
@@ -247,7 +280,12 @@ fun generators(): List<GenericFunction> {
         }
 
         returns("SELF", Sets, Sequences)
-        doc(Sets) { "Returns a set containing all elements of the original set except the given [element]." }
+        doc(Sets) {
+            """
+            Returns a set containing all elements of the original set except the given [element].
+            The returned set preserves the element iteration order of the original set.
+            """
+        }
         body(Sets) {
             """
             val result = LinkedHashSet<T>(mapCapacity(size))
@@ -288,7 +326,12 @@ fun generators(): List<GenericFunction> {
             """
         }
 
-        doc(Sets) { "Returns a set containing all elements of the original set except the elements contained in the given [elements] collection." }
+        doc(Sets) {
+            """
+            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.
+            """
+        }
         body(Sets) {
             """
             val other = elements.convertToSetForSetOperationWith(this)
@@ -340,7 +383,12 @@ fun generators(): List<GenericFunction> {
             return this.filterNot { it in other }
             """
         }
-        doc(Sets) { "Returns a set containing all elements of the original set except the elements contained in the given [elements] array." }
+        doc(Sets) {
+            """
+            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.
+            """
+        }
         body(Sets) {
             """
             val result = LinkedHashSet<T>(this)
@@ -386,7 +434,12 @@ fun generators(): List<GenericFunction> {
             return this.filterNot { it in other }
             """
         }
-        doc(Sets) { "Returns a set containing all elements of the original set except the elements contained in the given [elements] sequence." }
+        doc(Sets) {
+            """
+            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.
+            """
+        }
         body(Sets) {
             """
             val result = LinkedHashSet<T>(this)

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

@@ -294,6 +294,7 @@ fun mapping(): List<GenericFunction> {
             """
             Groups ${f.element.pluralize()} of the original ${f.collection} by the key returned by the given [keySelector] function
             applied to each ${f.element} and returns a map where each group key is associated with a list of corresponding ${f.element.pluralize()}.
+            The returned map preserves the entry iteration order of the keys produced from the original ${f.collection}.
             @sample test.collections.CollectionTest.groupBy
             """
         }
@@ -339,6 +340,7 @@ fun mapping(): List<GenericFunction> {
             Groups values returned by the [valueTransform] function applied to each ${f.element} of the original ${f.collection}
             by the key returned by the given [keySelector] function applied to the ${f.element}
             and returns a map where each group key is associated with a list of corresponding values.
+            The returned map preserves the entry iteration order of the keys produced from the original ${f.collection}.
             @sample test.collections.CollectionTest.groupByKeysAndValues
             """
         }

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

@@ -7,7 +7,12 @@ fun sets(): List<GenericFunction> {
 
     templates add f("toMutableSet()") {
         exclude(Strings)
-        doc { f -> "Returns a mutable set containing all distinct ${f.element.pluralize()} from the given ${f.collection}." }
+        doc { f ->
+            """
+            Returns a mutable set containing all distinct ${f.element.pluralize()} from the given ${f.collection}.
+            The returned set preserves the element iteration order of the original ${f.collection}.
+            """
+        }
         returns("MutableSet<T>")
         body {
             """
@@ -24,7 +29,6 @@ fun sets(): List<GenericFunction> {
             return set
             """
         }
-        doc(Sequences) { "Returns a mutable set containing all distinct elements from the given sequence." }
         body(Sequences) {
             """
             val set = LinkedHashSet<T>()
@@ -90,7 +94,14 @@ fun sets(): List<GenericFunction> {
     templates add f("union(other: Iterable<T>)") {
         infix(true)
         exclude(Strings, Sequences)
-        doc { "Returns a set containing all distinct elements from both collections." }
+        doc { f ->
+            """
+            Returns a set containing all distinct elements from both collections.
+            The returned set preserves the element iteration order of the original ${f.collection}.
+            Those elements of the [other] collection that are unique are iterated in the end
+            in the order of the [other] collection.
+            """
+        }
         returns("Set<T>")
         body {
             """
@@ -104,7 +115,12 @@ fun sets(): List<GenericFunction> {
     templates add f("intersect(other: Iterable<T>)") {
         infix(true)
         exclude(Strings, Sequences)
-        doc { "Returns a set containing all elements that are contained by both this set and the specified collection." }
+        doc { f ->
+            """
+            Returns a set containing all elements that are contained by both this set and the specified collection.
+            The returned set preserves the element iteration order of the original ${f.collection}.
+            """
+        }
         returns("Set<T>")
         body {
             """
@@ -118,7 +134,12 @@ fun sets(): List<GenericFunction> {
     templates add f("subtract(other: Iterable<T>)") {
         infix(true)
         exclude(Strings, Sequences)
-        doc { "Returns a set containing all elements that are contained by this set and not contained by the specified collection." }
+        doc { f ->
+            """
+            Returns a set containing all elements that are contained by this ${f.collection} and not contained by the specified collection.
+            The returned set preserves the element iteration order of the original ${f.collection}.
+            """
+        }
         returns("Set<T>")
         body {
             """

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

@@ -21,7 +21,12 @@ fun snapshots(): List<GenericFunction> {
     }
 
     templates add f("toSet()") {
-        doc { f -> "Returns a [Set] of all ${f.element.pluralize()}." }
+        doc { f ->
+            """
+            Returns a [Set] of all ${f.element.pluralize()}.
+            The returned set preserves the element iteration order of the original ${f.collection}.
+            """
+        }
         returns("Set<T>")
         body(Iterables) {
             """
@@ -168,6 +173,7 @@ fun snapshots(): List<GenericFunction> {
             Returns a [Map] containing key-value pairs provided by [transform] function
             applied to ${f.element.pluralize()} of the given ${f.collection}.
             If any of two pairs would have the same key the last one gets added to the map.
+            The returned map preserves the entry iteration order of the original ${f.collection}.
             """
         }
         body {
@@ -231,6 +237,7 @@ fun snapshots(): List<GenericFunction> {
             Returns a [Map] containing the ${f.element.pluralize()} from the given ${f.collection} indexed by the key
             returned from [keySelector] function applied to each ${f.element}.
             If any two ${f.element.pluralize()} would have the same key returned by [keySelector] the last one gets added to the map.
+            The returned map preserves the entry iteration order of the original ${f.collection}.
             """
         }
         returns("Map<K, T>")
@@ -301,6 +308,7 @@ fun snapshots(): List<GenericFunction> {
             """
             Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to ${f.element.pluralize()} of the given ${f.collection}.
             If any two ${f.element.pluralize()} would have the same key returned by [keySelector] the last one gets added to the map.
+            The returned map preserves the entry iteration order of the original ${f.collection}.
             """
         }
         returns("Map<K, V>")