Update Flow.sample KDoc example timings, add tests (#2259)

* All Flow.debounce/sample KDoc example code snippets are automatically tested with Knit.
* Flow.sample timings are made larger, so that they produce an expected output when run under the real time, too.

Fixes #2243

Author: elizarov

docs/knit.properties

@@ -4,19 +4,7 @@
 
 knit.package=kotlinx.coroutines.guide
 knit.dir=../kotlinx-coroutines-core/jvm/test/guide/
-knit.pattern=example-[a-zA-Z0-9-]+-##\\.kt
-knit.include=knit.code.include
 
 test.package=kotlinx.coroutines.guide.test
 test.dir=../kotlinx-coroutines-core/jvm/test/guide/test/
-test.template=knit.test.template
 
-# Various test validation modes and their corresponding methods from TestUtil
-test.mode.=verifyLines
-test.mode.STARTS_WITH=verifyLinesStartWith
-test.mode.ARBITRARY_TIME=verifyLinesArbitraryTime
-test.mode.FLEXIBLE_TIME=verifyLinesFlexibleTime
-test.mode.FLEXIBLE_THREAD=verifyLinesFlexibleThread
-test.mode.LINES_START_UNORDERED=verifyLinesStartUnordered
-test.mode.LINES_START=verifyLinesStart
-test.mode.EXCEPTION=verifyExceptions

docs/knit.test.template

@@ -5,6 +5,7 @@
 // This file was automatically generated from ${file.name} by Knit tool. Do not edit.
 package ${test.package}
 
+import kotlinx.coroutines.knit.*
 import org.junit.Test
 
 class ${test.name} {

gradle.properties

@@ -10,7 +10,7 @@ kotlin_version=1.4.0
 # Dependencies
 junit_version=4.12
 atomicfu_version=0.14.4
-knit_version=0.1.3
+knit_version=0.2.0
 html_version=0.6.8
 lincheck_version=2.7.1
 dokka_version=0.9.16-rdev-2-mpp-hacks

knit.properties

@@ -0,0 +1,16 @@
+#
+# Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+#
+
+knit.include=docs/knit.code.include
+test.template=docs/knit.test.template
+
+# Various test validation modes and their corresponding methods from TestUtil
+test.mode.=verifyLines
+test.mode.STARTS_WITH=verifyLinesStartWith
+test.mode.ARBITRARY_TIME=verifyLinesArbitraryTime
+test.mode.FLEXIBLE_TIME=verifyLinesFlexibleTime
+test.mode.FLEXIBLE_THREAD=verifyLinesFlexibleThread
+test.mode.LINES_START_UNORDERED=verifyLinesStartUnordered
+test.mode.LINES_START=verifyLinesStart
+test.mode.EXCEPTION=verifyExceptions

kotlinx-coroutines-core/common/src/flow/operators/Delay.kt

@@ -14,13 +14,30 @@ import kotlinx.coroutines.selects.*
 import kotlin.jvm.*
 import kotlin.time.*
 
+/* Scaffolding for Knit code examples
+<!--- TEST_NAME FlowDelayTest -->
+<!--- PREFIX .*-duration-.*
+@file:OptIn(ExperimentalTime::class)
+----- INCLUDE .*-duration-.*
+import kotlin.time.*
+----- INCLUDE .*
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+fun main() = runBlocking {
+----- SUFFIX .*
+.toList().joinToString().let { println(it) } }
+-->
+*/
+
 /**
  * Returns a flow that mirrors the original flow, but filters out values
  * that are followed by the newer values within the given [timeout][timeoutMillis].
  * The latest value is always emitted.
  *
  * Example:
- * ```
+ *
+ * ```kotlin
  * flow {
  *     emit(1)
  *     delay(90)
@@ -33,7 +50,14 @@ import kotlin.time.*
  *     emit(5)
  * }.debounce(1000)
  * ```
- * produces `3, 4, 5`.
+ * <!--- KNIT example-delay-01.kt -->
+ *
+ * produces the following emissions
+ *
+ * ```text
+ * 3, 4, 5
+ * ```
+ * <!--- TEST -->
  *
  * Note that the resulting flow does not emit anything as long as the original flow emits
  * items faster than every [timeoutMillis] milliseconds.
@@ -77,7 +101,8 @@ public fun <T> Flow<T>.debounce(timeoutMillis: Long): Flow<T> {
  * The latest value is always emitted.
  *
  * Example:
- * ```
+ *
+ * ```kotlin
  * flow {
  *     emit(1)
  *     delay(90.milliseconds)
@@ -90,7 +115,14 @@ public fun <T> Flow<T>.debounce(timeoutMillis: Long): Flow<T> {
  *     emit(5)
  * }.debounce(1000.milliseconds)
  * ```
- * produces `3, 4, 5`.
+ * <!--- KNIT example-delay-duration-01.kt -->
+ *
+ * produces the following emissions
+ *
+ * ```text
+ * 3, 4, 5
+ * ```
+ * <!--- TEST -->
  *
  * Note that the resulting flow does not emit anything as long as the original flow emits
  * items faster than every [timeout] milliseconds.
@@ -103,15 +135,23 @@ public fun <T> Flow<T>.debounce(timeout: Duration): Flow<T> = debounce(timeout.t
  * Returns a flow that emits only the latest value emitted by the original flow during the given sampling [period][periodMillis].
  *
  * Example:
- * ```
+ *
+ * ```kotlin
  * flow {
  *     repeat(10) {
  *         emit(it)
- *         delay(50)
+ *         delay(110)
  *     }
- * }.sample(100)
+ * }.sample(200)
+ * ```
+ * <!--- KNIT example-delay-02.kt -->
+ *
+ * produces the following emissions
+ *
+ * ```text
+ * 1, 3, 5, 7, 9
  * ```
- * produces `1, 3, 5, 7, 9`.
+ * <!--- TEST -->
  * 
  * Note that the latest element is not emitted if it does not fit into the sampling window.
  */
@@ -166,15 +206,23 @@ internal fun CoroutineScope.fixedPeriodTicker(delayMillis: Long, initialDelayMil
  * Returns a flow that emits only the latest value emitted by the original flow during the given sampling [period].
  *
  * Example:
- * ```
+ *
+ * ```kotlin
  * flow {
  *     repeat(10) {
  *         emit(it)
- *         delay(50.milliseconds)
+ *         delay(110.milliseconds)
  *     }
- * }.sample(100.milliseconds)
+ * }.sample(200.milliseconds)
+ * ```
+ * <!--- KNIT example-delay-duration-02.kt -->
+ *
+ * produces the following emissions
+ *
+ * ```text
+ * 1, 3, 5, 7, 9
  * ```
- * produces `1, 3, 5, 7, 9`.
+ * <!--- TEST -->
  *
  * Note that the latest element is not emitted if it does not fit into the sampling window.
  */

kotlinx-coroutines-core/jvm/test/examples/example-delay-01.kt

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// This file was automatically generated from Delay.kt by Knit tool. Do not edit.
+package kotlinx.coroutines.examples.exampleDelay01
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+fun main() = runBlocking {
+
+flow {
+    emit(1)
+    delay(90)
+    emit(2)
+    delay(90)
+    emit(3)
+    delay(1010)
+    emit(4)
+    delay(1010)
+    emit(5)
+}.debounce(1000)
+.toList().joinToString().let { println(it) } }

kotlinx-coroutines-core/jvm/test/examples/example-delay-02.kt

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// This file was automatically generated from Delay.kt by Knit tool. Do not edit.
+package kotlinx.coroutines.examples.exampleDelay02
+
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+fun main() = runBlocking {
+
+flow {
+    repeat(10) {
+        emit(it)
+        delay(110)
+    }
+}.sample(200)
+.toList().joinToString().let { println(it) } }

kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-01.kt

@@ -0,0 +1,26 @@
+@file:OptIn(ExperimentalTime::class)
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// This file was automatically generated from Delay.kt by Knit tool. Do not edit.
+package kotlinx.coroutines.examples.exampleDelayDuration01
+
+import kotlin.time.*
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+fun main() = runBlocking {
+
+flow {
+    emit(1)
+    delay(90.milliseconds)
+    emit(2)
+    delay(90.milliseconds)
+    emit(3)
+    delay(1010.milliseconds)
+    emit(4)
+    delay(1010.milliseconds)
+    emit(5)
+}.debounce(1000.milliseconds)
+.toList().joinToString().let { println(it) } }

kotlinx-coroutines-core/jvm/test/examples/example-delay-duration-02.kt

@@ -0,0 +1,21 @@
+@file:OptIn(ExperimentalTime::class)
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// This file was automatically generated from Delay.kt by Knit tool. Do not edit.
+package kotlinx.coroutines.examples.exampleDelayDuration02
+
+import kotlin.time.*
+import kotlinx.coroutines.*
+import kotlinx.coroutines.flow.*
+
+fun main() = runBlocking {
+
+flow {
+    repeat(10) {
+        emit(it)
+        delay(110.milliseconds)
+    }
+}.sample(200.milliseconds)
+.toList().joinToString().let { println(it) } }

kotlinx-coroutines-core/jvm/test/examples/test/FlowDelayTest.kt

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+// This file was automatically generated from Delay.kt by Knit tool. Do not edit.
+package kotlinx.coroutines.examples.test
+
+import kotlinx.coroutines.knit.*
+import org.junit.Test
+
+class FlowDelayTest {
+    @Test
+    fun testExampleDelay01() {
+        test("ExampleDelay01") { kotlinx.coroutines.examples.exampleDelay01.main() }.verifyLines(
+            "3, 4, 5"
+        )
+    }
+
+    @Test
+    fun testExampleDelayDuration01() {
+        test("ExampleDelayDuration01") { kotlinx.coroutines.examples.exampleDelayDuration01.main() }.verifyLines(
+            "3, 4, 5"
+        )
+    }
+
+    @Test
+    fun testExampleDelay02() {
+        test("ExampleDelay02") { kotlinx.coroutines.examples.exampleDelay02.main() }.verifyLines(
+            "1, 3, 5, 7, 9"
+        )
+    }
+
+    @Test
+    fun testExampleDelayDuration02() {
+        test("ExampleDelayDuration02") { kotlinx.coroutines.examples.exampleDelayDuration02.main() }.verifyLines(
+            "1, 3, 5, 7, 9"
+        )
+    }
+}