Improve Flow documentation (Kotlin#3127)

Co-authored-by: dkhalanskyjb <[email protected]>

Author: 2 people

kotlinx-coroutines-core/common/src/flow/Flow.kt

@@ -108,7 +108,7 @@ import kotlin.coroutines.*
  * val myFlow = flow {
  *    // GlobalScope.launch { // is prohibited
  *    // launch(Dispatchers.IO) { // is prohibited
- *    // withContext(CoroutineName("myFlow")) // is prohibited
+ *    // withContext(CoroutineName("myFlow")) { // is prohibited
  *    emit(1) // OK
  *    coroutineScope {
  *        emit(2) // OK -- still the same coroutine
@@ -191,6 +191,9 @@ public interface Flow<out T> {
      *
      * 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.
+     *
+     * All default flow implementations ensure context preservation and exception transparency properties on a best-effort basis
+     * and throw [IllegalStateException] if a violation was detected.
      */
     public suspend fun collect(collector: FlowCollector<T>)
 }

kotlinx-coroutines-core/common/src/flow/SharedFlow.kt

@@ -115,7 +115,7 @@ import kotlin.native.concurrent.*
  * ### Implementation notes
  *
  * Shared flow implementation uses a lock to ensure thread-safety, but suspending collector and emitter coroutines are
- * resumed outside of this lock to avoid dead-locks when using unconfined coroutines. Adding new subscribers
+ * resumed outside of this lock to avoid deadlocks when using unconfined coroutines. Adding new subscribers
  * has `O(1)` amortized cost, but emitting has `O(N)` cost, where `N` is the number of subscribers.
  *
  * ### Not stable for inheritance
@@ -132,13 +132,13 @@ public interface SharedFlow<out T> : Flow<T> {
 
     /**
      * Accepts the given [collector] and [emits][FlowCollector.emit] values into it.
-     * This method should never be used directly. To emit values from a shared flow into a specific collector, either `collector.emitAll(flow)` or `collect { ... }` extension
-     * should be used.
+     * To emit values from a shared flow into a specific collector, either `collector.emitAll(flow)` or `collect { ... }`
+     * SAM-conversion can be used.
      *
      * **A shared flow never completes**. A call to [Flow.collect] or any other terminal operator
      * on a shared flow never completes normally.
      *
-     * @see [Flow.collect]
+     * @see [Flow.collect] for implementation and inheritance details.
      */
     override suspend fun collect(collector: FlowCollector<T>): Nothing
 }