Update Flow.collect documentation (Kotlin#3085)

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