Update Flow.collect documentation (#3085)
diff --git a/kotlinx-coroutines-core/common/src/flow/Flow.kt b/kotlinx-coroutines-core/common/src/flow/Flow.kt
index 90b12f7..4ee0ac7 100644
--- a/kotlinx-coroutines-core/common/src/flow/Flow.kt
+++ b/kotlinx-coroutines-core/common/src/flow/Flow.kt
@@ -172,17 +172,25 @@
*
* **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<out T> {
+
/**
* 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<T>)
}
