azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Remove confusing samples from SequenceBuilder docs

Browse Source 
Problem:
SequenceBuilder is experimental and deprecated in 1.3 in favor of
SequenceScope. Usage of experimental package is discouraged in 1.3.
The documentation for SequenceBuilder refers to SequnceScope sample code,
which might be confusing.

Solution:
Remove samples for SequenceBuilder completely to discourage its usage,
but provide a note about it having deprecated in favor of SequenceScope.
Provide links to modern version of outdated SequenceBuilder.
This commit is contained in:
Mikhail Levchenko
2018-10-21 21:18:06 +03:00
committed by Ilya Gorbunov
parent af5281e7c7
commit 16918fa25e
1 changed files with 9 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/stdlib/coroutines-experimental/src/kotlin/coroutines/experimental/SequenceBuilder.kt
+9 -17
View File
@@ -15,10 +15,10 @@ import kotlin.experimental.ExperimentalTypeInference
/** /**
* Builds a [Sequence] lazily yielding values one by one. * Builds a [Sequence] lazily yielding values one by one.
* *
* @see kotlin.sequences.generateSequence * Since Kotlin 1.3 use [kotlin.sequences.sequence] instead.
* *
* @sample samples.collections.Sequences.Building.buildSequenceYieldAll * @see kotlin.sequences.generateSequence
* @sample samples.collections.Sequences.Building.buildFibonacciSequence * @see kotlin.sequences.sequence
*/ */
@SinceKotlin("1.1") @SinceKotlin("1.1")
public fun <T> buildSequence(@BuilderInference builderAction: suspend SequenceBuilder<T>.() -> Unit): Sequence<T> = Sequence { buildIterator(builderAction) } public fun <T> buildSequence(@BuilderInference builderAction: suspend SequenceBuilder<T>.() -> Unit): Sequence<T> = Sequence { buildIterator(builderAction) }
@@ -26,8 +26,9 @@ public fun <T> buildSequence(@BuilderInference builderAction: suspend SequenceBu
/** /**
* Builds an [Iterator] lazily yielding values one by one. * Builds an [Iterator] lazily yielding values one by one.
* *
* @sample samples.collections.Sequences.Building.buildIterator * Since Kotlin 1.3 use [kotlin.sequences.iterator] instead.
* @sample samples.collections.Iterables.Building.iterable *
* @see kotlin.sequences.iterator
*/ */
@SinceKotlin("1.1") @SinceKotlin("1.1")
public fun <T> buildIterator(@BuilderInference builderAction: suspend SequenceBuilder<T>.() -> Unit): Iterator<T> { public fun <T> buildIterator(@BuilderInference builderAction: suspend SequenceBuilder<T>.() -> Unit): Iterator<T> {
@@ -39,20 +40,17 @@ public fun <T> buildIterator(@BuilderInference builderAction: suspend SequenceBu
/** /**
* Builder for a [Sequence] or an [Iterator], provides [yield] and [yieldAll] suspension functions. * Builder for a [Sequence] or an [Iterator], provides [yield] and [yieldAll] suspension functions.
* *
* Since Kotlin 1.3 use [kotlin.sequences.SequenceScope] instead.
*
* @see buildSequence * @see buildSequence
* @see buildIterator * @see buildIterator
* * @see kotlin.sequences.SequenceScope
* @sample samples.collections.Sequences.Building.buildSequenceYieldAll
* @sample samples.collections.Sequences.Building.buildFibonacciSequence
*/ */
@RestrictsSuspension @RestrictsSuspension
@SinceKotlin("1.1") @SinceKotlin("1.1")
public abstract class SequenceBuilder<in T> internal constructor() { public abstract class SequenceBuilder<in T> internal constructor() {
/** /**
* Yields a value to the [Iterator] being built. * Yields a value to the [Iterator] being built.
*
* @sample samples.collections.Sequences.Building.buildSequenceYieldAll
* @sample samples.collections.Sequences.Building.buildFibonacciSequence
*/ */
public abstract suspend fun yield(value: T) public abstract suspend fun yield(value: T)
@@ -60,15 +58,11 @@ public abstract class SequenceBuilder<in T> internal constructor() {
* Yields all values from the `iterator` to the [Iterator] being built. * Yields all values from the `iterator` to the [Iterator] being built.
* *
* The sequence of values returned by the given iterator can be potentially infinite. * The sequence of values returned by the given iterator can be potentially infinite.
*
* @sample samples.collections.Sequences.Building.buildSequenceYieldAll
*/ */
public abstract suspend fun yieldAll(iterator: Iterator<T>) 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.
*
* @sample samples.collections.Sequences.Building.buildSequenceYieldAll
*/ */
public suspend fun yieldAll(elements: Iterable<T>) { public suspend fun yieldAll(elements: Iterable<T>) {
if (elements is Collection && elements.isEmpty()) return if (elements is Collection && elements.isEmpty()) return
@@ -79,8 +73,6 @@ public abstract class SequenceBuilder<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.
* *
* The sequence can be potentially infinite. * The sequence can be potentially infinite.
*
* @sample samples.collections.Sequences.Building.buildSequenceYieldAll
*/ */
public suspend fun yieldAll(sequence: Sequence<T>) = yieldAll(sequence.iterator()) public suspend fun yieldAll(sequence: Sequence<T>) = yieldAll(sequence.iterator())
} }