From cc3f9ae7f0bd61df3f1e9a0bccbd145f2417c45b Mon Sep 17 00:00:00 2001 From: Yanis Batura Date: Mon, 5 Aug 2019 16:46:50 +0700 Subject: [PATCH 1/2] Flow.kt: fix typos and rephrase some expressions for better readability --- .../common/src/flow/Flow.kt | 56 +++++++++---------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/kotlinx-coroutines-core/common/src/flow/Flow.kt b/kotlinx-coroutines-core/common/src/flow/Flow.kt index bda326f85d..dd148e4520 100644 --- a/kotlinx-coroutines-core/common/src/flow/Flow.kt +++ b/kotlinx-coroutines-core/common/src/flow/Flow.kt @@ -22,7 +22,7 @@ import kotlin.coroutines.* * or [launchIn] operator that starts collection of the flow in the given scope. * They are applied to the upstream flow and trigger execution of all operations. * Execution of the flow is also called _collecting the flow_ and is always performed in a suspending manner - * without actual blocking. Terminal operator complete normally or exceptionally depending on successful or failed + * without actual blocking. Terminal operators complete normally or exceptionally depending on successful or failed * execution of all the flow operations in the upstream. The most basic terminal operator is [collect], for example: * * ``` @@ -37,10 +37,10 @@ import kotlin.coroutines.* * * By default, flows are _sequential_ and all flow operations are executed sequentially in the same coroutine, * with an exception for a few operations specifically designed to introduce concurrency into flow - * the execution such a [buffer] and [flatMapMerge]. See their documentation for details. + * execution such as [buffer] and [flatMapMerge]. See their documentation for details. * - * Flow interface does not carry information whether a flow is a truly a cold stream that can be collected repeatedly and - * triggers execution of the same code every time it is collected or if it is a hot stream that emits different + * The `Flow` interface does not carry information whether a flow truly is a cold stream that can be collected repeatedly and + * triggers execution of the same code every time it is collected, or if it is a hot stream that emits different * values from the same running source on each collection. However, conventionally flows represent cold streams. * Transitions between hot and cold streams are supported via channels and the corresponding API: * [channelFlow], [produceIn], [broadcastIn]. @@ -54,18 +54,18 @@ import kotlin.coroutines.* * * [flow { ... }][flow] builder function to construct arbitrary flows from * sequential calls to [emit][FlowCollector.emit] function. * * [channelFlow { ... }][channelFlow] builder function to construct arbitrary flows from - * potentially concurrent calls to [send][kotlinx.coroutines.channels.SendChannel.send] function. + * potentially concurrent calls to the [send][kotlinx.coroutines.channels.SendChannel.send] function. * * ### Flow constraints * - * All implementations of `Flow` interface must adhere to two key properties that are described in detail below: + * All implementations of the `Flow` interface must adhere to two key properties described in detail below: * * * Context preservation. * * Exception transparency. * * These properties ensure the ability to perform local reasoning about the code with flows and modularize the code - * in such a way so that upstream flow emitters can be developed separately from downstream flow collectors. - * A user of the flow does not needs to know implementation details of the upstream flows it uses. + * in such a way that upstream flow emitters can be developed separately from downstream flow collectors. + * A user of a flow does not need to be aware of implementation details of the upstream flows it uses. * * ### Context preservation * @@ -73,8 +73,8 @@ import kotlin.coroutines.* * it downstream, thus making reasoning about the execution context of particular transformations or terminal * operations trivial. * - * There is the only way to change the context of a flow: [flowOn][Flow.flowOn] operator, - * that changes the upstream context ("everything above the flowOn operator"). + * There is only one way to change the context of a flow: the [flowOn][Flow.flowOn] operator + * that changes the upstream context ("everything above the `flowOn` operator"). * For additional information refer to its documentation. * * This reasoning can be demonstrated in practice: @@ -97,7 +97,7 @@ import kotlin.coroutines.* * ``` * * From the implementation point of view, it means that all flow implementations should - * emit only from the same coroutine. + * only emit from the same coroutine. * This constraint is efficiently enforced by the default [flow] builder. * The [flow] builder should be used if flow implementation does not start any coroutines. * Its implementation prevents most of the development mistakes: @@ -114,27 +114,27 @@ import kotlin.coroutines.* * } * ``` * - * Use [channelFlow] if the collection and emission of the flow are to be separated into multiple coroutines. + * Use [channelFlow] if the collection and emission of a flow are to be separated into multiple coroutines. * It encapsulates all the context preservation work and allows you to focus on your * domain-specific problem, rather than invariant implementation details. * It is possible to use any combination of coroutine builders from within [channelFlow]. * - * If you are looking for the performance and are sure that no concurrent emits and context jumps will happen, - * [flow] builder alongside with [coroutineScope] or [supervisorScope] can be used instead: + * If you are looking for performance and are sure that no concurrent emits and context jumps will happen, + * the [flow] builder can be used alongside a [coroutineScope] or [supervisorScope] instead: * - Scoped primitive should be used to provide a [CoroutineScope]. * - Changing the context of emission is prohibited, no matter whether it is `withContext(ctx)` or - * builder argument (e.g. `launch(ctx)`). + * a builder argument (e.g. `launch(ctx)`). * - Collecting another flow from a separate context is allowed, but it has the same effect as - * [flowOn] operator on that flow, which is more efficient. + * applying the [flowOn] operator to that flow, which is more efficient. * * ### Exception transparency * * Flow implementations never catch or handle exceptions that occur in downstream flows. From the implementation standpoint * it means that calls to [emit][FlowCollector.emit] and [emitAll] shall never be wrapped into * `try { ... } catch { ... }` blocks. Exception handling in flows shall be performed with - * [catch][Flow.catch] operator and it is designed to catch only exception coming from upstream flow while passing - * all the downstream exceptions. Similarly, terminal operators like [collect][Flow.collect] - * throw any unhandled exception that occurs in its code or in upstream flows, for example: + * [catch][Flow.catch] operator and it is designed to only catch exceptions coming from upstream flows while passing + * all downstream exceptions. Similarly, terminal operators like [collect][Flow.collect] + * throw any unhandled exceptions that occur in their code or in upstream flows, for example: * * ``` * flow { emitData() } @@ -143,13 +143,13 @@ import kotlin.coroutines.* * .map { computeTwo(it) } * .collect { process(it) } // throws exceptions from process and computeTwo * ``` - * The same reasoning can be applied to [onCompletion] operator that is a declarative replacement for `finally` block. + * The same reasoning can be applied to the [onCompletion] operator that is a declarative replacement for the `finally` block. * - * Failure to adhere to the exception transparency requirement would result in strange behaviours that would make + * Failure to adhere to the exception transparency requirement can lead to strange behaviors which make * it hard to reason about the code because an exception in the `collect { ... }` could be somehow "caught" - * by the upstream flow, limiting the ability of local reasoning about the code. + * by an upstream flow, limiting the ability of local reasoning about the code. * - * Currently, flow infrastructure does not enforce exception transparency contracts, however, it might be enforced + * Currently, the flow infrastructure does not enforce exception transparency contracts, however, it might be enforced * in the future either at run time or at compile time. * * ### Reactive streams @@ -162,9 +162,9 @@ public interface Flow { * 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 flow interface directly is to extend [AbstractFlow]. - * To collect it into the specific collector, either `collector.emitAll(flow)` or `collect { ... }` extension - * should be used. Such limitation ensures that context preservation property is not violated and prevents most + * 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. */ @InternalCoroutinesApi @@ -172,8 +172,8 @@ public interface Flow { } /** - * Base class to extend to have a stateful implementation of the flow. - * It tracks all the properties required for context preservation and throws [IllegalStateException] + * The base class for stateful implementations of `Flow`. + * It tracks all the properties required for context preservation and throws an [IllegalStateException] * if any of the properties are violated. * * Example of the implementation: From e2d9b26cd5050c06d5c6044a2d10f53a9f5aea12 Mon Sep 17 00:00:00 2001 From: Yanis Batura Date: Mon, 5 Aug 2019 17:49:01 +0700 Subject: [PATCH 2/2] Rollback the addition of a definite article at start of `AbstractFlow` KDoc --- kotlinx-coroutines-core/common/src/flow/Flow.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/kotlinx-coroutines-core/common/src/flow/Flow.kt b/kotlinx-coroutines-core/common/src/flow/Flow.kt index dd148e4520..6d87c2b9aa 100644 --- a/kotlinx-coroutines-core/common/src/flow/Flow.kt +++ b/kotlinx-coroutines-core/common/src/flow/Flow.kt @@ -172,7 +172,7 @@ public interface Flow { } /** - * The base class for stateful implementations of `Flow`. + * Base class for stateful implementations of `Flow`. * It tracks all the properties required for context preservation and throws an [IllegalStateException] * if any of the properties are violated. *