[KT-74034] feat: add samples for sortBy and sortByDescending functions

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

diff --git a/libraries/stdlib/samples/test/samples/collections/collections.kt b/libraries/stdlib/samples/test/samples/collections/collections.kt
index 6eb9602..9cbdb89 100644
--- a/libraries/stdlib/samples/test/samples/collections/collections.kt
+++ b/libraries/stdlib/samples/test/samples/collections/collections.kt
@@ -1261,6 +1261,54 @@
     class Sorting {
 
         @Sample
+        fun sortBy() {
+            class Dish(val name: String, val calories: Int, val tasteRate: Float) {
+                override fun toString(): String = "Dish($name: $calories cal, taste $tasteRate/5)"
+            }
+
+            val fridgeContent = mutableListOf(Dish("🍨", 207, 4.7f), Dish("🥦", 34, 2.3f), Dish("🧃", 34, 4.9f))
+            
+            // original order
+            assertPrints(fridgeContent, "[Dish(🍨: 207 cal, taste 4.7/5), Dish(🥦: 34 cal, taste 2.3/5), Dish(🧃: 34 cal, taste 4.9/5)]")
+            
+            // sort by taste rate
+            fridgeContent.sortBy { it.tasteRate }
+            assertPrints(fridgeContent, "[Dish(🥦: 34 cal, taste 2.3/5), Dish(🍨: 207 cal, taste 4.7/5), Dish(🧃: 34 cal, taste 4.9/5)]")
+            
+            // create a new list with the same elements
+            val newFridgeContent = mutableListOf(Dish("🍨", 207, 4.7f), Dish("🥦", 34, 2.3f), Dish("🧃", 34, 4.9f))
+            
+            // sort by calories
+            newFridgeContent.sortBy { it.calories }
+            // note that the sorting is stable, so the 🥦 is before the 🧃
+            assertPrints(newFridgeContent, "[Dish(🥦: 34 cal, taste 2.3/5), Dish(🧃: 34 cal, taste 4.9/5), Dish(🍨: 207 cal, taste 4.7/5)]")
+        }
+        
+        @Sample
+        fun sortByDescending() {
+            class Dish(val name: String, val calories: Int, val tasteRate: Float) {
+                override fun toString(): String = "Dish($name: $calories cal, taste $tasteRate/5)"
+            }
+
+            val fridgeContent = mutableListOf(Dish("🍨", 207, 4.7f), Dish("🥦", 34, 2.3f), Dish("🧃", 34, 4.9f))
+            
+            // original order
+            assertPrints(fridgeContent, "[Dish(🍨: 207 cal, taste 4.7/5), Dish(🥦: 34 cal, taste 2.3/5), Dish(🧃: 34 cal, taste 4.9/5)]")
+            
+            // sort by taste rate in descending order
+            fridgeContent.sortByDescending { it.tasteRate }
+            assertPrints(fridgeContent, "[Dish(🧃: 34 cal, taste 4.9/5), Dish(🍨: 207 cal, taste 4.7/5), Dish(🥦: 34 cal, taste 2.3/5)]")
+            
+            // create a new list with the same elements
+            val newFridgeContent = mutableListOf(Dish("🍨", 207, 4.7f), Dish("🥦", 34, 2.3f), Dish("🧃", 34, 4.9f))
+            
+            // sort by calories in descending order
+            newFridgeContent.sortByDescending { it.calories }
+            // note that the sorting is stable, so the 🥦 is before the 🧃
+            assertPrints(newFridgeContent, "[Dish(🍨: 207 cal, taste 4.7/5), Dish(🥦: 34 cal, taste 2.3/5), Dish(🧃: 34 cal, taste 4.9/5)]")
+        }
+
+        @Sample
         fun sortMutableList() {
             val mutableList = mutableListOf(4, 3, 2, 1)
 

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

diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt
index acd7cb9..730d8ad 100644
--- a/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt
+++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt
@@ -424,6 +424,8 @@
         returns("Unit")
         typeParam("R : Comparable<R>")
         specialFor(Lists) { receiver("MutableList<T>") }
+        
+        sample("samples.collections.Collections.Sorting.sortBy")
 
         body { """if (size > 1) sortWith(compareBy(selector))""" }
     }
@@ -477,6 +479,8 @@
         returns("Unit")
         typeParam("R : Comparable<R>")
         specialFor(Lists) { receiver("MutableList<T>") }
+        
+        sample("samples.collections.Collections.Sorting.sortByDescending")
 
         body {
             """if (size > 1) sortWith(compareByDescending(selector))""" }