From 0ac85ad7152f7ecb1ff6b4bbb9d93d05b8fecb21 Mon Sep 17 00:00:00 2001
From: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>
Date: Wed, 16 Jan 2019 02:50:34 +0300
Subject: [PATCH] Document that sorting is stable in each platform

#KT-12473 Fixed
---
 .../stdlib/common/src/generated/_Arrays.kt    | 26 ++++++++++++
 .../common/src/generated/_Collections.kt      | 16 ++++++++
 .../stdlib/common/src/generated/_Sequences.kt | 10 +++++
 .../js/irRuntime/generated/_ArraysJs.kt       |  6 +++
 .../stdlib/js/src/generated/_ArraysJs.kt      |  6 +++
 libraries/stdlib/js/src/kotlin/collections.kt |  4 ++
 .../stdlib/jvm/src/generated/_ArraysJvm.kt    | 10 +++++
 .../collections/MutableCollectionsJVM.kt      |  4 ++
 .../kotlin-stdlib-gen/src/templates/Arrays.kt | 11 +++++
 .../src/templates/Ordering.kt                 | 41 +++++++++++++++++++
 10 files changed, 134 insertions(+)

diff --git a/libraries/stdlib/common/src/generated/_Arrays.kt b/libraries/stdlib/common/src/generated/_Arrays.kt
index 59127d8e20c..cc15c5828d8 100644
--- a/libraries/stdlib/common/src/generated/_Arrays.kt
+++ b/libraries/stdlib/common/src/generated/_Arrays.kt
@@ -5040,6 +5040,8 @@ public fun CharArray.reversedArray(): CharArray {
 
 /**
  * Sorts elements in the array in-place according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public inline fun <T, R : Comparable<R>> Array<out T>.sortBy(crossinline selector: (T) -> R?): Unit {
     if (size > 1) sortWith(compareBy(selector))
@@ -5047,6 +5049,8 @@ public inline fun <T, R : Comparable<R>> Array<out T>.sortBy(crossinline selecto
 
 /**
  * Sorts elements in the array in-place descending according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public inline fun <T, R : Comparable<R>> Array<out T>.sortByDescending(crossinline selector: (T) -> R?): Unit {
     if (size > 1) sortWith(compareByDescending(selector))
@@ -5054,6 +5058,8 @@ public inline fun <T, R : Comparable<R>> Array<out T>.sortByDescending(crossinli
 
 /**
  * Sorts elements in the array in-place descending according to their natural sort order.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public fun <T : Comparable<T>> Array<out T>.sortDescending(): Unit {
     sortWith(reverseOrder())
@@ -5131,6 +5137,8 @@ public fun CharArray.sortDescending(): Unit {
 
 /**
  * Returns a list of all elements sorted according to their natural sort order.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public fun <T : Comparable<T>> Array<out T>.sorted(): List<T> {
     return sortedArray().asList()
@@ -5187,6 +5195,8 @@ public fun CharArray.sorted(): List<Char> {
 
 /**
  * Returns an array with all elements of this array sorted according to their natural sort order.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public fun <T : Comparable<T>> Array<T>.sortedArray(): Array<T> {
     if (isEmpty()) return this
@@ -5251,6 +5261,8 @@ public fun CharArray.sortedArray(): CharArray {
 
 /**
  * Returns an array with all elements of this array sorted descending according to their natural sort order.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public fun <T : Comparable<T>> Array<T>.sortedArrayDescending(): Array<T> {
     if (isEmpty()) return this
@@ -5315,6 +5327,8 @@ public fun CharArray.sortedArrayDescending(): CharArray {
 
 /**
  * Returns an array with all elements of this array sorted according the specified [comparator].
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public fun <T> Array<out T>.sortedArrayWith(comparator: Comparator<in T>): Array<out T> {
     if (isEmpty()) return this
@@ -5323,6 +5337,8 @@ public fun <T> Array<out T>.sortedArrayWith(comparator: Comparator<in T>): Array
 
 /**
  * Returns a list of all elements sorted according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public inline fun <T, R : Comparable<R>> Array<out T>.sortedBy(crossinline selector: (T) -> R?): List<T> {
     return sortedWith(compareBy(selector))
@@ -5386,6 +5402,8 @@ public inline fun <R : Comparable<R>> CharArray.sortedBy(crossinline selector: (
 
 /**
  * Returns a list of all elements sorted descending according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public inline fun <T, R : Comparable<R>> Array<out T>.sortedByDescending(crossinline selector: (T) -> R?): List<T> {
     return sortedWith(compareByDescending(selector))
@@ -5449,6 +5467,8 @@ public inline fun <R : Comparable<R>> CharArray.sortedByDescending(crossinline s
 
 /**
  * Returns a list of all elements sorted descending according to their natural sort order.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public fun <T : Comparable<T>> Array<out T>.sortedDescending(): List<T> {
     return sortedWith(reverseOrder())
@@ -5505,6 +5525,8 @@ public fun CharArray.sortedDescending(): List<Char> {
 
 /**
  * Returns a list of all elements sorted according to the specified [comparator].
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public fun <T> Array<out T>.sortedWith(comparator: Comparator<in T>): List<T> {
     return sortedArrayWith(comparator).asList()
@@ -6702,11 +6724,15 @@ public expect fun CharArray.sort(): Unit
 
 /**
  * Sorts the array in-place according to the natural order of its elements.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public expect fun <T : Comparable<T>> Array<out T>.sort(): Unit
 
 /**
  * Sorts the array in-place according to the order specified by the given [comparator].
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public expect fun <T> Array<out T>.sortWith(comparator: Comparator<in T>): Unit
 
diff --git a/libraries/stdlib/common/src/generated/_Collections.kt b/libraries/stdlib/common/src/generated/_Collections.kt
index 8b77a7f9ad1..1c045d13076 100644
--- a/libraries/stdlib/common/src/generated/_Collections.kt
+++ b/libraries/stdlib/common/src/generated/_Collections.kt
@@ -861,6 +861,8 @@ public fun <T> Iterable<T>.reversed(): List<T> {
 
 /**
  * Sorts elements in the list in-place according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public inline fun <T, R : Comparable<R>> MutableList<T>.sortBy(crossinline selector: (T) -> R?): Unit {
     if (size > 1) sortWith(compareBy(selector))
@@ -868,6 +870,8 @@ public inline fun <T, R : Comparable<R>> MutableList<T>.sortBy(crossinline selec
 
 /**
  * Sorts elements in the list in-place descending according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public inline fun <T, R : Comparable<R>> MutableList<T>.sortByDescending(crossinline selector: (T) -> R?): Unit {
     if (size > 1) sortWith(compareByDescending(selector))
@@ -875,6 +879,8 @@ public inline fun <T, R : Comparable<R>> MutableList<T>.sortByDescending(crossin
 
 /**
  * Sorts elements in the list in-place descending according to their natural sort order.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public fun <T : Comparable<T>> MutableList<T>.sortDescending(): Unit {
     sortWith(reverseOrder())
@@ -882,6 +888,8 @@ public fun <T : Comparable<T>> MutableList<T>.sortDescending(): Unit {
 
 /**
  * Returns a list of all elements sorted according to their natural sort order.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public fun <T : Comparable<T>> Iterable<T>.sorted(): List<T> {
     if (this is Collection) {
@@ -894,6 +902,8 @@ public fun <T : Comparable<T>> Iterable<T>.sorted(): List<T> {
 
 /**
  * Returns a list of all elements sorted according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public inline fun <T, R : Comparable<R>> Iterable<T>.sortedBy(crossinline selector: (T) -> R?): List<T> {
     return sortedWith(compareBy(selector))
@@ -901,6 +911,8 @@ public inline fun <T, R : Comparable<R>> Iterable<T>.sortedBy(crossinline select
 
 /**
  * Returns a list of all elements sorted descending according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public inline fun <T, R : Comparable<R>> Iterable<T>.sortedByDescending(crossinline selector: (T) -> R?): List<T> {
     return sortedWith(compareByDescending(selector))
@@ -908,6 +920,8 @@ public inline fun <T, R : Comparable<R>> Iterable<T>.sortedByDescending(crossinl
 
 /**
  * Returns a list of all elements sorted descending according to their natural sort order.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public fun <T : Comparable<T>> Iterable<T>.sortedDescending(): List<T> {
     return sortedWith(reverseOrder())
@@ -915,6 +929,8 @@ public fun <T : Comparable<T>> Iterable<T>.sortedDescending(): List<T> {
 
 /**
  * Returns a list of all elements sorted according to the specified [comparator].
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public fun <T> Iterable<T>.sortedWith(comparator: Comparator<in T>): List<T> {
     if (this is Collection) {
diff --git a/libraries/stdlib/common/src/generated/_Sequences.kt b/libraries/stdlib/common/src/generated/_Sequences.kt
index 5ea1d117639..a22b5f70cdd 100644
--- a/libraries/stdlib/common/src/generated/_Sequences.kt
+++ b/libraries/stdlib/common/src/generated/_Sequences.kt
@@ -502,6 +502,8 @@ public fun <T> Sequence<T>.takeWhile(predicate: (T) -> Boolean): Sequence<T> {
 
 /**
  * Returns a sequence that yields elements of this sequence sorted according to their natural sort order.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  *
  * The operation is _intermediate_ and _stateful_.
  */
@@ -517,6 +519,8 @@ public fun <T : Comparable<T>> Sequence<T>.sorted(): Sequence<T> {
 
 /**
  * Returns a sequence that yields elements of this sequence sorted according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  *
  * The operation is _intermediate_ and _stateful_.
  */
@@ -526,6 +530,8 @@ public inline fun <T, R : Comparable<R>> Sequence<T>.sortedBy(crossinline select
 
 /**
  * Returns a sequence that yields elements of this sequence sorted descending according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  *
  * The operation is _intermediate_ and _stateful_.
  */
@@ -535,6 +541,8 @@ public inline fun <T, R : Comparable<R>> Sequence<T>.sortedByDescending(crossinl
 
 /**
  * Returns a sequence that yields elements of this sequence sorted descending according to their natural sort order.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  *
  * The operation is _intermediate_ and _stateful_.
  */
@@ -544,6 +552,8 @@ public fun <T : Comparable<T>> Sequence<T>.sortedDescending(): Sequence<T> {
 
 /**
  * Returns a sequence that yields elements of this sequence sorted according to the specified [comparator].
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  *
  * The operation is _intermediate_ and _stateful_.
  */
diff --git a/libraries/stdlib/js/irRuntime/generated/_ArraysJs.kt b/libraries/stdlib/js/irRuntime/generated/_ArraysJs.kt
index 4af1303e786..f0617b7c9a4 100644
--- a/libraries/stdlib/js/irRuntime/generated/_ArraysJs.kt
+++ b/libraries/stdlib/js/irRuntime/generated/_ArraysJs.kt
@@ -1198,6 +1198,8 @@ public actual fun CharArray.sort(): Unit {
 
 /**
  * Sorts the array in-place according to the natural order of its elements.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public actual fun <T : Comparable<T>> Array<out T>.sort(): Unit {
     if (size > 1) sortArray(this)
@@ -1205,6 +1207,8 @@ public actual fun <T : Comparable<T>> Array<out T>.sort(): Unit {
 
 /**
  * Sorts the array in-place according to the order specified by the given [comparison] function.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public fun <T> Array<out T>.sort(comparison: (a: T, b: T) -> Int): Unit {
     if (size > 1) sortArrayWith(this, comparison)
@@ -1268,6 +1272,8 @@ public inline fun CharArray.sort(noinline comparison: (a: Char, b: Char) -> Int)
 
 /**
  * Sorts the array in-place according to the order specified by the given [comparator].
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public actual fun <T> Array<out T>.sortWith(comparator: Comparator<in T>): Unit {
     if (size > 1) sortArrayWith(this, comparator)
diff --git a/libraries/stdlib/js/src/generated/_ArraysJs.kt b/libraries/stdlib/js/src/generated/_ArraysJs.kt
index e2144d233d5..639b78f8e13 100644
--- a/libraries/stdlib/js/src/generated/_ArraysJs.kt
+++ b/libraries/stdlib/js/src/generated/_ArraysJs.kt
@@ -1234,6 +1234,8 @@ public actual fun CharArray.sort(): Unit {
 
 /**
  * Sorts the array in-place according to the natural order of its elements.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public actual fun <T : Comparable<T>> Array<out T>.sort(): Unit {
     if (size > 1) sortArray(this)
@@ -1241,6 +1243,8 @@ public actual fun <T : Comparable<T>> Array<out T>.sort(): Unit {
 
 /**
  * Sorts the array in-place according to the order specified by the given [comparison] function.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public fun <T> Array<out T>.sort(comparison: (a: T, b: T) -> Int): Unit {
     if (size > 1) sortArrayWith(this, comparison)
@@ -1304,6 +1308,8 @@ public inline fun CharArray.sort(noinline comparison: (a: Char, b: Char) -> Int)
 
 /**
  * Sorts the array in-place according to the order specified by the given [comparator].
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public actual fun <T> Array<out T>.sortWith(comparator: Comparator<in T>): Unit {
     if (size > 1) sortArrayWith(this, comparator)
diff --git a/libraries/stdlib/js/src/kotlin/collections.kt b/libraries/stdlib/js/src/kotlin/collections.kt
index 6abd57149f3..a7c52b110f8 100644
--- a/libraries/stdlib/js/src/kotlin/collections.kt
+++ b/libraries/stdlib/js/src/kotlin/collections.kt
@@ -93,6 +93,8 @@ public actual fun <T> Iterable<T>.shuffled(): List<T> = toMutableList().apply {
 
 /**
  * Sorts elements in the list in-place according to their natural sort order.
+ *
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public actual fun <T : Comparable<T>> MutableList<T>.sort(): Unit {
     collectionsSort(this, naturalOrder())
@@ -100,6 +102,8 @@ public actual fun <T : Comparable<T>> MutableList<T>.sort(): Unit {
 
 /**
  * Sorts elements in the list in-place according to the order specified with [comparator].
+ *
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public actual fun <T> MutableList<T>.sortWith(comparator: Comparator<in T>): Unit {
     collectionsSort(this, comparator)
diff --git a/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt b/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt
index 770b6a33d80..4ef29d904bf 100644
--- a/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt
+++ b/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt
@@ -1685,6 +1685,8 @@ public actual fun CharArray.sort(): Unit {
 
 /**
  * Sorts the array in-place according to the natural order of its elements.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 @kotlin.internal.InlineOnly
 public actual inline fun <T : Comparable<T>> Array<out T>.sort(): Unit {
@@ -1695,6 +1697,8 @@ public actual inline fun <T : Comparable<T>> Array<out T>.sort(): Unit {
 /**
  * Sorts the array in-place according to the natural order of its elements.
  * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
+ * 
  * @throws ClassCastException if any element of the array is not [Comparable].
  */
 public fun <T> Array<out T>.sort(): Unit {
@@ -1703,6 +1707,8 @@ public fun <T> Array<out T>.sort(): Unit {
 
 /**
  * Sorts a range in the array in-place.
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public fun <T> Array<out T>.sort(fromIndex: Int = 0, toIndex: Int = size): Unit {
     java.util.Arrays.sort(this, fromIndex, toIndex)
@@ -1759,6 +1765,8 @@ public fun CharArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit {
 
 /**
  * Sorts the array in-place according to the order specified by the given [comparator].
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public actual fun <T> Array<out T>.sortWith(comparator: Comparator<in T>): Unit {
     if (size > 1) java.util.Arrays.sort(this, comparator)
@@ -1766,6 +1774,8 @@ public actual fun <T> Array<out T>.sortWith(comparator: Comparator<in T>): Unit
 
 /**
  * Sorts a range in the array in-place with the given [comparator].
+ * 
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public fun <T> Array<out T>.sortWith(comparator: Comparator<in T>, fromIndex: Int = 0, toIndex: Int = size): Unit {
     java.util.Arrays.sort(this, fromIndex, toIndex, comparator)
diff --git a/libraries/stdlib/jvm/src/kotlin/collections/MutableCollectionsJVM.kt b/libraries/stdlib/jvm/src/kotlin/collections/MutableCollectionsJVM.kt
index 5fc774ea036..a861574744c 100644
--- a/libraries/stdlib/jvm/src/kotlin/collections/MutableCollectionsJVM.kt
+++ b/libraries/stdlib/jvm/src/kotlin/collections/MutableCollectionsJVM.kt
@@ -22,6 +22,8 @@ public inline fun <T> MutableList<T>.sort(comparison: (T, T) -> Int): Unit = thr
 
 /**
  * Sorts elements in the list in-place according to their natural sort order.
+ *
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public actual fun <T : Comparable<T>> MutableList<T>.sort(): Unit {
     if (size > 1) java.util.Collections.sort(this)
@@ -29,6 +31,8 @@ public actual fun <T : Comparable<T>> MutableList<T>.sort(): Unit {
 
 /**
  * Sorts elements in the list in-place according to the order specified with [comparator].
+ *
+ * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  */
 public actual fun <T> MutableList<T>.sortWith(comparator: Comparator<in T>): Unit {
     if (size > 1) java.util.Collections.sort(this, comparator)
diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt
index c92f7da1673..5849f683d28 100644
--- a/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt
+++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt
@@ -6,6 +6,8 @@
 package templates
 
 import templates.Family.*
+import templates.Ordering.stableSortNote
+import templates.Ordering.appendStableSortNote
 
 object ArrayOps : TemplateGroupBase() {
 
@@ -884,6 +886,7 @@ object ArrayOps : TemplateGroupBase() {
     } builder {
         typeParam("T : Comparable<T>")
         doc { "Sorts the array in-place according to the natural order of its elements." }
+        appendStableSortNote()
         specialFor(ArraysOfPrimitives) {
             doc { "Sorts the array in-place." }
         }
@@ -939,6 +942,7 @@ object ArrayOps : TemplateGroupBase() {
         include(ArraysOfObjects)
     } builder {
         doc { "Sorts the array in-place according to the order specified by the given [comparator]." }
+        appendStableSortNote()
         returns("Unit")
         on(Platform.JVM) {
             body {
@@ -968,6 +972,7 @@ object ArrayOps : TemplateGroupBase() {
             body { "asDynamic().sort(comparison)" }
         }
         specialFor(ArraysOfObjects) {
+            appendStableSortNote()
             body { """if (size > 1) sortArrayWith(this, comparison)""" }
         }
     }
@@ -981,6 +986,8 @@ object ArrayOps : TemplateGroupBase() {
             """
             Sorts the array in-place according to the natural order of its elements.
 
+            $stableSortNote
+
             @throws ClassCastException if any element of the array is not [Comparable].
             """
         }
@@ -996,6 +1003,9 @@ object ArrayOps : TemplateGroupBase() {
         exclude(PrimitiveType.Boolean)
     } builder {
         doc { "Sorts a range in the array in-place." }
+        specialFor(ArraysOfObjects) {
+            appendStableSortNote()
+        }
         returns("Unit")
         body {
             "java.util.Arrays.sort(this, fromIndex, toIndex)"
@@ -1007,6 +1017,7 @@ object ArrayOps : TemplateGroupBase() {
         include(ArraysOfObjects)
     } builder {
         doc { "Sorts a range in the array in-place with the given [comparator]." }
+        appendStableSortNote()
         returns("Unit")
         body {
             "java.util.Arrays.sort(this, fromIndex, toIndex, comparator)"
diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt
index e441ecf4a04..ee1246e0286 100644
--- a/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt
+++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt
@@ -96,6 +96,15 @@ object Ordering : TemplateGroupBase() {
         }
     }
 
+    val stableSortNote =
+        "The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting."
+
+    fun MemberBuilder.appendStableSortNote() {
+        doc {
+            doc.orEmpty().trimIndent() + "\n\n" + stableSortNote
+        }
+    }
+
     val f_sorted = fn("sorted()") {
         includeDefault()
         exclude(PrimitiveType.Boolean)
@@ -106,6 +115,9 @@ object Ordering : TemplateGroupBase() {
             Returns a list of all elements sorted according to their natural sort order.
             """
         }
+        if (f != ArraysOfPrimitives) {
+            appendStableSortNote()
+        }
         returns("List<T>")
         typeParam("T : Comparable<T>")
         body {
@@ -134,6 +146,7 @@ object Ordering : TemplateGroupBase() {
             doc {
                 "Returns a sequence that yields elements of this sequence sorted according to their natural sort order."
             }
+            appendStableSortNote()
             sequenceClassification(intermediate, stateful)
         }
         body(Sequences) {
@@ -156,6 +169,9 @@ object Ordering : TemplateGroupBase() {
         doc {
             "Returns an array with all elements of this array sorted according to their natural sort order."
         }
+        specialFor(InvariantArraysOfObjects) {
+            appendStableSortNote()
+        }
         typeParam("T : Comparable<T>")
         returns("SELF")
         body {
@@ -171,6 +187,9 @@ object Ordering : TemplateGroupBase() {
         exclude(PrimitiveType.Boolean)
     } builder {
         doc { """Sorts elements in the ${f.collection} in-place descending according to their natural sort order.""" }
+        if (f != ArraysOfPrimitives) {
+            appendStableSortNote()
+        }
         returns("Unit")
         typeParam("T : Comparable<T>")
         specialFor(Lists) {
@@ -198,6 +217,9 @@ object Ordering : TemplateGroupBase() {
             Returns a list of all elements sorted descending according to their natural sort order.
             """
         }
+        if (f != ArraysOfPrimitives) {
+            appendStableSortNote()
+        }
         returns("List<T>")
         typeParam("T : Comparable<T>")
         body {
@@ -216,6 +238,7 @@ object Ordering : TemplateGroupBase() {
             doc {
                 "Returns a sequence that yields elements of this sequence sorted descending according to their natural sort order."
             }
+            appendStableSortNote()
             sequenceClassification(intermediate, stateful)
         }
     }
@@ -227,6 +250,9 @@ object Ordering : TemplateGroupBase() {
         doc {
             "Returns an array with all elements of this array sorted descending according to their natural sort order."
         }
+        specialFor(InvariantArraysOfObjects) {
+            appendStableSortNote()
+        }
         typeParam("T : Comparable<T>")
         returns("SELF")
         body(InvariantArraysOfObjects) {
@@ -252,6 +278,9 @@ object Ordering : TemplateGroupBase() {
             Returns a list of all elements sorted according to the specified [comparator].
             """
         }
+        if (f != ArraysOfPrimitives) {
+            appendStableSortNote()
+        }
         body {
             """
              if (this is Collection) {
@@ -278,6 +307,7 @@ object Ordering : TemplateGroupBase() {
             doc {
                 "Returns a sequence that yields elements of this sequence sorted according to the specified [comparator]."
             }
+            appendStableSortNote()
             sequenceClassification(intermediate, stateful)
         }
         body(Sequences) {
@@ -299,6 +329,7 @@ object Ordering : TemplateGroupBase() {
         doc {
             "Returns an array with all elements of this array sorted according the specified [comparator]."
         }
+        appendStableSortNote()
         returns("SELF")
         body {
             """
@@ -313,6 +344,7 @@ object Ordering : TemplateGroupBase() {
     } builder {
         inline()
         doc { """Sorts elements in the ${f.collection} in-place according to natural sort order of the value returned by specified [selector] function.""" }
+        appendStableSortNote()
         returns("Unit")
         typeParam("R : Comparable<R>")
         specialFor(Lists) { receiver("MutableList<T>") }
@@ -332,12 +364,16 @@ object Ordering : TemplateGroupBase() {
             Returns a list of all elements sorted according to natural sort order of the value returned by specified [selector] function.
             """
         }
+        if (f != ArraysOfPrimitives) {
+            appendStableSortNote()
+        }
 
         specialFor(Sequences) {
             returns("SELF")
             doc {
                 "Returns a sequence that yields elements of this sequence sorted according to natural sort order of the value returned by specified [selector] function."
             }
+            appendStableSortNote()
             sequenceClassification(intermediate, stateful)
         }
         body {
@@ -350,6 +386,7 @@ object Ordering : TemplateGroupBase() {
     } builder {
         inline()
         doc { """Sorts elements in the ${f.collection} in-place descending according to natural sort order of the value returned by specified [selector] function.""" }
+        appendStableSortNote()
         returns("Unit")
         typeParam("R : Comparable<R>")
         specialFor(Lists) { receiver("MutableList<T>") }
@@ -370,12 +407,16 @@ object Ordering : TemplateGroupBase() {
             Returns a list of all elements sorted descending according to natural sort order of the value returned by specified [selector] function.
             """
         }
+        if (f != ArraysOfPrimitives) {
+            appendStableSortNote()
+        }
 
         specialFor(Sequences) {
             returns("SELF")
             doc {
                 "Returns a sequence that yields elements of this sequence sorted descending according to natural sort order of the value returned by specified [selector] function."
             }
+            appendStableSortNote()
             sequenceClassification(intermediate, stateful)
         }