Introduce kotlin-stdlib-generator dsl block for specifying sample reference

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

@@ -704,6 +704,7 @@ public infix fun Short.until(to: Short): IntRange {
  * Ensures that this value is not less than the specified [minimumValue].
  * 
  * @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise.
+ * 
  * @sample samples.comparisons.ComparableOps.coerceAtLeastComparable
  */
 public fun <T: Comparable<T>> T.coerceAtLeast(minimumValue: T): T {
@@ -714,6 +715,7 @@ public fun <T: Comparable<T>> T.coerceAtLeast(minimumValue: T): T {
  * Ensures that this value is not less than the specified [minimumValue].
  * 
  * @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise.
+ * 
  * @sample samples.comparisons.ComparableOps.coerceAtLeast
  */
 public fun Byte.coerceAtLeast(minimumValue: Byte): Byte {
@@ -724,6 +726,7 @@ public fun Byte.coerceAtLeast(minimumValue: Byte): Byte {
  * Ensures that this value is not less than the specified [minimumValue].
  * 
  * @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise.
+ * 
  * @sample samples.comparisons.ComparableOps.coerceAtLeast
  */
 public fun Short.coerceAtLeast(minimumValue: Short): Short {
@@ -734,6 +737,7 @@ public fun Short.coerceAtLeast(minimumValue: Short): Short {
  * Ensures that this value is not less than the specified [minimumValue].
  * 
  * @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise.
+ * 
  * @sample samples.comparisons.ComparableOps.coerceAtLeast
  */
 public fun Int.coerceAtLeast(minimumValue: Int): Int {
@@ -744,6 +748,7 @@ public fun Int.coerceAtLeast(minimumValue: Int): Int {
  * Ensures that this value is not less than the specified [minimumValue].
  * 
  * @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise.
+ * 
  * @sample samples.comparisons.ComparableOps.coerceAtLeast
  */
 public fun Long.coerceAtLeast(minimumValue: Long): Long {
@@ -754,6 +759,7 @@ public fun Long.coerceAtLeast(minimumValue: Long): Long {
  * Ensures that this value is not less than the specified [minimumValue].
  * 
  * @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise.
+ * 
  * @sample samples.comparisons.ComparableOps.coerceAtLeast
  */
 public fun Float.coerceAtLeast(minimumValue: Float): Float {
@@ -764,6 +770,7 @@ public fun Float.coerceAtLeast(minimumValue: Float): Float {
  * Ensures that this value is not less than the specified [minimumValue].
  * 
  * @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise.
+ * 
  * @sample samples.comparisons.ComparableOps.coerceAtLeast
  */
 public fun Double.coerceAtLeast(minimumValue: Double): Double {
@@ -774,6 +781,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.coerceAtMostComparable
  */
 public fun <T: Comparable<T>> T.coerceAtMost(maximumValue: T): T {
@@ -784,6 +792,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 {
@@ -794,6 +803,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 {
@@ -804,6 +814,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 {
@@ -814,6 +825,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 {
@@ -824,6 +836,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 {
@@ -834,6 +847,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 {
@@ -844,6 +858,7 @@ public fun Double.coerceAtMost(maximumValue: Double): Double {
  * Ensures that this value lies in the specified range [minimumValue]..[maximumValue].
  * 
  * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
+ * 
  * @sample samples.comparisons.ComparableOps.coerceInComparable
  */
 public fun <T: Comparable<T>> T.coerceIn(minimumValue: T?, maximumValue: T?): T {
@@ -863,6 +878,7 @@ public fun <T: Comparable<T>> T.coerceIn(minimumValue: T?, maximumValue: T?): T
  * Ensures that this value lies in the specified range [minimumValue]..[maximumValue].
  * 
  * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
+ * 
  * @sample samples.comparisons.ComparableOps.coerceIn
  */
 public fun Byte.coerceIn(minimumValue: Byte, maximumValue: Byte): Byte {
@@ -876,6 +892,7 @@ public fun Byte.coerceIn(minimumValue: Byte, maximumValue: Byte): Byte {
  * Ensures that this value lies in the specified range [minimumValue]..[maximumValue].
  * 
  * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
+ * 
  * @sample samples.comparisons.ComparableOps.coerceIn
  */
 public fun Short.coerceIn(minimumValue: Short, maximumValue: Short): Short {
@@ -889,6 +906,7 @@ public fun Short.coerceIn(minimumValue: Short, maximumValue: Short): Short {
  * Ensures that this value lies in the specified range [minimumValue]..[maximumValue].
  * 
  * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
+ * 
  * @sample samples.comparisons.ComparableOps.coerceIn
  */
 public fun Int.coerceIn(minimumValue: Int, maximumValue: Int): Int {
@@ -902,6 +920,7 @@ public fun Int.coerceIn(minimumValue: Int, maximumValue: Int): Int {
  * Ensures that this value lies in the specified range [minimumValue]..[maximumValue].
  * 
  * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
+ * 
  * @sample samples.comparisons.ComparableOps.coerceIn
  */
 public fun Long.coerceIn(minimumValue: Long, maximumValue: Long): Long {
@@ -915,6 +934,7 @@ public fun Long.coerceIn(minimumValue: Long, maximumValue: Long): Long {
  * Ensures that this value lies in the specified range [minimumValue]..[maximumValue].
  * 
  * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
+ * 
  * @sample samples.comparisons.ComparableOps.coerceIn
  */
 public fun Float.coerceIn(minimumValue: Float, maximumValue: Float): Float {
@@ -928,6 +948,7 @@ public fun Float.coerceIn(minimumValue: Float, maximumValue: Float): Float {
  * Ensures that this value lies in the specified range [minimumValue]..[maximumValue].
  * 
  * @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
+ * 
  * @sample samples.comparisons.ComparableOps.coerceIn
  */
 public fun Double.coerceIn(minimumValue: Double, maximumValue: Double): Double {
@@ -941,6 +962,7 @@ public fun Double.coerceIn(minimumValue: Double, maximumValue: Double): Double {
  * Ensures that this value lies in the specified [range].
  * 
  * @return this value if it's in the [range], or `range.start` if this value is less than `range.start`, or `range.endInclusive` if this value is greater than `range.endInclusive`.
+ * 
  * @sample samples.comparisons.ComparableOps.coerceInFloatingPointRange
  */
 @SinceKotlin("1.1")
@@ -959,6 +981,7 @@ public fun <T: Comparable<T>> T.coerceIn(range: ClosedFloatingPointRange<T>): T
  * Ensures that this value lies in the specified [range].
  * 
  * @return this value if it's in the [range], or `range.start` if this value is less than `range.start`, or `range.endInclusive` if this value is greater than `range.endInclusive`.
+ * 
  * @sample samples.comparisons.ComparableOps.coerceInComparable
  */
 public fun <T: Comparable<T>> T.coerceIn(range: ClosedRange<T>): T {
@@ -977,6 +1000,7 @@ public fun <T: Comparable<T>> T.coerceIn(range: ClosedRange<T>): T {
  * Ensures that this value lies in the specified [range].
  * 
  * @return this value if it's in the [range], or `range.start` if this value is less than `range.start`, or `range.endInclusive` if this value is greater than `range.endInclusive`.
+ * 
  * @sample samples.comparisons.ComparableOps.coerceIn
  */
 public fun Int.coerceIn(range: ClosedRange<Int>): Int {
@@ -995,6 +1019,7 @@ public fun Int.coerceIn(range: ClosedRange<Int>): Int {
  * Ensures that this value lies in the specified [range].
  * 
  * @return this value if it's in the [range], or `range.start` if this value is less than `range.start`, or `range.endInclusive` if this value is greater than `range.endInclusive`.
+ * 
  * @sample samples.comparisons.ComparableOps.coerceIn
  */
 public fun Long.coerceIn(range: ClosedRange<Long>): Long {

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

@@ -332,6 +332,8 @@ public inline fun <T> Sequence<T>.singleOrNull(predicate: (T) -> Boolean): T? {
 
 /**
  * Returns a sequence containing all elements except first [n] elements.
+ * 
+ * @sample samples.collections.Collections.Transformations.drop
  *
  * The operation is _intermediate_ and _stateless_.
  */
@@ -346,6 +348,8 @@ public fun <T> Sequence<T>.drop(n: Int): Sequence<T> {
 
 /**
  * Returns a sequence containing all elements except first elements that satisfy the given [predicate].
+ * 
+ * @sample samples.collections.Collections.Transformations.drop
  *
  * The operation is _intermediate_ and _stateless_.
  */
@@ -459,6 +463,8 @@ public inline fun <T, C : MutableCollection<in T>> Sequence<T>.filterTo(destinat
 
 /**
  * Returns a sequence containing first [n] elements.
+ * 
+ * @sample samples.collections.Collections.Transformations.take
  *
  * The operation is _intermediate_ and _stateless_.
  */
@@ -473,6 +479,8 @@ public fun <T> Sequence<T>.take(n: Int): Sequence<T> {
 
 /**
  * Returns a sequence containing first elements satisfying the given [predicate].
+ * 
+ * @sample samples.collections.Collections.Transformations.take
  *
  * The operation is _intermediate_ and _stateless_.
  */

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

@@ -220,6 +220,8 @@ public inline fun CharSequence.singleOrNull(predicate: (Char) -> Boolean): Char?
 
 /**
  * Returns a subsequence of this char sequence with the first [n] characters removed.
+ * 
+ * @sample samples.collections.Collections.Transformations.drop
  */
 public fun CharSequence.drop(n: Int): CharSequence {
     require(n >= 0) { "Requested character count $n is less than zero." }
@@ -228,6 +230,8 @@ public fun CharSequence.drop(n: Int): CharSequence {
 
 /**
  * Returns a string with the first [n] characters removed.
+ * 
+ * @sample samples.collections.Collections.Transformations.drop
  */
 public fun String.drop(n: Int): String {
     require(n >= 0) { "Requested character count $n is less than zero." }
@@ -236,6 +240,8 @@ public fun String.drop(n: Int): String {
 
 /**
  * Returns a subsequence of this char sequence with the last [n] characters removed.
+ * 
+ * @sample samples.collections.Collections.Transformations.drop
  */
 public fun CharSequence.dropLast(n: Int): CharSequence {
     require(n >= 0) { "Requested character count $n is less than zero." }
@@ -244,6 +250,8 @@ public fun CharSequence.dropLast(n: Int): CharSequence {
 
 /**
  * Returns a string with the last [n] characters removed.
+ * 
+ * @sample samples.collections.Collections.Transformations.drop
  */
 public fun String.dropLast(n: Int): String {
     require(n >= 0) { "Requested character count $n is less than zero." }
@@ -252,6 +260,8 @@ public fun String.dropLast(n: Int): String {
 
 /**
  * Returns a subsequence of this char sequence containing all characters except last characters that satisfy the given [predicate].
+ * 
+ * @sample samples.collections.Collections.Transformations.drop
  */
 public inline fun CharSequence.dropLastWhile(predicate: (Char) -> Boolean): CharSequence {
     for (index in lastIndex downTo 0)
@@ -262,6 +272,8 @@ public inline fun CharSequence.dropLastWhile(predicate: (Char) -> Boolean): Char
 
 /**
  * Returns a string containing all characters except last characters that satisfy the given [predicate].
+ * 
+ * @sample samples.collections.Collections.Transformations.drop
  */
 public inline fun String.dropLastWhile(predicate: (Char) -> Boolean): String {
     for (index in lastIndex downTo 0)
@@ -272,6 +284,8 @@ public inline fun String.dropLastWhile(predicate: (Char) -> Boolean): String {
 
 /**
  * Returns a subsequence of this char sequence containing all characters except first characters that satisfy the given [predicate].
+ * 
+ * @sample samples.collections.Collections.Transformations.drop
  */
 public inline fun CharSequence.dropWhile(predicate: (Char) -> Boolean): CharSequence {
     for (index in this.indices)
@@ -282,6 +296,8 @@ public inline fun CharSequence.dropWhile(predicate: (Char) -> Boolean): CharSequ
 
 /**
  * Returns a string containing all characters except first characters that satisfy the given [predicate].
+ * 
+ * @sample samples.collections.Collections.Transformations.drop
  */
 public inline fun String.dropWhile(predicate: (Char) -> Boolean): String {
     for (index in this.indices)
@@ -406,6 +422,8 @@ public inline fun String.slice(indices: Iterable<Int>): String {
 
 /**
  * Returns a subsequence of this char sequence containing the first [n] characters from this char sequence, or the entire char sequence if this char sequence is shorter.
+ * 
+ * @sample samples.collections.Collections.Transformations.take
  */
 public fun CharSequence.take(n: Int): CharSequence {
     require(n >= 0) { "Requested character count $n is less than zero." }
@@ -414,6 +432,8 @@ public fun CharSequence.take(n: Int): CharSequence {
 
 /**
  * Returns a string containing the first [n] characters from this string, or the entire string if this string is shorter.
+ * 
+ * @sample samples.collections.Collections.Transformations.take
  */
 public fun String.take(n: Int): String {
     require(n >= 0) { "Requested character count $n is less than zero." }
@@ -422,6 +442,8 @@ public fun String.take(n: Int): String {
 
 /**
  * Returns a subsequence of this char sequence containing the last [n] characters from this char sequence, or the entire char sequence if this char sequence is shorter.
+ * 
+ * @sample samples.collections.Collections.Transformations.take
  */
 public fun CharSequence.takeLast(n: Int): CharSequence {
     require(n >= 0) { "Requested character count $n is less than zero." }
@@ -431,6 +453,8 @@ public fun CharSequence.takeLast(n: Int): CharSequence {
 
 /**
  * Returns a string containing the last [n] characters from this string, or the entire string if this string is shorter.
+ * 
+ * @sample samples.collections.Collections.Transformations.take
  */
 public fun String.takeLast(n: Int): String {
     require(n >= 0) { "Requested character count $n is less than zero." }
@@ -440,6 +464,8 @@ public fun String.takeLast(n: Int): String {
 
 /**
  * Returns a subsequence of this char sequence containing last characters that satisfy the given [predicate].
+ * 
+ * @sample samples.collections.Collections.Transformations.take
  */
 public inline fun CharSequence.takeLastWhile(predicate: (Char) -> Boolean): CharSequence {
     for (index in lastIndex downTo 0) {
@@ -452,6 +478,8 @@ public inline fun CharSequence.takeLastWhile(predicate: (Char) -> Boolean): Char
 
 /**
  * Returns a string containing last characters that satisfy the given [predicate].
+ * 
+ * @sample samples.collections.Collections.Transformations.take
  */
 public inline fun String.takeLastWhile(predicate: (Char) -> Boolean): String {
     for (index in lastIndex downTo 0) {
@@ -464,6 +492,8 @@ public inline fun String.takeLastWhile(predicate: (Char) -> Boolean): String {
 
 /**
  * Returns a subsequence of this char sequence containing the first characters that satisfy the given [predicate].
+ * 
+ * @sample samples.collections.Collections.Transformations.take
  */
 public inline fun CharSequence.takeWhile(predicate: (Char) -> Boolean): CharSequence {
     for (index in 0 until length)
@@ -475,6 +505,8 @@ public inline fun CharSequence.takeWhile(predicate: (Char) -> Boolean): CharSequ
 
 /**
  * Returns a string containing the first characters that satisfy the given [predicate].
+ * 
+ * @sample samples.collections.Collections.Transformations.take
  */
 public inline fun String.takeWhile(predicate: (Char) -> Boolean): String {
     for (index in 0 until length)

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

@@ -37,10 +37,9 @@ object Aggregates : TemplateGroupBase() {
         doc {
             """
             Returns `true` if all ${f.element.pluralize()} match the given [predicate].
-
-            @sample samples.collections.Collections.Aggregates.all
             """
         }
+        sample("samples.collections.Collections.Aggregates.all")
         returns("Boolean")
         body {
             """
@@ -64,10 +63,9 @@ object Aggregates : TemplateGroupBase() {
         doc {
             """
             Returns `true` if no ${f.element.pluralize()} match the given [predicate].
-
-            @sample samples.collections.Collections.Aggregates.noneWithPredicate
             """
         }
+        sample("samples.collections.Collections.Aggregates.noneWithPredicate")
         returns("Boolean")
         body {
             """
@@ -89,10 +87,9 @@ object Aggregates : TemplateGroupBase() {
         doc {
             """
             Returns `true` if the ${f.collection} has no ${f.element.pluralize()}.
-
-            @sample samples.collections.Collections.Aggregates.none
             """
         }
+        sample("samples.collections.Collections.Aggregates.none")
         returns("Boolean")
         body {
             "return !iterator().hasNext()"
@@ -119,10 +116,9 @@ object Aggregates : TemplateGroupBase() {
         doc {
             """
             Returns `true` if at least one ${f.element} matches the given [predicate].
-
-            @sample samples.collections.Collections.Aggregates.anyWithPredicate
             """
         }
+        sample("samples.collections.Collections.Aggregates.anyWithPredicate")
         returns("Boolean")
         body {
             """
@@ -144,10 +140,9 @@ object Aggregates : TemplateGroupBase() {
         doc {
             """
             Returns `true` if ${f.collection} has at least one ${f.element}.
-
-            @sample samples.collections.Collections.Aggregates.any
             """
         }
+        sample("samples.collections.Collections.Aggregates.any")
         returns("Boolean")
         body {
             "return iterator().hasNext()"

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

@@ -118,10 +118,9 @@ object ArrayOps : TemplateGroupBase() {
         doc {
             """
             Returns a string representation of the contents of the specified array as if it is [List].
-
-            @sample samples.collections.Arrays.ContentOperations.contentToString
             """
         }
+        sample("samples.collections.Arrays.ContentOperations.contentToString")
         returns("String")
         on(Platform.JVM) {
             inlineOnly()
@@ -144,10 +143,9 @@ object ArrayOps : TemplateGroupBase() {
 
             If any of arrays contains itself on any nesting level that reference
             is rendered as `"[...]"` to prevent recursion.
-
-            @sample samples.collections.Arrays.ContentOperations.contentDeepToString
             """
         }
+        sample("samples.collections.Arrays.ContentOperations.contentDeepToString")
         returns("String")
         on(Platform.JVM) {
             inlineOnly()

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

@@ -36,9 +36,9 @@ object ComparableOps : TemplateGroupBase() {
             Ensures that this value is not less than the specified [minimumValue].
 
             @return this value if it's greater than or equal to the [minimumValue] or the [minimumValue] otherwise.
-            @sample samples.comparisons.ComparableOps.coerceAtLeast${if (f == Generic) "Comparable" else ""}
             """
         }
+        sample("samples.comparisons.ComparableOps.coerceAtLeast${if (f == Generic) "Comparable" else ""}")
         body {
             """
             return if (this < minimumValue) minimumValue else this
@@ -58,9 +58,9 @@ 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${if (f == Generic) "Comparable" else ""}
             """
         }
+        sample("samples.comparisons.ComparableOps.coerceAtMost${if (f == Generic) "Comparable" else ""}")
         body {
             """
             return if (this > maximumValue) maximumValue else this
@@ -80,9 +80,9 @@ object ComparableOps : TemplateGroupBase() {
             Ensures that this value lies in the specified [range].
 
             @return this value if it's in the [range], or `range.start` if this value is less than `range.start`, or `range.endInclusive` if this value is greater than `range.endInclusive`.
-            @sample samples.comparisons.ComparableOps.coerceIn${if (f == Generic) "Comparable" else ""}
             """
         }
+        sample("samples.comparisons.ComparableOps.coerceIn${if (f == Generic) "Comparable" else ""}")
         body(Generic) {
             """
             if (range is ClosedFloatingPointRange) {
@@ -123,9 +123,9 @@ object ComparableOps : TemplateGroupBase() {
             Ensures that this value lies in the specified [range].
 
             @return this value if it's in the [range], or `range.start` if this value is less than `range.start`, or `range.endInclusive` if this value is greater than `range.endInclusive`.
-            @sample samples.comparisons.ComparableOps.coerceInFloatingPointRange
             """
         }
+        sample("samples.comparisons.ComparableOps.coerceInFloatingPointRange")
         body(Generic) {
             """
             if (range.isEmpty()) throw IllegalArgumentException("Cannot coerce value to an empty range: ${'$'}range.")
@@ -384,9 +384,9 @@ object ComparableOps : TemplateGroupBase() {
             Ensures that this value lies in the specified range [minimumValue]..[maximumValue].
 
             @return this value if it's in the range, or [minimumValue] if this value is less than [minimumValue], or [maximumValue] if this value is greater than [maximumValue].
-            @sample samples.comparisons.ComparableOps.coerceIn${if (f == Generic) "Comparable" else ""}
             """
         }
+        sample("samples.comparisons.ComparableOps.coerceIn${if (f == Generic) "Comparable" else ""}")
         body(Primitives) {
             """
             if (minimumValue > maximumValue) throw IllegalArgumentException("Cannot coerce value to an empty range: maximum ${'$'}maximumValue is less than minimum ${'$'}minimumValue.")

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

@@ -51,10 +51,9 @@ object Filtering : TemplateGroupBase() {
         doc { 
             """
             Returns a list containing all elements except first [n] elements.
-
-            @sample samples.collections.Collections.Transformations.drop
             """
         }
+        sample("samples.collections.Collections.Transformations.drop")
         returns("List<T>")
         body {
             """
@@ -138,10 +137,9 @@ object Filtering : TemplateGroupBase() {
         doc { 
             """
             Returns a list containing first [n] elements.
-                        
-            @sample samples.collections.Collections.Transformations.take
             """
         }
+        sample("samples.collections.Collections.Transformations.take")
         returns("List<T>")
         body {
             """
@@ -219,10 +217,9 @@ object Filtering : TemplateGroupBase() {
         doc { 
             """
             Returns a list containing all elements except last [n] elements.
-            
-            @sample samples.collections.Collections.Transformations.drop
             """
         }
+        sample("samples.collections.Collections.Transformations.drop")
         returns("List<T>")
         body {
             """
@@ -249,10 +246,9 @@ object Filtering : TemplateGroupBase() {
         doc { 
             """
             Returns a list containing last [n] elements.
-            
-            @sample samples.collections.Collections.Transformations.take
             """
         }
+        sample("samples.collections.Collections.Transformations.take")
 
         returns("List<T>")
         specialFor(Strings, CharSequences) {
@@ -316,10 +312,9 @@ object Filtering : TemplateGroupBase() {
         doc { 
             """
             Returns a list containing all elements except first elements that satisfy the given [predicate].
-        
-            @sample samples.collections.Collections.Transformations.drop
             """
         }
+        sample("samples.collections.Collections.Transformations.drop")
         returns("List<T>")
         body {
             """
@@ -373,10 +368,9 @@ object Filtering : TemplateGroupBase() {
         doc { 
             """
             Returns a list containing first elements satisfying the given [predicate].
-            
+            """
-            @sample samples.collections.Collections.Transformations.take
-            """ 
         }
+        sample("samples.collections.Collections.Transformations.take")
         returns("List<T>")
         body {
             """
@@ -424,10 +418,9 @@ object Filtering : TemplateGroupBase() {
         doc { 
             """
             Returns a list containing all elements except last elements that satisfy the given [predicate].
-
-            @sample samples.collections.Collections.Transformations.drop
             """
         }
+        sample("samples.collections.Collections.Transformations.drop")
         returns("List<T>")
 
         body {
@@ -481,10 +474,9 @@ object Filtering : TemplateGroupBase() {
         doc { 
             """
             Returns a list containing last elements satisfying the given [predicate].
-                
-            @sample samples.collections.Collections.Transformations.take
             """
         }
+        sample("samples.collections.Collections.Transformations.take")
         returns("List<T>")
 
         body {

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

@@ -631,10 +631,9 @@ object Generators : TemplateGroupBase() {
             @param step the number of elements to move the window forward by on an each step, by default 1
             @param partialWindows controls whether or not to keep partial windows in the end if any,
             by default `false` which means partial windows won't be preserved
-
-            @sample samples.collections.Sequences.Transformations.averageWindows
             """
         }
+        sample("samples.collections.Sequences.Transformations.averageWindows")
 
         typeParam("R")
         returns("List<R>")
@@ -711,10 +710,9 @@ object Generators : TemplateGroupBase() {
             @param step the number of elements to move the window forward by on an each step, by default 1
             @param partialWindows controls whether or not to keep partial windows in the end if any,
             by default `false` which means partial windows won't be preserved
-
-            @sample samples.collections.Sequences.Transformations.takeWindows
             """
         }
+        sample("samples.collections.Sequences.Transformations.takeWindows")
 
         body {
             """
@@ -765,10 +763,9 @@ object Generators : TemplateGroupBase() {
             @param step the number of elements to move the window forward by on an each step, by default 1
             @param partialWindows controls whether or not to keep partial windows in the end if any,
             by default `false` which means partial windows won't be preserved
-
-            @sample samples.collections.Sequences.Transformations.averageWindows
             """
         }
+        sample("samples.collections.Sequences.Transformations.averageWindows")
         typeParam("R")
         returns("Sequence<R>")
 
@@ -798,10 +795,9 @@ object Generators : TemplateGroupBase() {
             @param step the number of elements to move the window forward by on an each step, by default 1
             @param partialWindows controls whether or not to keep partial windows in the end if any,
             by default `false` which means partial windows won't be preserved
-
-            @sample samples.collections.Sequences.Transformations.takeWindows
             """
         }
+        sample("samples.collections.Sequences.Transformations.takeWindows")
         returns("Sequence<String>")
 
         body(CharSequences) { "return windowedSequence(size, step, partialWindows) { it.toString() }" }
@@ -823,10 +819,9 @@ object Generators : TemplateGroupBase() {
             The last ${f.viewResult} may have less ${f.element.pluralize()} than the given [size].
 
             @param size the number of elements to take in each ${f.viewResult}, must be positive and can be greater than the number of elements in this ${f.collection}.
-
-            @sample samples.text.Strings.chunkedTransform
             """
         }
+        sample("samples.text.Strings.chunkedTransform")
 
         typeParam("R")
         returns("List<R>")
@@ -851,10 +846,9 @@ object Generators : TemplateGroupBase() {
             The last ${f.snapshotResult} in the resulting ${f.mapResult} may have less ${f.element.pluralize()} than the given [size].
 
             @param size the number of elements to take in each ${f.snapshotResult}, must be positive and can be greater than the number of elements in this ${f.collection}.
-
-            @sample samples.collections.Collections.Transformations.chunked
             """
         }
+        sample("samples.collections.Collections.Transformations.chunked")
         specialFor(Iterables) { returns("List<List<T>>") }
         specialFor(Sequences) { returns("Sequence<List<T>>") }
         specialFor(CharSequences) { returns("List<String>") }
@@ -880,10 +874,9 @@ object Generators : TemplateGroupBase() {
             The last ${f.viewResult} may have less ${f.element.pluralize()} than the given [size].
 
             @param size the number of elements to take in each ${f.viewResult}, must be positive and can be greater than the number of elements in this ${f.collection}.
-
-            @sample samples.text.Strings.chunkedTransformToSequence
             """
         }
+        sample("samples.text.Strings.chunkedTransformToSequence")
 
         typeParam("R")
         returns("Sequence<R>")
@@ -906,10 +899,9 @@ object Generators : TemplateGroupBase() {
             The last ${f.snapshotResult} in the resulting sequence may have less ${f.element.pluralize()} than the given [size].
 
             @param size the number of elements to take in each ${f.snapshotResult}, must be positive and can be greater than the number of elements in this ${f.collection}.
-
-            @sample samples.collections.Collections.Transformations.chunked
             """
         }
+        sample("samples.collections.Collections.Transformations.chunked")
         returns("Sequence<String>")
 
         body(CharSequences) { "return chunkedSequence(size) { it.toString() }" }
@@ -926,10 +918,9 @@ object Generators : TemplateGroupBase() {
             to an each pair of two adjacent ${f.element.pluralize()} in this ${f.collection}.
 
             The returned ${f.mapResult} is empty if this ${f.collection} contains less than two ${f.element.pluralize()}.
-
-            @sample samples.collections.Collections.Transformations.zipWithNextToFindDeltas
             """
         }
+        sample("samples.collections.Collections.Transformations.zipWithNextToFindDeltas")
         returns("List<R>")
         inline()
         body {
@@ -988,10 +979,9 @@ object Generators : TemplateGroupBase() {
             Returns a ${f.mapResult} of pairs of each two adjacent ${f.element.pluralize()} in this ${f.collection}.
 
             The returned ${f.mapResult} is empty if this ${f.collection} contains less than two ${f.element.pluralize()}.
-
-            @sample samples.collections.Collections.Transformations.zipWithNext
             """
         }
+        sample("samples.collections.Collections.Transformations.zipWithNext")
         sequenceClassification(intermediate, stateless)
         specialFor(Sequences) { returns("Sequence<Pair<T, T>>") }
         body {
@@ -1007,10 +997,9 @@ object Generators : TemplateGroupBase() {
             Returns a list of values built from the elements of `this` ${f.collection} and the [other] collection with the same index
             using the provided [transform] function applied to each pair of elements.
             The returned list has length of the shortest collection.
-
-            @sample samples.collections.Iterables.Operations.zipIterableWithTransform
             """
         }
+        sample("samples.collections.Iterables.Operations.zipIterableWithTransform")
         typeParam("R")
         typeParam("V")
         returns("List<V>")
@@ -1048,10 +1037,9 @@ object Generators : TemplateGroupBase() {
             Returns a list of values built from the elements of `this` ${f.collection} and the [other] array with the same index
             using the provided [transform] function applied to each pair of elements.
             The returned list has length of the shortest collection.
-
-            @sample samples.collections.Iterables.Operations.zipIterableWithTransform
             """
         }
+        sample("samples.collections.Iterables.Operations.zipIterableWithTransform")
         typeParam("R")
         typeParam("V")
         returns("List<V>")
@@ -1089,10 +1077,9 @@ object Generators : TemplateGroupBase() {
             Returns a list of values built from the elements of `this` array and the [other] array with the same index
             using the provided [transform] function applied to each pair of elements.
             The returned list has length of the shortest array.
-
-            @sample samples.collections.Iterables.Operations.zipIterableWithTransform
             """
         }
+        sample("samples.collections.Iterables.Operations.zipIterableWithTransform")
         typeParam("V")
         returns("List<V>")
         inline()
@@ -1116,10 +1103,9 @@ object Generators : TemplateGroupBase() {
             Returns a sequence of values built from the elements of `this` sequence and the [other] sequence with the same index
             using the provided [transform] function applied to each pair of elements.
             The resulting sequence ends as soon as the shortest input sequence ends.
-
-            @sample samples.collections.Sequences.Transformations.zipWithTransform
             """
         }
+        sample("samples.collections.Sequences.Transformations.zipWithTransform")
         sequenceClassification(intermediate, stateless)
         typeParam("R")
         typeParam("V")
@@ -1139,10 +1125,9 @@ object Generators : TemplateGroupBase() {
             Returns a list of values built from the characters of `this` and the [other] char sequences with the same index
             using the provided [transform] function applied to each pair of characters.
             The returned list has length of the shortest char sequence.
-
-            @sample samples.text.Strings.zipWithTransform
             """
         }
+        sample("samples.text.Strings.zipWithTransform")
         typeParam("V")
         returns("List<V>")
         inline()
@@ -1168,10 +1153,9 @@ object Generators : TemplateGroupBase() {
             """
             Returns a list of pairs built from the elements of `this` collection and [other] ${f.collection} with the same index.
             The returned list has length of the shortest collection.
-
-            @sample samples.collections.Iterables.Operations.zipIterable
             """
         }
+        sample("samples.collections.Iterables.Operations.zipIterable")
         typeParam("R")
         returns("List<Pair<T, R>>")
         body {
@@ -1189,10 +1173,9 @@ object Generators : TemplateGroupBase() {
             """
             Returns a list of pairs built from the characters of `this` and the [other] char sequences with the same index
             The returned list has length of the shortest char sequence.
-
-            @sample samples.text.Strings.zip
             """
         }
+        sample("samples.text.Strings.zip")
         returns("List<Pair<Char, Char>>")
         body {
             """
@@ -1209,10 +1192,9 @@ object Generators : TemplateGroupBase() {
             """
             Returns a list of pairs built from the elements of `this` ${f.collection} and the [other] array with the same index.
             The returned list has length of the shortest collection.
-
-            @sample samples.collections.Iterables.Operations.zipIterable
             """
         }
+        sample("samples.collections.Iterables.Operations.zipIterable")
         typeParam("R")
         returns("List<Pair<T, R>>")
         body {
@@ -1230,10 +1212,9 @@ object Generators : TemplateGroupBase() {
             """
             Returns a list of pairs built from the elements of `this` array and the [other] array with the same index.
             The returned list has length of the shortest collection.
-
-            @sample samples.collections.Iterables.Operations.zipIterable
             """
         }
+        sample("samples.collections.Iterables.Operations.zipIterable")
         returns("List<Pair<T, T>>")
         body {
             """
@@ -1250,10 +1231,9 @@ object Generators : TemplateGroupBase() {
             """
             Returns a sequence of values built from the elements of `this` sequence and the [other] sequence with the same index.
             The resulting sequence ends as soon as the shortest input sequence ends.
-
-            @sample samples.collections.Sequences.Transformations.zip
             """
         }
+        sample("samples.collections.Sequences.Transformations.zip")
         sequenceClassification(intermediate, stateless)
         typeParam("R")
         returns("Sequence<Pair<T, R>>")

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

@@ -326,10 +326,9 @@ object Mapping : TemplateGroupBase() {
             applied to each ${f.element} and returns a map where each group key is associated with a list of corresponding ${f.element.pluralize()}.
 
             The returned map preserves the entry iteration order of the keys produced from the original ${f.collection}.
-
-            @sample samples.collections.Collections.Transformations.groupBy
             """
         }
+        sample("samples.collections.Collections.Transformations.groupBy")
         sequenceClassification(terminal)
         typeParam("K")
         returns("Map<K, List<T>>")
@@ -350,10 +349,9 @@ object Mapping : TemplateGroupBase() {
             applied to each ${f.element} and puts to the [destination] map each group key associated with a list of corresponding ${f.element.pluralize()}.
 
             @return The [destination] map.
-
-            @sample samples.collections.Collections.Transformations.groupBy
             """
         }
+        sample("samples.collections.Collections.Transformations.groupBy")
         sequenceClassification(terminal)
         returns("M")
         body {
@@ -380,10 +378,9 @@ object Mapping : TemplateGroupBase() {
             and returns a map where each group key is associated with a list of corresponding values.
 
             The returned map preserves the entry iteration order of the keys produced from the original ${f.collection}.
-
-            @sample samples.collections.Collections.Transformations.groupByKeysAndValues
             """
         }
+        sample("samples.collections.Collections.Transformations.groupByKeysAndValues")
         sequenceClassification(terminal)
         typeParam("K")
         typeParam("V")
@@ -408,10 +405,9 @@ object Mapping : TemplateGroupBase() {
             and puts to the [destination] map each group key associated with a list of corresponding values.
 
             @return The [destination] map.
-
-            @sample samples.collections.Collections.Transformations.groupByKeysAndValues
             """
         }
+        sample("samples.collections.Collections.Transformations.groupByKeysAndValues")
         sequenceClassification(terminal)
         returns("M")
         body {
@@ -441,10 +437,9 @@ object Mapping : TemplateGroupBase() {
             """
             Creates a [Grouping] source from ${f.collection.prefixWithArticle()} to be used later with one of group-and-fold operations
             using the specified [keySelector] function to extract a key from each ${f.element}.
-
-            @sample samples.collections.Collections.Transformations.groupingByEachCount
             """
         }
+        sample("samples.collections.Collections.Transformations.groupingByEachCount")
 
         body {
             """

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

@@ -52,10 +52,11 @@ object SequenceOps : TemplateGroupBase() {
         doc {
             """
             Creates a [Sequence] instance that wraps the original ${f.collection} returning its ${f.element.pluralize()} when being iterated.
-
-            ${if (f in listOf(ArraysOfPrimitives, ArraysOfObjects, Iterables)) "@sample samples.collections.Sequences.Building.sequenceFrom${f.doc.collection.capitalize()}" else ""}
             """
         }
+        if (f in listOf(ArraysOfPrimitives, ArraysOfObjects, Iterables))
+            sample("samples.collections.Sequences.Building.sequenceFrom${f.doc.collection.capitalize()}")
+
         returns("Sequence<T>")
         body {
             """

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

@@ -30,10 +30,9 @@ object StringJoinOps : TemplateGroupBase() {
 
             If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit]
             elements will be appended, followed by the [truncated] string (which defaults to "...").
-            
-            @sample samples.collections.Collections.Transformations.joinTo
             """
         }
+        sample("samples.collections.Collections.Transformations.joinTo")
         sequenceClassification(terminal)
         typeParam("A : Appendable")
         returns("A")
@@ -81,10 +80,9 @@ object StringJoinOps : TemplateGroupBase() {
 
             If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit]
             elements will be appended, followed by the [truncated] string (which defaults to "...").
-            
-            @sample samples.collections.Collections.Transformations.joinToString
             """
         }
+        sample("samples.collections.Collections.Transformations.joinToString")
         sequenceClassification(terminal)
 
         returns("String")

libraries/tools/kotlin-stdlib-gen/src/templates/dsl/MemberBuilder.kt

@@ -55,6 +55,8 @@ class MemberBuilder(
 
     var doc: String? = null; private set
 
+    val samples = mutableListOf<String>()
+
     val sequenceClassification = mutableListOf<SequenceClass>()
     var deprecate: Deprecation? = null; private set
     var since: String? = null; private set
@@ -129,6 +131,10 @@ class MemberBuilder(
     @Deprecated("Use specialFor", ReplaceWith("specialFor(*fs) { doc(valueBuilder) }"))
     fun doc(vararg fs: Family, valueBuilder: DocExtensions.() -> String) = specialFor(*fs) { doc(valueBuilder) }
 
+    fun sample(sampleRef: String) {
+        samples += sampleRef
+    }
+
     fun body(valueBuilder: () -> String) {
         body = valueBuilder()
     }
@@ -299,6 +305,10 @@ class MemberBuilder(
             StringReader(methodDoc.trim()).forEachLine { line ->
                 builder.append(" * ").append(line.trim()).append("\n")
             }
+            if (samples.any()) {
+                builder.append(" * \n")
+                samples.forEach { builder.append(" * @sample $it\n")}
+            }
             if (family == Sequences && sequenceClassification.isNotEmpty()) {
                 builder.append(" *\n")
                 builder.append(" * The operation is ${sequenceClassification.joinToString(" and ") { "_${it}_" }}.\n")