Minor Improvements to the documentation and code comments #4346
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Refined the wording for better readability and correctness. Added missing articles and restructured sentences to avoid splitting the infinitive.
Corrected verb forms for grammatical accuracy.
Added missing commas for grammatical correctness. Ensured proper separation between clauses to enhance sentence flow.
…oaches Refined the explanation of cancellable computation strategies for greater clarity and precision. - Expanded details on periodically invoking suspending functions. - Reworded sentence structure to improve readability. - Included explicit references to `ensureActive` to provide better guidance on checking cancellation status.
…ion for quick reference.
Revised grammatical inconsistencies for improved clarity and correctness. - Changed `well-behaving` to `well-behaved` to use the correct past participle form in a compound adjective. - Remove an unnecessary "a" from "any kind of a communication channel" to ensure proper usage.
…yling Applied a note style to improve visibility and ensure that important information stands out more clearly in the documentation.
…raction with coroutineScope example - Improve readability of async and coroutineScope explanation - Simplify language while maintaining technical accuracy - Restructure sentence flow for better comprehension
…ext switching Refined the explanation of coroutine context switching for better clarity and comprehension. - Expanded details on `runBlocking` with an explicit context to highlight its controlled execution benefits. - Clarified how `withContext` suspends a coroutine and switches execution context while ensuring smooth reversion. - Structured the explanation for improved readability and understanding.
Refined the documentation to enhance clarity and structure. - Improved sentence flow and paragraph formatting for better readability. - Reformatted explanations of job states and transitions for improved comprehension. - Enhanced descriptions of cancellation behavior to clarify distinctions between normal cancellation and failure.
Refined the documentation for `completeExceptionally` to enhance clarity and correctness. - Improved sentence structure for better readability. - Clarified the transition states of a job when completed exceptionally. - Fixed grammatical inconsistencies, such as "its responsibility" → "It is the responsibility." - Enhanced explanation of how children receive `CancellationException` for diagnostic purposes.
- Refined the explanation of `CoroutineScope` and its role in managing coroutine lifecycles. - Adjusted phrasing to provide a smoother flow and better comprehension.
…inconsistencies and enhanced the flow
…o the appropriate method
…ope() Added missing articles for improved grammatical accuracy and readability. Included a direct link to the `CoroutineScope()` function to enhance navigation and accessibility for developers.
…ng for better clarity
dkhalanskyjb
requested changes
Feb 11, 2025
| Because the [async] coroutine builder is defined as an extension on [CoroutineScope], we need to have it in the | ||
| scope and that is what the [coroutineScope][_coroutineScope] function provides: | ||
| Let's refactor the [Concurrent using async](#concurrent-using-async) example into a function that runs | ||
| `doSomethingUsefulOne` and `doSomethingUsefulTwo` concurrently and returns their combined results. |
There was a problem hiding this comment.
But why? It's not the example that's being extracted; instead, a function is extracted from a part of the example.
There was a problem hiding this comment.
I believe both approaches are valid. If we look further down, there is a code block that takes the entire example and modifies the code, which can be considered a refactor.
| * | ||
| * Do not replace `GlobalScope.launch { ... }` with `CoroutineScope().launch { ... }` constructor function call. | ||
| * The latter has the same pitfalls as `GlobalScope`. See [CoroutineScope] documentation on the intended usage of | ||
| * `CoroutineScope()` constructor function. | ||
| * [CoroutineScope()](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope.html) |
There was a problem hiding this comment.
Let's stick to KDoc referring to other KDoc entries when possible, without sending the reader to the Internet.
There was a problem hiding this comment.
@dkhalanskyjb Sadly, KDoc is unable to locate the function's reference in this instance. I had to use a link as a result. Because, in my opinion, having it in the documentation is more valuable. Even if it is just a link, it is better than none at all. Because I was searching for it, it took me a while to find it when I was reading the documentation.
There was a problem hiding this comment.
Yes, I understand the problem you are trying to solve. It's a known issue with KDoc and will be mitigated in KDoc. I've asked the KDoc team, and they do actually intend to implement a fix in the foreseeable future.
The downside of requiring the Internet is that some clients of kotlinx.coroutines are airgapped, and also, many people use older versions of coroutines, and the information in the latest API reference may just not be correct for them.
| * - **[CompletableJob]** is created with a `Job()` factory function. | ||
| * - A **coroutine job** is created with the [launch][CoroutineScope.launch] coroutine builder. | ||
| * It runs a specified block of code and completes upon completion of this block. | ||
| * - **[CompletableJob]** is created with a [Job()](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job.html) |
There was a problem hiding this comment.
Ditto: links to the Internet are not the way to fix incorrect resolution of references.
There was a problem hiding this comment.
@dkhalanskyjb Here, the same thing happened. like in the function CoroutineScope().
Expanded the explanation of `withContext` to provide a more precise understanding of its behavior. - Clarified that `withContext` only suspends and switches context if the specified context differs from the current one. - Explained how `CoroutineDispatcher` influences context switching, requiring additional dispatches. - Improved wording for better readability and comprehension.
…g coroutine execution Revised phrasing to reflect that coroutines are continuously launched throughout the application's lifecycle. - Changed "we launched" to "launching" to better align with present continuous tense, emphasizing ongoing behavior.
…s get cancelled Added "All" to stress that every coroutine is cancelled, highlighting this crucial aspect of coroutine behavior.
Corrected "a different threads" to "different threads" for grammatical accuracy.
Restored emphasis on "whole application lifetime" to clearly indicate that top-level coroutines span from application start to termination.
…tions Reverted "or" to its original placement to correctly reflect that a job remains active until either the coroutine completes or `CompletableJob.complete` is called.
…uracy Fixed an extra "on" left over after the change to ensure proper sentence structure and readability.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This pull request improves the documentation and code comments in the repository.
The changes include:
cancellation-and-timeouts.mddocument.composing-suspending-functions.md.coroutine-context-and-dispatchers.md.CompletableJob.kt,CoroutineScope.kt,Job.kt,Supervisor.kt,Yield.kt, andThreadContextElement.kt.