Document that sorting is stable (#2552)

runtime/src/main/kotlin/generated/_ArraysNative.kt

@@ -1388,6 +1388,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) kotlin.util.sortArrayComparable(this)
@@ -1395,6 +1397,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 [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) kotlin.util.sortArrayWith(this, 0, size, comparator)

runtime/src/main/kotlin/kotlin/collections/Arrays.kt

@@ -23,7 +23,12 @@ public actual inline fun <reified T> Array<out T>?.orEmpty(): Array<out T> = thi
         throw IllegalArgumentException("fromIndex ($fromIndex) is greater than toIndex ($toIndex).")
 }
 
-
+// TODO: Move to generated code
+/**
+ * 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 {
     sortArrayWith(this, fromIndex, toIndex, comparator)
 }

runtime/src/main/kotlin/kotlin/collections/MutableCollections.kt

@@ -9,11 +9,15 @@ import kotlin.comparisons.*
 
 /**
  * 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 = sortWith(Comparator<T> { a: T, b: T -> a.compareTo(b) })
 
 /**
  * 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) {