Reword docs for the Reactor integration

Author: dkhalanskyjb

reactive/kotlinx-coroutines-reactor/src/Convert.kt

@@ -41,8 +41,8 @@ public fun <T> Deferred<T?>.asMono(context: CoroutineContext): Mono<T> = mono(co
 /**
  * Converts a stream of elements received from the channel to the hot reactive flux.
  *
- * Every subscriber receives values from this channel in **fan-out** fashion. If the are multiple subscribers,
- * they'll receive values in round-robin way.
+ * Every subscriber receives values from this channel in a **fan-out** fashion. If the are multiple subscribers,
+ * they'll receive values in a round-robin way.
  * @param context -- the coroutine context from which the resulting flux is going to be signalled
  */
 @Deprecated(message = "Deprecated in the favour of consumeAsFlow()",

reactive/kotlinx-coroutines-reactor/src/Flux.kt

@@ -11,23 +11,24 @@ import org.reactivestreams.*
 import reactor.core.*
 import reactor.core.publisher.*
 import reactor.util.context.*
+import java.lang.IllegalArgumentException
 import kotlin.coroutines.*
 
 /**
- * Creates cold reactive [Flux] that runs a given [block] in a coroutine.
+ * Creates a cold reactive [Flux] that runs a given [block] in a coroutine.
  * Every time the returned flux is subscribed, it starts a new coroutine in the specified [context].
- * Coroutine emits ([Subscriber.onNext]) values with `send`, completes ([Subscriber.onComplete])
- * when the coroutine completes or channel is explicitly closed and emits error ([Subscriber.onError])
- * if coroutine throws an exception or closes channel with a cause.
- * Unsubscribing cancels running coroutine.
+ * Coroutine emits ([Subscriber.onNext]) values with [send][ProducerScope.send], completes ([Subscriber.onComplete])
+ * when the coroutine completes, or the channel is explicitly closed and emits an error ([Subscriber.onError])
+ * if the coroutine throws an exception or closes the channel with a cause.
+ * Unsubscribing cancels the running coroutine.
  *
- * Invocations of `send` are suspended appropriately when subscribers apply back-pressure and to ensure that
- * `onNext` is not invoked concurrently.
- *
- * Method throws [IllegalArgumentException] if provided [context] contains a [Job] instance.
+ * Invocations of [send][ProducerScope.send] are suspended appropriately when subscribers apply back-pressure and to
+ * ensure that [onNext][Subscriber.onNext] is not invoked concurrently.
  *
  * **Note: This is an experimental api.** Behaviour of publishers that work as children in a parent scope with respect
  *        to cancellation and error handling may change in the future.
+ *
+ * @throws IllegalArgumentException if the provided [context] contains a [Job] instance.
  */
 @ExperimentalCoroutinesApi
 public fun <T> flux(

reactive/kotlinx-coroutines-reactor/src/ReactorContext.kt

@@ -10,14 +10,16 @@ import kotlin.coroutines.*
 import kotlinx.coroutines.reactive.*
 
 /**
- * Wraps Reactor's [Context] into [CoroutineContext] element for seamless integration Reactor and kotlinx.coroutines.
- * [Context.asCoroutineContext] is defined to add Reactor's [Context] elements as part of [CoroutineContext].
- * Coroutine context element that propagates information about Reactor's [Context] through coroutines.
+ * Wraps Reactor's [Context] into a [CoroutineContext] element for seamless integration between
+ * Reactor and kotlinx.coroutines.
+ * [Context.asCoroutineContext] is defined to place Reactor's [Context] elements into a [CoroutineContext],
+ * which can be used to propagate the information about Reactor's [Context] through coroutines.
  *
- * This context element is implicitly propagated through subscriber's context by all Reactive integrations, such as [mono], [flux],
- * [Publisher.asFlow][asFlow], [Flow.asPublisher][asPublisher] and [Flow.asFlux][asFlux].
- * Functions that subscribe to the reactive stream (e.g. [Publisher.awaitFirst][kotlinx.coroutines.reactive.awaitFirst])
- * also propagate the [ReactorContext] to the subscriber's [Context].
+ * This context element is implicitly propagated through subscriber's context by all Reactive integrations,
+ * such as [mono], [flux], [Publisher.asFlow][asFlow], [Flow.asPublisher][asPublisher] and [Flow.asFlux][asFlux].
+ * Functions that subscribe to the reactive stream
+ * (e.g. [Publisher.awaitFirst][kotlinx.coroutines.reactive.awaitFirst]), too, propagate [ReactorContext]
+ * to the subscriber's [Context].
  **
  * ### Examples of Reactive context integration.
  *