Update the documentation for the Channel interface

[dkhalanskyjb]

Note: a major piece of terminology that's changed in this is that when a channel is closed with a cause, it's no longer called a "failed channel". I found it immensely confusing to have channelResult.isClosed that means "the channel is closed", but channelResult.isFailed that doesn't mean "the channel is failed". Also, every cancelled channel is a "failed" channel by the definition of being closed with a cause, which doesn't seem to be the intention. So, I suggest that we remove mentions of "failed channels" throughout and replace them with "closed with a cause". Luckily, it's only relevant in a limited number of places.

[lukellmann]

While reading through the updated documentation, I noticed that it doesn't clarify how onUndeliveredElement and BufferOverflow.DROP_OLDEST/BufferOverflow.DROP_LATEST interact (i.e. do dropped elements get passed to the onUndeliveredElement function). It is only briefly mentioned in the example of the Channel factory function ("The dropped resources were closed by the channel itself").

I also think the behavior of SendChannel and ReceiveChannel functions when the channel was cancelled could be described in more detail. Instead of only mentioning in the documentation of ReceiveChannel.cancel that other functions will throw CancellationExceptions, this could be clarified in the documentation of each function this applies to.

[lukellmann]

This sentence seems to miss an "or" (or is off in some other way).

[lukellmann]

Explicitly mentioning the false for channels that are closed for receive was clearer to me.

[dkhalanskyjb]

For me, it's the opposite, because the second sentence used to contradict the first one.

[lukellmann]

Sure, it's very subjective :)

[lukellmann]

Suggested change

	* then [send] will rethrow the exact object that was passed to [close].
	* then [send] will rethrow the exact exception that was passed to [close].

ReceiveChannel.receive uses "exception" instead of "object" and i think that's clearer.

[dkhalanskyjb]

I was trying to evoke the feeling that the same runtime object (not just an exception with the same class etc.) was going to be thrown. Reworded.

[kjnsn]

Honestly, "exception" is much clearer to me

[lukellmann]

It might be simpler to say something like "... if and only if ..." (stating the logical equivalence and not the implication in both directions).

[dkhalanskyjb]

Math-style succinctness is not a good friend when designing APIs or writing documentation for general use. As an example, look at how vacuous truth caused a confusion: https://www.reddit.com/r/Kotlin/comments/q2llvo/what_should_a_function_called/

[lukellmann]

Makes sense, I didn't think about that.

[lukellmann]

This exception might also be thrown when the result represents a failed operation on a channel that isn't closed yet. So the new exception message is a bit misleading.

[lukellmann]

Note: a major piece of terminology that's changed in this is that when a channel is closed with a cause, it's no longer called a "failed channel".

The term is still used here:

• CoroutineScope.produce (twice)
• CoroutineScope.actor
• ChannelsTest.testToListOnFailedChannel
• ReceiveChannel.receiveOrNull
• ReceiveChannel.receiveOrNull (in Channels.common.kt).

[dkhalanskyjb]

I also think the behavior of SendChannel and ReceiveChannel functions when the channel was cancelled could be described in more detail. Instead of only mentioning in the documentation of ReceiveChannel.cancel that other functions will throw CancellationExceptions, this could be clarified in the documentation of each function this applies to.

Semantically, cancel does not put the channel into a "cancelled" state, it only closes the channel with a CancellationException and consumes the elements, and it looks like every operation that throws when the channel is closed already mentions this.

[lukellmann]

Sure, it's very subjective :)

[lukellmann]

Makes sense, I didn't think about that.

[lukellmann]

Semantically, cancel does not put the channel into a "cancelled" state, it only closes the channel with a CancellationException and consumes the elements, and it looks like every operation that throws when the channel is closed already mentions this.

Oh, I didn't think about it that way (probably because CancellationExceptions are special). Yes, seems alright.

[kjnsn]

Semantically, cancel does not put the channel into a "cancelled" state, it only closes the channel with a CancellationException and consumes the elements, and it looks like every operation that throws when the channel is closed already mentions this.

I think this could be clarified. When trying to read from a closed channel it doesn't throw a CancellationException (at least from my experience).

[dkhalanskyjb]

When trying to read from a closed channel it doesn't throw a CancellationException

@kjnsn, close the channel with a CancellationException (like cancel does), and it will:

import kotlinx.coroutines.*
import kotlinx.coroutines.channels.*

fun main() {
    runBlocking {
        val c = Channel<Int>()
        c.close(CancellationException())
        println(runCatching { c.receive() }) // CancellationException
    }
}

Runnable version; https://pl.kotl.in/vutYqCO0B

[qwwdfsad]

Superb revamp 👍

I have a few minor comments and it will be good to go

[qwwdfsad]

Awesome!