Update Flow.collect documentation (#3085)

Author: qwwdfsad

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<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>)
 }