KT-16602: Improve mutable sorting samples, fix sample references

libraries/stdlib/jvm/src/generated/_ArraysJvm.kt

@@ -1818,7 +1818,7 @@ public fun <T> Array<out T>.sort(): Unit {
  * 
  * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  * 
- * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable
+ * @sample samples.collections.Arrays.Sorting.sortRangeOfArrayOfComparable
  */
 public fun <T> Array<out T>.sort(fromIndex: Int = 0, toIndex: Int = size): Unit {
     java.util.Arrays.sort(this, fromIndex, toIndex)
@@ -1827,7 +1827,7 @@ public fun <T> Array<out T>.sort(fromIndex: Int = 0, toIndex: Int = size): Unit
 /**
  * Sorts a range in the array in-place.
  * 
- * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable
+ * @sample samples.collections.Arrays.Sorting.sortRangeOfArray
  */
 public fun ByteArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit {
     java.util.Arrays.sort(this, fromIndex, toIndex)
@@ -1836,7 +1836,7 @@ public fun ByteArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit {
 /**
  * Sorts a range in the array in-place.
  * 
- * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable
+ * @sample samples.collections.Arrays.Sorting.sortRangeOfArray
  */
 public fun ShortArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit {
     java.util.Arrays.sort(this, fromIndex, toIndex)
@@ -1845,7 +1845,7 @@ public fun ShortArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit {
 /**
  * Sorts a range in the array in-place.
  * 
- * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable
+ * @sample samples.collections.Arrays.Sorting.sortRangeOfArray
  */
 public fun IntArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit {
     java.util.Arrays.sort(this, fromIndex, toIndex)
@@ -1854,7 +1854,7 @@ public fun IntArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit {
 /**
  * Sorts a range in the array in-place.
  * 
- * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable
+ * @sample samples.collections.Arrays.Sorting.sortRangeOfArray
  */
 public fun LongArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit {
     java.util.Arrays.sort(this, fromIndex, toIndex)
@@ -1863,7 +1863,7 @@ public fun LongArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit {
 /**
  * Sorts a range in the array in-place.
  * 
- * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable
+ * @sample samples.collections.Arrays.Sorting.sortRangeOfArray
  */
 public fun FloatArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit {
     java.util.Arrays.sort(this, fromIndex, toIndex)
@@ -1872,7 +1872,7 @@ public fun FloatArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit {
 /**
  * Sorts a range in the array in-place.
  * 
- * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable
+ * @sample samples.collections.Arrays.Sorting.sortRangeOfArray
  */
 public fun DoubleArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit {
     java.util.Arrays.sort(this, fromIndex, toIndex)
@@ -1881,7 +1881,7 @@ public fun DoubleArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit {
 /**
  * Sorts a range in the array in-place.
  * 
- * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable
+ * @sample samples.collections.Arrays.Sorting.sortRangeOfArray
  */
 public fun CharArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit {
     java.util.Arrays.sort(this, fromIndex, toIndex)

libraries/stdlib/jvm/src/kotlin/collections/MutableCollectionsJVM.kt

@@ -24,6 +24,7 @@ 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.
+ *
  * @sample samples.collections.Collections.Sorting.sortMutableList
  */
 public actual fun <T : Comparable<T>> MutableList<T>.sort(): Unit {
@@ -34,6 +35,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.
+ *
+ * @sample samples.collections.Collections.Sorting.sortMutableListWith
  */
 public actual fun <T> MutableList<T>.sortWith(comparator: Comparator<in T>): Unit {
     if (size > 1) java.util.Collections.sort(this, comparator)

libraries/stdlib/samples/test/samples/collections/arrays.kt

@@ -137,20 +137,20 @@ class Arrays {
         fun sortArray() {
             val intArray = intArrayOf(4, 3, 2, 1)
 
+            // before sorting
             assertPrints(intArray.joinToString(), "4, 3, 2, 1")
 
             intArray.sort()
 
+            // after sorting
             assertPrints(intArray.joinToString(), "1, 2, 3, 4")
         }
 
         @Sample
         fun sortArrayOfComparable() {
-            data class Person(val firstName: String, val lastName: String) : Comparable<Person> {
+            class Person(val firstName: String, val lastName: String) : Comparable<Person> {
-                override fun compareTo(other: Person): Int {
+                override fun compareTo(other: Person): Int = this.lastName.compareTo(other.lastName)
-                    return lastName.compareTo(other.lastName)
+                override fun toString(): String = "$firstName $lastName"
-                }
-
             }
 
             val people = arrayOf(
@@ -159,11 +159,13 @@ class Arrays {
                 Person("Sweyn", "Forkbeard")
             )
 
-            assertPrints(people.joinToString(), "Person(firstName=Ragnar, lastName=Lodbrok), Person(firstName=Bjorn, lastName=Ironside), Person(firstName=Sweyn, lastName=Forkbeard)")
+            // before sorting
+            assertPrints(people.joinToString(), "Ragnar Lodbrok, Bjorn Ironside, Sweyn Forkbeard")
 
             people.sort()
 
-            assertPrints(people.joinToString(), "Person(firstName=Sweyn, lastName=Forkbeard), Person(firstName=Bjorn, lastName=Ironside), Person(firstName=Ragnar, lastName=Lodbrok)")
+            // after sorting
+            assertPrints(people.joinToString(), "Sweyn Forkbeard, Bjorn Ironside, Ragnar Lodbrok")
 
         }
 
@@ -171,13 +173,37 @@ class Arrays {
         fun sortRangeOfArray() {
             val intArray = intArrayOf(4, 3, 2, 1)
 
+            // before sorting
             assertPrints(intArray.joinToString(), "4, 3, 2, 1")
 
             intArray.sort(0, 3)
 
+            // after sorting
             assertPrints(intArray.joinToString(), "2, 3, 4, 1")
         }
 
+        @Sample
+        fun sortRangeOfArrayOfComparable() {
+            class Person(val firstName: String, val lastName: String) : Comparable<Person> {
+                override fun compareTo(other: Person): Int = this.lastName.compareTo(other.lastName)
+                override fun toString(): String = "$firstName $lastName"
+            }
+
+            val people = arrayOf(
+                Person("Ragnar", "Lodbrok"),
+                Person("Bjorn", "Ironside"),
+                Person("Sweyn", "Forkbeard")
+            )
+
+            // before sorting
+            assertPrints(people.joinToString(), "Ragnar Lodbrok, Bjorn Ironside, Sweyn Forkbeard")
+
+            people.sort(0, 2)
+
+            // after sorting
+            assertPrints(people.joinToString(), "Bjorn Ironside, Ragnar Lodbrok, Sweyn Forkbeard")
+        }
+
     }
 
 }

libraries/stdlib/samples/test/samples/collections/collections.kt

@@ -568,33 +568,32 @@ class Collections {
         fun sortMutableList() {
             val mutableList = mutableListOf(4, 3, 2, 1)
 
+            // before sorting
             assertPrints(mutableList.joinToString(), "4, 3, 2, 1")
 
             mutableList.sort()
 
+            // after sorting
             assertPrints(mutableList.joinToString(), "1, 2, 3, 4")
         }
 
         @Sample
-        fun sortRangeOfComparable() {
+        fun sortMutableListWith() {
-            data class Person(val firstName: String, val lastName: String) : Comparable<Person> {
+            // non-comparable class
-                override fun compareTo(other: Person): Int {
+            class Person(val firstName: String, val lastName: String) {
-                    return lastName.compareTo(other.lastName)
+                override fun toString(): String = "$firstName $lastName"
-                }
-
             }
 
-            val people = arrayOf(
+            val people = mutableListOf(
                 Person("Ragnar", "Lodbrok"),
                 Person("Bjorn", "Ironside"),
                 Person("Sweyn", "Forkbeard")
             )
 
-            assertPrints(people.joinToString(), "Person(firstName=Ragnar, lastName=Lodbrok), Person(firstName=Bjorn, lastName=Ironside), Person(firstName=Sweyn, lastName=Forkbeard)")
+            people.sortWith(compareByDescending { it.firstName })
 
-            people.sort(0, 2)
+            // after sorting
-
+            assertPrints(people.joinToString(), "Sweyn Forkbeard, Ragnar Lodbrok, Bjorn Ironside")
-            assertPrints(people.joinToString(), "Person(firstName=Bjorn, lastName=Ironside), Person(firstName=Ragnar, lastName=Lodbrok), Person(firstName=Sweyn, lastName=Forkbeard)")
         }
 
     }

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

@@ -1146,8 +1146,11 @@ object ArrayOps : TemplateGroupBase() {
         doc { "Sorts a range in the array in-place." }
         specialFor(ArraysOfObjects) {
             appendStableSortNote()
+            sample("samples.collections.Arrays.Sorting.sortRangeOfArrayOfComparable")
+        }
+        specialFor(ArraysOfPrimitives) {
+            sample("samples.collections.Arrays.Sorting.sortRangeOfArray")
         }
-        sample("samples.collections.Arrays.Sorting.sortRangeOfComparable")
         returns("Unit")
         body {
             "java.util.Arrays.sort(this, fromIndex, toIndex)"