Skip to content

Fix documentation comments in CancellableContinutation.kt #4447

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 4, 2025
Merged

Fix documentation comments in CancellableContinutation.kt #4447

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c9daa91
Update documentation comments in CancellableContinuation.kt
kaseken Jun 2, 2025
85fe6bc
Fix the format of the table in CancellableContinuation.kt
kaseken Jun 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions kotlinx-coroutines-core/common/src/CancellableContinuation.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ import kotlin.coroutines.intrinsics.*
* An instance of `CancellableContinuation` can only be obtained by the [suspendCancellableCoroutine] function.
* The interface itself is public for use and private for implementation.
*
* A typical usages of this function is to suspend a coroutine while waiting for a result
* A typical usage of this function is to suspend a coroutine while waiting for a result
* from a callback or an external source of values that optionally supports cancellation:
*
* ```
Expand All @@ -45,7 +45,7 @@ import kotlin.coroutines.intrinsics.*
* [CancellableContinuation] allows concurrent invocations of the [cancel] and [resume] pair, guaranteeing
* that only one of these operations will succeed.
* Concurrent invocations of [resume] methods lead to a [IllegalStateException] and are considered a programmatic error.
* Concurrent invocations of [cancel] methods is permitted, and at most one of them succeeds.
* Concurrent invocations of [cancel] methods are permitted, and at most one of them succeeds.
*
* ### Prompt cancellation guarantee
*
Expand Down Expand Up @@ -84,11 +84,11 @@ import kotlin.coroutines.intrinsics.*
*
* A cancellable continuation has three observable states:
*
* | **State** | [isActive] | [isCompleted] | [isCancelled] |
* | ----------------------------------- | ---------- | ------------- | ------------- |
* | _Active_ (initial state) | `true` | `false` | `false` |
* | _Resumed_ (final _completed_ state) | `false` | `true` | `false` |
* | _Canceled_ (final _completed_ state)| `false` | `true` | `true` |
* | **State** | [isActive] | [isCompleted] | [isCancelled] |
* | ------------------------------------ | ---------- | ------------- | ------------- |
* | _Active_ (initial state) | `true` | `false` | `false` |
* | _Resumed_ (final _completed_ state) | `false` | `true` | `false` |
* | _Cancelled_ (final _completed_ state)| `false` | `true` | `true` |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The table is inconsistently formatted after this change.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the catch! The table style has been corrected.
85fe6bc

*
* For a detailed description of each state, see the corresponding properties' documentation.
*
Expand Down Expand Up @@ -188,7 +188,7 @@ public interface CancellableContinuation<in T> : Continuation<T> {
* Internal function that setups cancellation behavior in [suspendCancellableCoroutine].
* It's illegal to call this function in any non-`kotlinx.coroutines` code and
* such calls lead to undefined behaviour.
* Exposed in our ABI since 1.0.0 withing `suspendCancellableCoroutine` body.
* Exposed in our ABI since 1.0.0 within `suspendCancellableCoroutine` body.
*
* @suppress **This is unstable API and it is subject to change.**
*/
Expand Down