From 25b3f627671d183883525f1bb83d4f7dc0e5c1af Mon Sep 17 00:00:00 2001
From: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>
Date: Thu, 14 Mar 2019 22:28:34 +0300
Subject: [PATCH] Clarify yield/yieldAll function suspending the caller
 behavior

---
 .../stdlib/src/kotlin/collections/SequenceBuilder.kt | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/libraries/stdlib/src/kotlin/collections/SequenceBuilder.kt b/libraries/stdlib/src/kotlin/collections/SequenceBuilder.kt
index b28be61f60d..d2421eff880 100644
--- a/libraries/stdlib/src/kotlin/collections/SequenceBuilder.kt
+++ b/libraries/stdlib/src/kotlin/collections/SequenceBuilder.kt
@@ -60,7 +60,8 @@ public inline fun <T> buildIterator(@BuilderInference noinline builderAction: su
 @SinceKotlin("1.3")
 public abstract class SequenceScope<in T> internal constructor() {
     /**
-     * Yields a value to the [Iterator] being built.
+     * Yields a value to the [Iterator] being built and suspends
+     * until the next value is requested.
      *
      * @sample samples.collections.Sequences.Building.buildSequenceYieldAll
      * @sample samples.collections.Sequences.Building.buildFibonacciSequence
@@ -68,7 +69,8 @@ public abstract class SequenceScope<in T> internal constructor() {
     public abstract suspend fun yield(value: T)
 
     /**
-     * Yields all values from the `iterator` to the [Iterator] being built.
+     * Yields all values from the `iterator` to the [Iterator] being built
+     * and suspends until all these values are iterated and the next one is requested.
      *
      * The sequence of values returned by the given iterator can be potentially infinite.
      *
@@ -77,7 +79,8 @@ public abstract class SequenceScope<in T> internal constructor() {
     public abstract suspend fun yieldAll(iterator: Iterator<T>)
 
     /**
-     * Yields a collections of values to the [Iterator] being built.
+     * Yields a collections of values to the [Iterator] being built
+     * and suspends until all these values are iterated and the next one is requested.
      *
      * @sample samples.collections.Sequences.Building.buildSequenceYieldAll
      */
@@ -87,7 +90,8 @@ public abstract class SequenceScope<in T> internal constructor() {
     }
 
     /**
-     * Yields potentially infinite sequence of values  to the [Iterator] being built.
+     * Yields potentially infinite sequence of values  to the [Iterator] being built
+     * and suspends until all these values are iterated and the next one is requested.
      *
      * The sequence can be potentially infinite.
      *