diff --git a/libraries/stdlib/common/src/generated/_Ranges.kt b/libraries/stdlib/common/src/generated/_Ranges.kt index 793d5b42e35..c152fc14dc4 100644 --- a/libraries/stdlib/common/src/generated/_Ranges.kt +++ b/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.coerceAtLeast(minimumValue: T): T { @@ -714,6 +715,7 @@ public fun > 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.coerceAtMost(maximumValue: T): T { @@ -784,6 +792,7 @@ public fun > 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.coerceIn(minimumValue: T?, maximumValue: T?): T { @@ -863,6 +878,7 @@ public fun > 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.coerceIn(range: ClosedFloatingPointRange): 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.coerceIn(range: ClosedRange): T { @@ -977,6 +1000,7 @@ public fun > T.coerceIn(range: ClosedRange): 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 { @@ -995,6 +1019,7 @@ public fun Int.coerceIn(range: ClosedRange): 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 { diff --git a/libraries/stdlib/common/src/generated/_Sequences.kt b/libraries/stdlib/common/src/generated/_Sequences.kt index 8d202f4bf06..c90be378ef3 100644 --- a/libraries/stdlib/common/src/generated/_Sequences.kt +++ b/libraries/stdlib/common/src/generated/_Sequences.kt @@ -332,6 +332,8 @@ public inline fun Sequence.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 Sequence.drop(n: Int): Sequence { /** * 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 > Sequence.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 Sequence.take(n: Int): Sequence { /** * Returns a sequence containing first elements satisfying the given [predicate]. + * + * @sample samples.collections.Collections.Transformations.take * * The operation is _intermediate_ and _stateless_. */ diff --git a/libraries/stdlib/common/src/generated/_Strings.kt b/libraries/stdlib/common/src/generated/_Strings.kt index 627783d2893..529d0c9fa70 100644 --- a/libraries/stdlib/common/src/generated/_Strings.kt +++ b/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): 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) diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt index b7c9db29200..2e3977db19b 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt +++ b/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()" diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt index fee892d1894..3caa3811964 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt +++ b/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() diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Comparables.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Comparables.kt index 3d73375fc2a..64a8a1cb1d5 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Comparables.kt +++ b/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.") diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Filtering.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Filtering.kt index e1df9ded2dc..febaaa6fa44 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Filtering.kt +++ b/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") 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") 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") 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") 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") 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") 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") 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") body { diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt index bb19898982e..e56d53fe641 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt +++ b/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") @@ -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") @@ -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") 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") @@ -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>") } specialFor(Sequences) { returns("Sequence>") } specialFor(CharSequences) { returns("List") } @@ -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") @@ -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") 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") 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>") } 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") @@ -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") @@ -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") 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") 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>") 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>") 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>") 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>") 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>") diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt index 85063c2b44a..ffe522edfd9 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt +++ b/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>") @@ -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 { """ diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Sequence.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Sequence.kt index a1e5a039569..5289fb6a823 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Sequence.kt +++ b/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") body { """ diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Strings.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Strings.kt index 74b2e06737c..10fc58bdb59 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Strings.kt +++ b/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") diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/dsl/MemberBuilder.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/dsl/MemberBuilder.kt index 4b270a34ed1..84f9141321c 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/dsl/MemberBuilder.kt +++ b/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() + val sequenceClassification = mutableListOf() 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")