From bec65691f259f72ba86facc5631e12417cc741e5 Mon Sep 17 00:00:00 2001 From: Vsevolod Tolstopyatov Date: Wed, 15 Dec 2021 00:26:50 +0300 Subject: [PATCH] Update Flow.collect documentation --- .../common/src/flow/Flow.kt | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/kotlinx-coroutines-core/common/src/flow/Flow.kt b/kotlinx-coroutines-core/common/src/flow/Flow.kt index 90b12f7fa2..4ee0ac7c28 100644 --- a/kotlinx-coroutines-core/common/src/flow/Flow.kt +++ b/kotlinx-coroutines-core/common/src/flow/Flow.kt @@ -172,17 +172,25 @@ import kotlin.coroutines.* * * **The `Flow` interface is not stable for inheritance in 3rd party libraries**, as new methods * might be added to this interface in the future, but is stable for use. + * * Use the `flow { ... }` builder function to create an implementation, or extend [AbstractFlow]. + * These implementations ensure that the context preservation property is not violated, and prevent most + * of the developer mistakes related to concurrency, inconsistent flow dispatchers, and cancellation. */ public interface Flow { + /** * Accepts the given [collector] and [emits][FlowCollector.emit] values into it. - * This method should never be implemented or used directly. * - * The only way to implement the `Flow` interface directly is to extend [AbstractFlow]. - * To collect it into a specific collector, either `collector.emitAll(flow)` or `collect { ... }` extension - * should be used. Such limitation ensures that the context preservation property is not violated and prevents most - * of the developer mistakes related to concurrency, inconsistent flow dispatchers and cancellation. + * This method can be used along with SAM-conversion of [FlowCollector]: + * ``` + * myFlow.collect { value -> println("Collected $value") + * ``` + * + * ### Method inheritance + * + * To ensure the context preservation property, it is not recommended implementing this method directly. + * Instead, [AbstractFlow] can be used as the base type to properly ensure flow's properties. */ public suspend fun collect(collector: FlowCollector) }