Add samples for coerceAtMost

#KT-20357

js/js.libraries/src/core/generated/_RangesJs.kt

@@ -722,6 +722,7 @@ public fun Double.coerceAtLeast(minimumValue: Double): Double {
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public fun <T: Comparable<T>> T.coerceAtMost(maximumValue: T): T {
     return if (this > maximumValue) maximumValue else this
@@ -731,6 +732,7 @@ public fun <T: Comparable<T>> T.coerceAtMost(maximumValue: T): T {
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public fun Byte.coerceAtMost(maximumValue: Byte): Byte {
     return if (this > maximumValue) maximumValue else this
@@ -740,6 +742,7 @@ public fun Byte.coerceAtMost(maximumValue: Byte): Byte {
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public fun Short.coerceAtMost(maximumValue: Short): Short {
     return if (this > maximumValue) maximumValue else this
@@ -749,6 +752,7 @@ public fun Short.coerceAtMost(maximumValue: Short): Short {
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public fun Int.coerceAtMost(maximumValue: Int): Int {
     return if (this > maximumValue) maximumValue else this
@@ -758,6 +762,7 @@ public fun Int.coerceAtMost(maximumValue: Int): Int {
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public fun Long.coerceAtMost(maximumValue: Long): Long {
     return if (this > maximumValue) maximumValue else this
@@ -767,6 +772,7 @@ public fun Long.coerceAtMost(maximumValue: Long): Long {
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public fun Float.coerceAtMost(maximumValue: Float): Float {
     return if (this > maximumValue) maximumValue else this
@@ -776,6 +782,7 @@ public fun Float.coerceAtMost(maximumValue: Float): Float {
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public fun Double.coerceAtMost(maximumValue: Double): Double {
     return if (this > maximumValue) maximumValue else this

libraries/stdlib/common/src/generated/_Ranges.kt

@@ -528,6 +528,7 @@ public expect fun Double.coerceAtLeast(minimumValue: Double): Double
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public expect fun <T: Comparable<T>> T.coerceAtMost(maximumValue: T): T
 
@@ -535,6 +536,7 @@ public expect fun <T: Comparable<T>> T.coerceAtMost(maximumValue: T): T
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public expect fun Byte.coerceAtMost(maximumValue: Byte): Byte
 
@@ -542,6 +544,7 @@ public expect fun Byte.coerceAtMost(maximumValue: Byte): Byte
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public expect fun Short.coerceAtMost(maximumValue: Short): Short
 
@@ -549,6 +552,7 @@ public expect fun Short.coerceAtMost(maximumValue: Short): Short
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public expect fun Int.coerceAtMost(maximumValue: Int): Int
 
@@ -556,6 +560,7 @@ public expect fun Int.coerceAtMost(maximumValue: Int): Int
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public expect fun Long.coerceAtMost(maximumValue: Long): Long
 
@@ -563,6 +568,7 @@ public expect fun Long.coerceAtMost(maximumValue: Long): Long
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public expect fun Float.coerceAtMost(maximumValue: Float): Float
 
@@ -570,6 +576,7 @@ public expect fun Float.coerceAtMost(maximumValue: Float): Float
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public expect fun Double.coerceAtMost(maximumValue: Double): Double
 

libraries/stdlib/samples/test/samples/comparisons/comparableOps.kt

@@ -26,4 +26,9 @@ class ComparableOps {
         assertPrints(10.coerceAtLeast(20), "20")
     }
 
+    @Sample
+    fun coerceAtMost() {
+        assertPrints(10.coerceAtMost(5), "5")
+        assertPrints(10.coerceAtMost(20), "10")
+    }
 }

libraries/stdlib/src/generated/_Ranges.kt

@@ -722,6 +722,7 @@ public fun Double.coerceAtLeast(minimumValue: Double): Double {
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public fun <T: Comparable<T>> T.coerceAtMost(maximumValue: T): T {
     return if (this > maximumValue) maximumValue else this
@@ -731,6 +732,7 @@ public fun <T: Comparable<T>> T.coerceAtMost(maximumValue: T): T {
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public fun Byte.coerceAtMost(maximumValue: Byte): Byte {
     return if (this > maximumValue) maximumValue else this
@@ -740,6 +742,7 @@ public fun Byte.coerceAtMost(maximumValue: Byte): Byte {
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public fun Short.coerceAtMost(maximumValue: Short): Short {
     return if (this > maximumValue) maximumValue else this
@@ -749,6 +752,7 @@ public fun Short.coerceAtMost(maximumValue: Short): Short {
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public fun Int.coerceAtMost(maximumValue: Int): Int {
     return if (this > maximumValue) maximumValue else this
@@ -758,6 +762,7 @@ public fun Int.coerceAtMost(maximumValue: Int): Int {
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public fun Long.coerceAtMost(maximumValue: Long): Long {
     return if (this > maximumValue) maximumValue else this
@@ -767,6 +772,7 @@ public fun Long.coerceAtMost(maximumValue: Long): Long {
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public fun Float.coerceAtMost(maximumValue: Float): Float {
     return if (this > maximumValue) maximumValue else this
@@ -776,6 +782,7 @@ public fun Float.coerceAtMost(maximumValue: Float): Float {
  * Ensures that this value is not greater than the specified [maximumValue].
  * 
  * @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+ * @sample samples.comparisons.ComparableOps.coerceAtMost
  */
 public fun Double.coerceAtMost(maximumValue: Double): Double {
     return if (this > maximumValue) maximumValue else this

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

@@ -58,6 +58,7 @@ object ComparableOps : TemplateGroupBase() {
             Ensures that this value is not greater than the specified [maximumValue].
 
             @return this value if it's less than or equal to the [maximumValue] or the [maximumValue] otherwise.
+            @sample samples.comparisons.ComparableOps.coerceAtMost
             """
         }
         body {