Rework existing unit tests used as samples.

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

@@ -0,0 +1,62 @@
+/*
+ * Copyright 2010-2016 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package samples.collections
+
+import samples.*
+import kotlin.test.*
+import java.util.*
+
+
+@RunWith(Enclosed::class)
+class Collections {
+
+    class Lists {
+        @Sample
+        fun lastIndexOfList() {
+            assertPrints(emptyList<Any>().lastIndex, "-1")
+            assertPrints(listOf("a", "x", "y").lastIndex, "2")
+        }
+    }
+
+    class Transformations {
+
+        @Sample
+        fun groupBy() {
+            val words = listOf("a", "abc", "ab", "def", "abcd")
+            val byLength = words.groupBy { it.length }
+
+            assertPrints(byLength.keys, "[1, 3, 2, 4]")
+            assertPrints(byLength.values, "[[a], [abc, def], [ab], [abcd]]")
+
+            val mutableByLength: MutableMap<Int, MutableList<String>> = words.groupByTo(mutableMapOf()) { it.length }
+            // same content as in byLength map, but the map is mutable
+            assertTrue(mutableByLength == byLength)
+        }
+
+        @Sample
+        fun groupByKeysAndValues() {
+            val nameToTeam = listOf("Alice" to "Marketing", "Bob" to "Sales", "Carol" to "Marketing")
+            val namesByTeam = nameToTeam.groupBy({ it.second }, { it.first })
+            assertPrints(namesByTeam, "{Marketing=[Alice, Carol], Sales=[Bob]}")
+
+            val mutableNamesByTeam = nameToTeam.groupByTo(HashMap(), { it.second }, { it.first })
+            // same content as in namesByTeam map, but the map is mutable
+            assertTrue(mutableNamesByTeam == namesByTeam)
+        }
+    }
+
+}

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

@@ -0,0 +1,156 @@
+package samples.collections
+
+import samples.*
+import kotlin.test.*
+import java.util.*
+import kotlin.comparisons.*
+
+@RunWith(Enclosed::class)
+class Maps {
+
+    class Instantiation {
+
+        @Sample
+        fun mapFromPairs() {
+            val map = mapOf(1 to "x", 2 to "y", -1 to "zz")
+            assertPrints(map, "{1=x, 2=y, -1=zz}")
+        }
+
+        @Sample
+        fun mutableMapFromPairs() {
+            val map = mutableMapOf(1 to "x", 2 to "y", -1 to "zz")
+            assertPrints(map, "{1=x, 2=y, -1=zz}")
+
+            map[1] = "a"
+            assertPrints(map, "{1=a, 2=y, -1=zz}")
+        }
+
+        @Sample
+        fun hashMapFromPairs() {
+            val map: HashMap<Int, String> = hashMapOf(1 to "x", 2 to "y", -1 to "zz")
+            assertPrints(map, "{-1=zz, 1=x, 2=y}")
+        }
+
+        @Sample
+        fun linkedMapFromPairs() {
+            val map: LinkedHashMap<Int, String> = linkedMapOf(1 to "x", 2 to "y", -1 to "zz")
+            assertPrints(map, "{1=x, 2=y, -1=zz}")
+        }
+
+        @Sample
+        fun sortedMapFromPairs() {
+            val map = sortedMapOf(Pair("c", 3), Pair("b", 2), Pair("d", 1))
+            assertPrints(map.keys, "[b, c, d]")
+            assertPrints(map.values, "[2, 3, 1]")
+        }
+
+        @Sample
+        fun emptyReadOnlyMap() {
+            val map = emptyMap<String, Int>()
+            assertTrue(map.isEmpty())
+
+            val anotherMap = mapOf<String, Int>()
+            assertTrue(map == anotherMap, "Empty maps are equal")
+        }
+
+        @Sample
+        fun emptyMutableMap() {
+            val map = mutableMapOf<Int, Any?>()
+            assertTrue(map.isEmpty())
+
+            map[1] = "x"
+            map[2] = 1.05
+            // Now map contains something:
+            assertPrints(map, "{1=x, 2=1.05}")
+        }
+
+    }
+
+
+    class Usage {
+
+        @Sample
+        fun getOrElse() {
+            val map = mutableMapOf<String, Int?>()
+            assertPrints(map.getOrElse("x") { 1 }, "1")
+
+            map["x"] = 3
+            assertPrints(map.getOrElse("x") { 1 }, "3")
+
+            map["x"] = null
+            assertPrints(map.getOrElse("x") { 1 }, "1")
+        }
+
+        @Sample
+        fun getOrPut() {
+            val map = mutableMapOf<String, Int?>()
+            assertPrints(map.getOrPut("x") { 2 }, "2")
+            assertPrints(map.getOrPut("x") { 3 }, "2") // still
+
+            assertPrints(map.getOrPut("y") { null }, "null")
+            assertPrints(map.getOrPut("y") { 42 }, "42") // but!
+        }
+
+        @Sample
+        fun forOverEntries() {
+            val map = mapOf("beverage" to 2.7, "meal" to 12.4, "dessert" to 5.8)
+
+            for ((key, value) in map) {
+                println("$key - $value") // prints: beverage - 2.7
+                                         // prints: meal - 12.4
+                                         // prints: dessert - 5.8
+            }
+
+        }
+    }
+
+    class Transformations {
+
+        @Sample
+        fun mapKeys() {
+            val map1 = mapOf("beer" to 2.7, "bisquit" to 5.8)
+            val map2 = map1.mapKeys { it.key.length }
+            assertPrints(map2, "{4=2.7, 7=5.8}")
+
+            val map3 = map1.mapKeys { it.key.take(1) }
+            assertPrints(map3, "{b=5.8}")
+        }
+
+        @Sample
+        fun mapValues() {
+            val map1 = mapOf("beverage" to 2.7, "meal" to 12.4)
+            val map2 = map1.mapValues { it.value.toString() + "$" }
+
+            assertPrints(map2, "{beverage=2.7$, meal=12.4$}")
+        }
+
+
+        @Sample
+        fun mapToSortedMap() {
+            val map = mapOf(Pair("c", 3), Pair("b", 2), Pair("d", 1))
+            val sorted = map.toSortedMap()
+            assertPrints(sorted.keys, "[b, c, d]")
+            assertPrints(sorted.values, "[2, 3, 1]")
+        }
+
+        @Sample
+        fun mapToSortedMapWithComparator() {
+            val map = mapOf(Pair("abc", 1), Pair("c", 3), Pair("bd", 4), Pair("bc", 2))
+            val sorted = map.toSortedMap(compareBy<String> { it.length }.thenBy { it })
+            assertPrints(sorted.keys, "[c, bc, bd, abc]")
+        }
+
+        @Sample
+        fun mapToProperties() {
+            val map = mapOf("x" to "value A", "y" to "value B")
+            val props = map.toProperties()
+
+            assertPrints(props.getProperty("x"), "value A")
+            assertPrints(props.getProperty("y", "fail"), "value B")
+            assertPrints(props.getProperty("z", "fail"), "fail")
+        }
+
+    }
+
+}
+

libraries/stdlib/samples/test/samples/misc/preconditions.kt

@@ -0,0 +1,55 @@
+package samples.misc
+
+import samples.*
+import kotlin.test.*
+
+class Preconditions {
+
+    @Sample
+    fun failWithError() {
+        val name: String? = null
+
+        val exception = assertFailsWith<IllegalStateException> {
+            val nonNullName = name ?: error("Name is missing")
+        }
+
+        assertPrints(exception.message, "Name is missing")
+    }
+
+    @Sample
+    fun failRequireWithLazyMessage() {
+
+        fun getIndices(count: Int) {
+            require(count >= 0) { "Count must be non-negative, was $count" }
+            // ...
+        }
+
+        val exception = assertFailsWith<IllegalArgumentException> {
+            getIndices(-1)
+        }
+        assertPrints(exception.message, "Count must be non-negative, was -1")
+    }
+
+    @Sample
+    fun failCheckWithLazyMessage() {
+
+        var someState: String? = null
+        fun getStateValue(): String {
+            val state = checkNotNull(someState) { "State must be set beforehand" }
+            check(state.isNotEmpty()) { "State must be non-empty" }
+            // ...
+            return state
+        }
+
+        assertFailsWith<IllegalStateException> {
+            getStateValue()
+        }
+
+        assertFailsWith<IllegalStateException> {
+            someState = ""
+            getStateValue()
+        }.let { exception ->
+            assertPrints(exception.message, "State must be non-empty")
+        }
+    }
+}

libraries/stdlib/samples/test/samples/misc/tuples.kt

@@ -0,0 +1,23 @@
+package samples.misc
+
+import samples.*
+import kotlin.test.*
+
+class Tuples {
+
+    @Sample
+    fun pairDestructuring() {
+        val (a, b) = Pair(1, "x")
+        assertPrints(a, "1")
+        assertPrints(b, "x")
+    }
+
+    @Sample
+    fun tripleDestructuring() {
+        val (a, b, c) = Triple(2, "x", listOf(null))
+        assertPrints(a, "2")
+        assertPrints(b, "x")
+        assertPrints(c, "[null]")
+    }
+
+}

libraries/stdlib/samples/test/samples/text/regex.kt

@@ -0,0 +1,23 @@
+package samples.text
+
+import samples.*
+import kotlin.test.*
+import java.util.*
+
+class Regexps {
+
+    @Sample
+    fun matchDestructuringToGroupValues() {
+        val inputString = "John 9731879"
+        val match = Regex("(\\w+) (\\d+)").find(inputString)!!
+        val (name, phone) = match.destructured
+
+        assertPrints(name, "John")
+        assertPrints(phone, "9731879")
+
+        assertPrints(match.groupValues, "[John 9731879, John, 9731879]")
+
+        val numberedGroupValues = match.destructured.toList()
+        assertPrints(numberedGroupValues, "[John, 9731879]")
+    }
+}

libraries/stdlib/samples/test/samples/text/strings.kt

@@ -0,0 +1,27 @@
+package samples.text
+
+import samples.*
+import kotlin.test.*
+import java.util.*
+
+class Strings {
+
+    @Sample
+    fun capitalize() {
+        assertPrints("abcd".capitalize(), "Abcd")
+        assertPrints("Abcd".capitalize(), "Abcd")
+    }
+
+    @Sample
+    fun decaptialize() {
+        assertPrints("abcd".decapitalize(), "abcd")
+        assertPrints("Abcd".decapitalize(), "abcd")
+    }
+
+    @Sample
+    fun repeat() {
+        assertPrints("Word".repeat(4), "WordWordWordWord")
+        assertPrints("Word".repeat(0), "")
+    }
+
+}

libraries/stdlib/src/generated/_Arrays.kt

@@ -7235,7 +7235,7 @@ public inline fun <R, C : MutableCollection<in R>> CharArray.flatMapTo(destinati
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <T, K> Array<out T>.groupBy(keySelector: (T) -> K): Map<K, List<T>> {
     return groupByTo(LinkedHashMap<K, MutableList<T>>(), keySelector)
@@ -7247,7 +7247,7 @@ public inline fun <T, K> Array<out T>.groupBy(keySelector: (T) -> K): Map<K, Lis
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K> ByteArray.groupBy(keySelector: (Byte) -> K): Map<K, List<Byte>> {
     return groupByTo(LinkedHashMap<K, MutableList<Byte>>(), keySelector)
@@ -7259,7 +7259,7 @@ public inline fun <K> ByteArray.groupBy(keySelector: (Byte) -> K): Map<K, List<B
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K> ShortArray.groupBy(keySelector: (Short) -> K): Map<K, List<Short>> {
     return groupByTo(LinkedHashMap<K, MutableList<Short>>(), keySelector)
@@ -7271,7 +7271,7 @@ public inline fun <K> ShortArray.groupBy(keySelector: (Short) -> K): Map<K, List
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K> IntArray.groupBy(keySelector: (Int) -> K): Map<K, List<Int>> {
     return groupByTo(LinkedHashMap<K, MutableList<Int>>(), keySelector)
@@ -7283,7 +7283,7 @@ public inline fun <K> IntArray.groupBy(keySelector: (Int) -> K): Map<K, List<Int
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K> LongArray.groupBy(keySelector: (Long) -> K): Map<K, List<Long>> {
     return groupByTo(LinkedHashMap<K, MutableList<Long>>(), keySelector)
@@ -7295,7 +7295,7 @@ public inline fun <K> LongArray.groupBy(keySelector: (Long) -> K): Map<K, List<L
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K> FloatArray.groupBy(keySelector: (Float) -> K): Map<K, List<Float>> {
     return groupByTo(LinkedHashMap<K, MutableList<Float>>(), keySelector)
@@ -7307,7 +7307,7 @@ public inline fun <K> FloatArray.groupBy(keySelector: (Float) -> K): Map<K, List
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K> DoubleArray.groupBy(keySelector: (Double) -> K): Map<K, List<Double>> {
     return groupByTo(LinkedHashMap<K, MutableList<Double>>(), keySelector)
@@ -7319,7 +7319,7 @@ public inline fun <K> DoubleArray.groupBy(keySelector: (Double) -> K): Map<K, Li
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K> BooleanArray.groupBy(keySelector: (Boolean) -> K): Map<K, List<Boolean>> {
     return groupByTo(LinkedHashMap<K, MutableList<Boolean>>(), keySelector)
@@ -7331,7 +7331,7 @@ public inline fun <K> BooleanArray.groupBy(keySelector: (Boolean) -> K): Map<K,
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K> CharArray.groupBy(keySelector: (Char) -> K): Map<K, List<Char>> {
     return groupByTo(LinkedHashMap<K, MutableList<Char>>(), keySelector)
@@ -7344,7 +7344,7 @@ public inline fun <K> CharArray.groupBy(keySelector: (Char) -> K): Map<K, List<C
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <T, K, V> Array<out T>.groupBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map<K, List<V>> {
     return groupByTo(LinkedHashMap<K, MutableList<V>>(), keySelector, valueTransform)
@@ -7357,7 +7357,7 @@ public inline fun <T, K, V> Array<out T>.groupBy(keySelector: (T) -> K, valueTra
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V> ByteArray.groupBy(keySelector: (Byte) -> K, valueTransform: (Byte) -> V): Map<K, List<V>> {
     return groupByTo(LinkedHashMap<K, MutableList<V>>(), keySelector, valueTransform)
@@ -7370,7 +7370,7 @@ public inline fun <K, V> ByteArray.groupBy(keySelector: (Byte) -> K, valueTransf
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V> ShortArray.groupBy(keySelector: (Short) -> K, valueTransform: (Short) -> V): Map<K, List<V>> {
     return groupByTo(LinkedHashMap<K, MutableList<V>>(), keySelector, valueTransform)
@@ -7383,7 +7383,7 @@ public inline fun <K, V> ShortArray.groupBy(keySelector: (Short) -> K, valueTran
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V> IntArray.groupBy(keySelector: (Int) -> K, valueTransform: (Int) -> V): Map<K, List<V>> {
     return groupByTo(LinkedHashMap<K, MutableList<V>>(), keySelector, valueTransform)
@@ -7396,7 +7396,7 @@ public inline fun <K, V> IntArray.groupBy(keySelector: (Int) -> K, valueTransfor
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V> LongArray.groupBy(keySelector: (Long) -> K, valueTransform: (Long) -> V): Map<K, List<V>> {
     return groupByTo(LinkedHashMap<K, MutableList<V>>(), keySelector, valueTransform)
@@ -7409,7 +7409,7 @@ public inline fun <K, V> LongArray.groupBy(keySelector: (Long) -> K, valueTransf
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V> FloatArray.groupBy(keySelector: (Float) -> K, valueTransform: (Float) -> V): Map<K, List<V>> {
     return groupByTo(LinkedHashMap<K, MutableList<V>>(), keySelector, valueTransform)
@@ -7422,7 +7422,7 @@ public inline fun <K, V> FloatArray.groupBy(keySelector: (Float) -> K, valueTran
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V> DoubleArray.groupBy(keySelector: (Double) -> K, valueTransform: (Double) -> V): Map<K, List<V>> {
     return groupByTo(LinkedHashMap<K, MutableList<V>>(), keySelector, valueTransform)
@@ -7435,7 +7435,7 @@ public inline fun <K, V> DoubleArray.groupBy(keySelector: (Double) -> K, valueTr
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V> BooleanArray.groupBy(keySelector: (Boolean) -> K, valueTransform: (Boolean) -> V): Map<K, List<V>> {
     return groupByTo(LinkedHashMap<K, MutableList<V>>(), keySelector, valueTransform)
@@ -7448,7 +7448,7 @@ public inline fun <K, V> BooleanArray.groupBy(keySelector: (Boolean) -> K, value
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original array.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V> CharArray.groupBy(keySelector: (Char) -> K, valueTransform: (Char) -> V): Map<K, List<V>> {
     return groupByTo(LinkedHashMap<K, MutableList<V>>(), keySelector, valueTransform)
@@ -7460,7 +7460,7 @@ public inline fun <K, V> CharArray.groupBy(keySelector: (Char) -> K, valueTransf
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <T, K, M : MutableMap<in K, MutableList<T>>> Array<out T>.groupByTo(destination: M, keySelector: (T) -> K): M {
     for (element in this) {
@@ -7477,7 +7477,7 @@ public inline fun <T, K, M : MutableMap<in K, MutableList<T>>> Array<out T>.grou
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K, M : MutableMap<in K, MutableList<Byte>>> ByteArray.groupByTo(destination: M, keySelector: (Byte) -> K): M {
     for (element in this) {
@@ -7494,7 +7494,7 @@ public inline fun <K, M : MutableMap<in K, MutableList<Byte>>> ByteArray.groupBy
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K, M : MutableMap<in K, MutableList<Short>>> ShortArray.groupByTo(destination: M, keySelector: (Short) -> K): M {
     for (element in this) {
@@ -7511,7 +7511,7 @@ public inline fun <K, M : MutableMap<in K, MutableList<Short>>> ShortArray.group
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K, M : MutableMap<in K, MutableList<Int>>> IntArray.groupByTo(destination: M, keySelector: (Int) -> K): M {
     for (element in this) {
@@ -7528,7 +7528,7 @@ public inline fun <K, M : MutableMap<in K, MutableList<Int>>> IntArray.groupByTo
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K, M : MutableMap<in K, MutableList<Long>>> LongArray.groupByTo(destination: M, keySelector: (Long) -> K): M {
     for (element in this) {
@@ -7545,7 +7545,7 @@ public inline fun <K, M : MutableMap<in K, MutableList<Long>>> LongArray.groupBy
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K, M : MutableMap<in K, MutableList<Float>>> FloatArray.groupByTo(destination: M, keySelector: (Float) -> K): M {
     for (element in this) {
@@ -7562,7 +7562,7 @@ public inline fun <K, M : MutableMap<in K, MutableList<Float>>> FloatArray.group
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K, M : MutableMap<in K, MutableList<Double>>> DoubleArray.groupByTo(destination: M, keySelector: (Double) -> K): M {
     for (element in this) {
@@ -7579,7 +7579,7 @@ public inline fun <K, M : MutableMap<in K, MutableList<Double>>> DoubleArray.gro
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K, M : MutableMap<in K, MutableList<Boolean>>> BooleanArray.groupByTo(destination: M, keySelector: (Boolean) -> K): M {
     for (element in this) {
@@ -7596,7 +7596,7 @@ public inline fun <K, M : MutableMap<in K, MutableList<Boolean>>> BooleanArray.g
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K, M : MutableMap<in K, MutableList<Char>>> CharArray.groupByTo(destination: M, keySelector: (Char) -> K): M {
     for (element in this) {
@@ -7614,7 +7614,7 @@ public inline fun <K, M : MutableMap<in K, MutableList<Char>>> CharArray.groupBy
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <T, K, V, M : MutableMap<in K, MutableList<V>>> Array<out T>.groupByTo(destination: M, keySelector: (T) -> K, valueTransform: (T) -> V): M {
     for (element in this) {
@@ -7632,7 +7632,7 @@ public inline fun <T, K, V, M : MutableMap<in K, MutableList<V>>> Array<out T>.g
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> ByteArray.groupByTo(destination: M, keySelector: (Byte) -> K, valueTransform: (Byte) -> V): M {
     for (element in this) {
@@ -7650,7 +7650,7 @@ public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> ByteArray.groupBy
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> ShortArray.groupByTo(destination: M, keySelector: (Short) -> K, valueTransform: (Short) -> V): M {
     for (element in this) {
@@ -7668,7 +7668,7 @@ public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> ShortArray.groupB
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> IntArray.groupByTo(destination: M, keySelector: (Int) -> K, valueTransform: (Int) -> V): M {
     for (element in this) {
@@ -7686,7 +7686,7 @@ public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> IntArray.groupByT
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> LongArray.groupByTo(destination: M, keySelector: (Long) -> K, valueTransform: (Long) -> V): M {
     for (element in this) {
@@ -7704,7 +7704,7 @@ public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> LongArray.groupBy
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> FloatArray.groupByTo(destination: M, keySelector: (Float) -> K, valueTransform: (Float) -> V): M {
     for (element in this) {
@@ -7722,7 +7722,7 @@ public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> FloatArray.groupB
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> DoubleArray.groupByTo(destination: M, keySelector: (Double) -> K, valueTransform: (Double) -> V): M {
     for (element in this) {
@@ -7740,7 +7740,7 @@ public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> DoubleArray.group
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> BooleanArray.groupByTo(destination: M, keySelector: (Boolean) -> K, valueTransform: (Boolean) -> V): M {
     for (element in this) {
@@ -7758,7 +7758,7 @@ public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> BooleanArray.grou
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> CharArray.groupByTo(destination: M, keySelector: (Char) -> K, valueTransform: (Char) -> V): M {
     for (element in this) {

libraries/stdlib/src/generated/_Collections.kt

@@ -1139,7 +1139,7 @@ public inline fun <T, R, C : MutableCollection<in R>> Iterable<T>.flatMapTo(dest
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original collection.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <T, K> Iterable<T>.groupBy(keySelector: (T) -> K): Map<K, List<T>> {
     return groupByTo(LinkedHashMap<K, MutableList<T>>(), keySelector)
@@ -1152,7 +1152,7 @@ public inline fun <T, K> Iterable<T>.groupBy(keySelector: (T) -> K): Map<K, List
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original collection.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <T, K, V> Iterable<T>.groupBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map<K, List<V>> {
     return groupByTo(LinkedHashMap<K, MutableList<V>>(), keySelector, valueTransform)
@@ -1164,7 +1164,7 @@ public inline fun <T, K, V> Iterable<T>.groupBy(keySelector: (T) -> K, valueTran
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <T, K, M : MutableMap<in K, MutableList<T>>> Iterable<T>.groupByTo(destination: M, keySelector: (T) -> K): M {
     for (element in this) {
@@ -1182,7 +1182,7 @@ public inline fun <T, K, M : MutableMap<in K, MutableList<T>>> Iterable<T>.group
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <T, K, V, M : MutableMap<in K, MutableList<V>>> Iterable<T>.groupByTo(destination: M, keySelector: (T) -> K, valueTransform: (T) -> V): M {
     for (element in this) {

libraries/stdlib/src/generated/_Sequences.kt

@@ -608,7 +608,7 @@ public inline fun <T, R, C : MutableCollection<in R>> Sequence<T>.flatMapTo(dest
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original sequence.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <T, K> Sequence<T>.groupBy(keySelector: (T) -> K): Map<K, List<T>> {
     return groupByTo(LinkedHashMap<K, MutableList<T>>(), keySelector)
@@ -621,7 +621,7 @@ public inline fun <T, K> Sequence<T>.groupBy(keySelector: (T) -> K): Map<K, List
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original sequence.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <T, K, V> Sequence<T>.groupBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map<K, List<V>> {
     return groupByTo(LinkedHashMap<K, MutableList<V>>(), keySelector, valueTransform)
@@ -633,7 +633,7 @@ public inline fun <T, K, V> Sequence<T>.groupBy(keySelector: (T) -> K, valueTran
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <T, K, M : MutableMap<in K, MutableList<T>>> Sequence<T>.groupByTo(destination: M, keySelector: (T) -> K): M {
     for (element in this) {
@@ -651,7 +651,7 @@ public inline fun <T, K, M : MutableMap<in K, MutableList<T>>> Sequence<T>.group
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <T, K, V, M : MutableMap<in K, MutableList<V>>> Sequence<T>.groupByTo(destination: M, keySelector: (T) -> K, valueTransform: (T) -> V): M {
     for (element in this) {

libraries/stdlib/src/generated/_Strings.kt

@@ -658,7 +658,7 @@ public inline fun <R, C : MutableCollection<in R>> CharSequence.flatMapTo(destin
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original char sequence.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K> CharSequence.groupBy(keySelector: (Char) -> K): Map<K, List<Char>> {
     return groupByTo(LinkedHashMap<K, MutableList<Char>>(), keySelector)
@@ -671,7 +671,7 @@ public inline fun <K> CharSequence.groupBy(keySelector: (Char) -> K): Map<K, Lis
  * 
  * The returned map preserves the entry iteration order of the keys produced from the original char sequence.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V> CharSequence.groupBy(keySelector: (Char) -> K, valueTransform: (Char) -> V): Map<K, List<V>> {
     return groupByTo(LinkedHashMap<K, MutableList<V>>(), keySelector, valueTransform)
@@ -683,7 +683,7 @@ public inline fun <K, V> CharSequence.groupBy(keySelector: (Char) -> K, valueTra
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupBy
+ * @sample samples.collections.Collections.Transformations.groupBy
  */
 public inline fun <K, M : MutableMap<in K, MutableList<Char>>> CharSequence.groupByTo(destination: M, keySelector: (Char) -> K): M {
     for (element in this) {
@@ -701,7 +701,7 @@ public inline fun <K, M : MutableMap<in K, MutableList<Char>>> CharSequence.grou
  * 
  * @return The [destination] map.
  * 
- * @sample test.collections.CollectionTest.groupByKeysAndValues
+ * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
  */
 public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> CharSequence.groupByTo(destination: M, keySelector: (Char) -> K, valueTransform: (Char) -> V): M {
     for (element in this) {

libraries/stdlib/src/kotlin/collections/Collections.kt

@@ -113,7 +113,7 @@ public val Collection<*>.indices: IntRange
 /**
  * Returns the index of the last item in the list or -1 if the list is empty.
  *
- * @sample test.collections.ListSpecificTest.lastIndex
+ * @sample samples.collections.Collections.Lists.lastIndexOfList
  */
 public val <T> List<T>.lastIndex: Int
     get() = this.size - 1

libraries/stdlib/src/kotlin/collections/Maps.kt

@@ -23,7 +23,10 @@ private object EmptyMap : Map<Any?, Nothing>, Serializable {
     private fun readResolve(): Any = EmptyMap
 }
 
-/** Returns an empty read-only map of specified type. The returned map is serializable (JVM). */
+/**
+ * Returns an empty read-only map of specified type. The returned map is serializable (JVM).
+ * @sample samples.collections.Maps.Instantiation.emptyReadOnlyMap
+ */
 public fun <K, V> emptyMap(): Map<K, V> = @Suppress("UNCHECKED_CAST") (EmptyMap as Map<K, V>)
 
 /**
@@ -33,16 +36,22 @@ public fun <K, V> emptyMap(): Map<K, V> = @Suppress("UNCHECKED_CAST") (EmptyMap
  *
  * Entries of the map are iterated in the order they were specified.
  * The returned map is serializable (JVM).
+ *
+ * @sample samples.collections.Maps.Instantiation.mapFromPairs
  */
 public fun <K, V> mapOf(vararg pairs: Pair<K, V>): Map<K, V> = if (pairs.size > 0) linkedMapOf(*pairs) else emptyMap()
 
-/** Returns an empty read-only map. The returned map is serializable (JVM). */
+/**
+ * Returns an empty read-only map. The returned map is serializable (JVM).
+ * @sample samples.collections.Maps.Instantiation.emptyReadOnlyMap
+ */
 @kotlin.internal.InlineOnly
 public inline fun <K, V> mapOf(): Map<K, V> = emptyMap()
 
 /**
  * Returns an immutable map, mapping only the specified key to the
  * specified value.  The returned map is serializable.
+ * @sample samples.collections.Maps.Instantiation.mapFromPairs
  */
 @JvmVersion
 public fun <K, V> mapOf(pair: Pair<K, V>): Map<K, V> = java.util.Collections.singletonMap(pair.first, pair.second)
@@ -52,6 +61,8 @@ public fun <K, V> mapOf(pair: Pair<K, V>): Map<K, V> = java.util.Collections.sin
  * where the first component is the key and the second is the value. If multiple pairs have
  * the same key, the resulting map will contain the value from the last of those pairs.
  * Entries of the map are iterated in the order they were specified.
+ * @sample samples.collections.Maps.Instantiation.mutableMapFromPairs
+ * @sample samples.collections.Maps.Instantiation.emptyMutableMap
  */
 public fun <K, V> mutableMapOf(vararg pairs: Pair<K, V>): MutableMap<K, V>
         = LinkedHashMap<K, V>(mapCapacity(pairs.size)).apply { putAll(pairs) }
@@ -60,7 +71,7 @@ public fun <K, V> mutableMapOf(vararg pairs: Pair<K, V>): MutableMap<K, V>
  * Returns a new [HashMap] with the specified contents, given as a list of pairs
  * where the first component is the key and the second is the value.
  *
- * @sample test.collections.MapTest.createUsingPairs
+ * @sample samples.collections.Maps.Instantiation.hashMapFromPairs
  */
 public fun <K, V> hashMapOf(vararg pairs: Pair<K, V>): HashMap<K, V>
         = HashMap<K, V>(mapCapacity(pairs.size)).apply { putAll(pairs) }
@@ -72,7 +83,7 @@ public fun <K, V> hashMapOf(vararg pairs: Pair<K, V>): HashMap<K, V>
  * the same key, the resulting map will contain the value from the last of those pairs.
  * Entries of the map are iterated in the order they were specified.
  *
- * @sample test.collections.MapTest.createLinkedMap
+ * @sample samples.collections.Maps.Instantiation.linkedMapFromPairs
  */
 public fun <K, V> linkedMapOf(vararg pairs: Pair<K, V>): LinkedHashMap<K, V>
         = LinkedHashMap<K, V>(mapCapacity(pairs.size)).apply { putAll(pairs) }
@@ -182,7 +193,7 @@ public inline fun <K, V> Map.Entry<K, V>.toPair(): Pair<K, V> = Pair(key, value)
 /**
  * Returns the value for the given key, or the result of the [defaultValue] function if there was no entry for the given key.
  *
- * @sample test.collections.MapTest.getOrElse
+ * @sample samples.collections.Maps.Usage.getOrElse
  */
 @kotlin.internal.InlineOnly
 public inline fun <K, V> Map<K, V>.getOrElse(key: K, defaultValue: () -> V): V = get(key) ?: defaultValue()
@@ -203,7 +214,7 @@ internal inline fun <K, V> Map<K, V>.getOrElseNullable(key: K, defaultValue: ()
  * Returns the value for the given key. If the key is not found in the map, calls the [defaultValue] function,
  * puts its result into the map under the given key and returns it.
  *
- * @sample test.collections.MapTest.getOrPut
+ * @sample samples.collections.Maps.Usage.getOrPut
  */
 public inline fun <K, V> MutableMap<K, V>.getOrPut(key: K, defaultValue: () -> V): V {
     val value = get(key)
@@ -219,7 +230,7 @@ public inline fun <K, V> MutableMap<K, V>.getOrPut(key: K, defaultValue: () -> V
 /**
  * Returns an [Iterator] over the entries in the [Map].
  *
- * @sample test.collections.MapTest.iterateWithProperties
+ * @sample samples.collections.Maps.Usage.forOverEntries
  */
 @kotlin.internal.InlineOnly
 public inline operator fun <K, V> Map<out K, V>.iterator(): Iterator<Map.Entry<K, V>> = entries.iterator()
@@ -285,7 +296,7 @@ public fun <K, V> MutableMap<in K, in V>.putAll(pairs: Sequence<Pair<K,V>>): Uni
  *
  * The returned map preserves the entry iteration order of the original map.
  *
- * @sample test.collections.MapTest.mapValues
+ * @sample samples.collections.Maps.Transforms.mapValues
  */
 @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
 public inline fun <K, V, R> Map<out K, V>.mapValues(transform: (Map.Entry<K, V>) -> R): Map<K, R> {
@@ -301,7 +312,7 @@ public inline fun <K, V, R> Map<out K, V>.mapValues(transform: (Map.Entry<K, V>)
  *
  * The returned map preserves the entry iteration order of the original map.
  *
- * @sample test.collections.MapTest.mapKeys
+ * @sample samples.collections.Maps.Transforms.mapKeys
  */
 @Suppress("NON_PUBLIC_CALL_FROM_PUBLIC_INLINE")
 public inline fun <K, V, R> Map<out K, V>.mapKeys(transform: (Map.Entry<K, V>) -> R): Map<R, V> {

libraries/stdlib/src/kotlin/collections/MapsJVM.kt

@@ -40,7 +40,7 @@ public inline fun <K, V> ConcurrentMap<K, V>.getOrPut(key: K, defaultValue: () -
 /**
  * Converts this [Map] to a [SortedMap] so iteration order will be in key order.
  *
- * @sample test.collections.MapJVMTest.toSortedMap
+ * @sample samples.collections.Maps.Transformations.mapToSortedMap
  */
 public fun <K : Comparable<K>, V> Map<out K, V>.toSortedMap(): SortedMap<K, V> = TreeMap(this)
 
@@ -48,7 +48,7 @@ public fun <K : Comparable<K>, V> Map<out K, V>.toSortedMap(): SortedMap<K, V> =
  * Converts this [Map] to a [SortedMap] using the given [comparator] so that iteration order will be in the order
  * defined by the comparator.
  *
- * @sample test.collections.MapJVMTest.toSortedMapWithComparator
+ * @sample samples.collections.Maps.Transformations.mapToSortedMapWithComparator
  */
 public fun <K, V> Map<out K, V>.toSortedMap(comparator: Comparator<in K>): SortedMap<K, V>
         = TreeMap<K, V>(comparator).apply { putAll(this@toSortedMap) }
@@ -57,7 +57,7 @@ public fun <K, V> Map<out K, V>.toSortedMap(comparator: Comparator<in K>): Sorte
  * Returns a new [SortedMap] with the specified contents, given as a list of pairs
  * where the first value is the key and the second is the value.
  *
- * @sample test.collections.MapJVMTest.createSortedMap
+ * @sample samples.collections.Maps.Instantiation.sortedMapFromPairs
  */
 public fun <K : Comparable<K>, V> sortedMapOf(vararg pairs: Pair<K, V>): SortedMap<K, V>
         = TreeMap<K, V>().apply { putAll(pairs) }
@@ -66,7 +66,7 @@ public fun <K : Comparable<K>, V> sortedMapOf(vararg pairs: Pair<K, V>): SortedM
 /**
  * Converts this [Map] to a [Properties] object.
  *
- * @sample test.collections.MapJVMTest.toProperties
+ * @sample samples.collections.Maps.Transformations.mapToProperties
  */
 @kotlin.internal.InlineOnly
 public inline fun Map<String, String>.toProperties(): Properties

libraries/stdlib/src/kotlin/text/StringsJVM.kt

@@ -385,7 +385,7 @@ public inline fun String.toPattern(flags: Int = 0): java.util.regex.Pattern {
  * Returns a copy of this string having its first letter uppercased, or the original string,
  * if it's empty or already starts with an upper case letter.
  *
- * @sample test.text.StringTest.capitalize
+ * @sample samples.text.Strings.captialize
  */
 public fun String.capitalize(): String {
     return if (isNotEmpty() && this[0].isLowerCase()) substring(0, 1).toUpperCase() + substring(1) else this
@@ -395,7 +395,7 @@ public fun String.capitalize(): String {
  * Returns a copy of this string having its first letter lowercased, or the original string,
  * if it's empty or already starts with a lower case letter.
  *
- * @sample test.text.StringTest.decapitalize
+ * @sample samples.text.Strings.decaptialize
  */
 public fun String.decapitalize(): String {
     return if (isNotEmpty() && this[0].isUpperCase()) substring(0, 1).toLowerCase() + substring(1) else this
@@ -404,7 +404,7 @@ public fun String.decapitalize(): String {
 /**
  * Returns a string containing this char sequence repeated [n] times.
  * @throws [IllegalArgumentException] when n < 0.
- * @sample test.text.StringJVMTest.repeat
+ * @sample samples.text.Strings.repeat
  */
 public fun CharSequence.repeat(n: Int): String {
     require (n >= 0) { "Count 'n' must be non-negative, but was $n." }

libraries/stdlib/src/kotlin/text/regex/MatchResult.kt

@@ -73,6 +73,8 @@ public interface MatchResult {
      *
      * If the group in the regular expression is optional and there were no match captured by that group,
      * corresponding item in [groupValues] is an empty string.
+     *
+     * @sample: samples.text.Regexps.matchDestructuringToGroupValues
      */
     public val groupValues: List<String>
 
@@ -81,10 +83,7 @@ public interface MatchResult {
      *
      * component1 corresponds to the value of the first group, component2 — of the second, and so on.
      *
-     * @sample:
-     * ```
-     * val (name, phone) = Regex("(\\w+) (\\d+)").match(inputString)!!.destructured
-     * ```
+     * @sample: samples.text.Regexps.matchDestructuring
      */
     public val destructured: Destructured get() = Destructured(this)
 
@@ -100,6 +99,8 @@ public interface MatchResult {
      *
      * If the group in the regular expression is optional and there were no match captured by that group,
      * corresponding component value is an empty string.
+     *
+     * @sample: samples.text.Regexps.matchDestructuringToGroupValues
      */
     public class Destructured internal constructor(public val match: MatchResult) {
         @kotlin.internal.InlineOnly
@@ -125,6 +126,8 @@ public interface MatchResult {
         /**
          *  Returns destructured group values as a list of strings.
          *  First value in the returned list corresponds to the value of the first group, and so on.
+         *
+         * @sample: samples.text.Regexps.matchDestructuringToGroupValues
          */
         public fun toList(): List<String> = match.groupValues.subList(1, match.groupValues.size)
     }

libraries/stdlib/src/kotlin/util/Preconditions.kt

@@ -4,6 +4,8 @@ package kotlin
 
 /**
  * Throws an [IllegalArgumentException] if the [value] is false.
+ *
+ * @sample samples.misc.Preconditions.failRequireWithLazyMessage
  */
 @kotlin.internal.InlineOnly
 public inline fun require(value: Boolean): Unit = require(value) { "Failed requirement." }
@@ -11,7 +13,7 @@ public inline fun require(value: Boolean): Unit = require(value) { "Failed requi
 /**
  * Throws an [IllegalArgumentException] with the result of calling [lazyMessage] if the [value] is false.
  *
- * @sample test.collections.PreconditionsTest.failingRequireWithLazyMessage
+ * @sample samples.misc.Preconditions.failRequireWithLazyMessage
  */
 @kotlin.internal.InlineOnly
 public inline fun require(value: Boolean, lazyMessage: () -> Any): Unit {
@@ -31,7 +33,7 @@ public inline fun <T:Any> requireNotNull(value: T?): T = requireNotNull(value) {
  * Throws an [IllegalArgumentException] with the result of calling [lazyMessage] if the [value] is null. Otherwise
  * returns the not null value.
  *
- * @sample test.collections.PreconditionsTest.requireNotNullWithLazyMessage
+ * @sample samples.misc.Preconditions.failRequireWithLazyMessage
  */
 @kotlin.internal.InlineOnly
 public inline fun <T:Any> requireNotNull(value: T?, lazyMessage: () -> Any): T {
@@ -45,6 +47,8 @@ public inline fun <T:Any> requireNotNull(value: T?, lazyMessage: () -> Any): T {
 
 /**
  * Throws an [IllegalStateException] if the [value] is false.
+ *
+ * @sample samples.misc.Preconditions.failCheckWithLazyMessage
  */
 @kotlin.internal.InlineOnly
 public inline fun check(value: Boolean): Unit = check(value) { "Check failed." }
@@ -52,7 +56,7 @@ public inline fun check(value: Boolean): Unit = check(value) { "Check failed." }
 /**
  * Throws an [IllegalStateException] with the result of calling [lazyMessage] if the [value] is false.
  *
- * @sample test.collections.PreconditionsTest.failingCheckWithLazyMessage
+ * @sample samples.misc.Preconditions.failCheckWithLazyMessage
  */
 @kotlin.internal.InlineOnly
 public inline fun check(value: Boolean, lazyMessage: () -> Any): Unit {
@@ -65,6 +69,8 @@ public inline fun check(value: Boolean, lazyMessage: () -> Any): Unit {
 /**
  * Throws an [IllegalStateException] if the [value] is null. Otherwise
  * returns the not null value.
+ *
+ * @sample samples.misc.Preconditions.failCheckWithLazyMessage
  */
 @kotlin.internal.InlineOnly
 public inline fun <T:Any> checkNotNull(value: T?): T = checkNotNull(value) { "Required value was null." }
@@ -72,6 +78,8 @@ public inline fun <T:Any> checkNotNull(value: T?): T = checkNotNull(value) { "Re
 /**
  * Throws an [IllegalStateException] with the result of calling [lazyMessage]  if the [value] is null. Otherwise
  * returns the not null value.
+ *
+ * @sample samples.misc.Preconditions.failCheckWithLazyMessage
  */
 @kotlin.internal.InlineOnly
 public inline fun <T:Any> checkNotNull(value: T?, lazyMessage: () -> Any): T {
@@ -87,7 +95,7 @@ public inline fun <T:Any> checkNotNull(value: T?, lazyMessage: () -> Any): T {
 /**
  * Throws an [IllegalStateException] with the given [message].
  *
- * @sample test.collections.PreconditionsTest.error
+ * @sample samples.misc.Preconditions.failWithError
  */
 @kotlin.internal.InlineOnly
 public inline fun error(message: Any): Nothing = throw IllegalStateException(message.toString())

libraries/stdlib/src/kotlin/util/Tuples.kt

@@ -9,7 +9,7 @@ package kotlin
  * Pair exhibits value semantics, i.e. two pairs are equal if both components are equal.
  *
  * An example of decomposing it into values:
- * @sample test.tuples.PairTest.pairMultiAssignment
+ * @sample samples.misc.Tuples.pairDestructuring
  *
  * @param A type of the first value.
  * @param B type of the second value.
@@ -32,7 +32,7 @@ public data class Pair<out A, out B>(
  * Creates a tuple of type [Pair] from this and [that].
  *
  * This can be useful for creating [Map] literals with less noise, for example:
- * @sample test.collections.MapTest.createUsingTo
+ * @sample samples.collections.Maps.Instantiation.mapFromPairs
  */
 public infix fun <A, B> A.to(that: B): Pair<A, B> = Pair(this, that)
 
@@ -47,7 +47,7 @@ public fun <T> Pair<T, T>.toList(): List<T> = listOf(first, second)
  * There is no meaning attached to values in this class, it can be used for any purpose.
  * Triple exhibits value semantics, i.e. two triples are equal if all three components are equal.
  * An example of decomposing it into values:
- * @sample test.tuples.TripleTest.tripleMultiAssignment
+ * @sample samples.misc.Tuples.tripleDestructuring
  *
  * @param A type of the first value.
  * @param B type of the second value.

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

@@ -297,7 +297,7 @@ fun mapping(): List<GenericFunction> {
 
             The returned map preserves the entry iteration order of the keys produced from the original ${f.collection}.
 
-            @sample test.collections.CollectionTest.groupBy
+            @sample samples.collections.Collections.Transformations.groupBy
             """
         }
         typeParam("K")
@@ -318,7 +318,7 @@ fun mapping(): List<GenericFunction> {
 
             @return The [destination] map.
 
-            @sample test.collections.CollectionTest.groupBy
+            @sample samples.collections.Collections.Transformations.groupBy
             """
         }
         returns("M")
@@ -346,7 +346,7 @@ fun mapping(): List<GenericFunction> {
 
             The returned map preserves the entry iteration order of the keys produced from the original ${f.collection}.
 
-            @sample test.collections.CollectionTest.groupByKeysAndValues
+            @sample samples.collections.Collections.Transformations.groupByKeysAndValues
             """
         }
         typeParam("K")
@@ -372,7 +372,7 @@ fun mapping(): List<GenericFunction> {
 
             @return The [destination] map.
 
-            @sample test.collections.CollectionTest.groupByKeysAndValues
+            @sample samples.collections.Collections.Transformations.groupByKeysAndValues
             """
         }
         returns("M")