The comments for 'ReceiveChannel.receiveCatching' are confusing.

[CoenQian]

What do we have now?

ReceiveChannel.receiveCatching

I am confused by the comments marked with underlines:

1. If the Job of the current coroutine is cancelled or completed while this function is suspended, this function immediately resumes with a CancellationException.
2. If the job was cancelled while this function was suspended, it will not resume successfully.

When I try to translate them into Chinese, I feel like they're the same thing.

Keywords in two lines：

1. If job is cancelled or completed while this function is suspended, this function immediately resumes with a CancellationException.
2. If job was cancelled while this function was suspended, this function will not resume successfully.

The differences in keywords between the two lines of text are listed below:

line	job be cancelled	function be suspended	when	result
1st line	is	is	immediately	resume
2nd line	was	was	will	not resume

Thanks for your patience.

My question is "why the result of two lines are different?".

What should be instead?

From my pespectives, the result of two lines should be same.

Maybe designer of this function want to express like this:

1. this function is(was) suspended.
2. if the job invoking this function is(was) cancelled.
3. this function immediately(will) resume with CancellationException(not resume successfully).

"resume with CancellationException" means "not resume successfully"

But, it is difficult for developers from non-english speaking country or kotlin coroutine beginners.

There is a good case in Channel API.

When phrase "not resume successfully" was used in the current context, the designer used "throws a CancellationException" phrase instead of "resume with a CancellationException" phrase.

Why?
Even though I am an experienced kotlin coroutine user and have readed lots of source codes of coroutine library, i still felt confused when i read this comment for the first time.

As the result of two lines are different (resume vs not resume), i try to analyze what's different about the environments, of course, I failed.

When i asked other developers about this issue, they also faced the same confusion as i did.

Someone even interpreted the difference between "is" and "was" as one expressing a continuous process (ending in "ing") and the other expressing a completed result (ending in "ed").

So i suggest simplifying the comments like Channel's "Prompt cancellation guarantee"

Thanks for your patience again.

[CoenQian]

select has the same comment.