Extend the KDoc for some channel APIs

[globsterg]

One of the pieces of #4133.

Each file can be reviewed independently (and changes to other files will be added later). I'm keeping this a single pull request to avoid spamming.

[qwwdfsad]

well done!

[qwwdfsad]

yield is redundant and rather confusing here, let's avoid that?

[qwwdfsad]

Maybe invoke it in-place instead of a single coroutine?

[qwwdfsad]

Reading this, it seems like the example is mixing two concepts: one is about consuming, and the other about undelivered clean up (which we don't consider as "processed", it has a different meaning).

Maybe something more straightforward?
Like the following (outline, haven't tried to compile it):

val producer = produce {
    var currentElement = 0
    try {
        while(true) {
            send(currentElement++)
        }
    } finally {
        println("Cancelled after: $currentElement")
    }
}

consumeFirst { ... }

It's deterministic, more trivial and straightforward. WDYT?

[globsterg]

Yes, good point. The point of consume seems to be just notifying the producer that there are no more consumers. I noticed that consume is a reliable way not to miss any elements and became too fixated on that, but this really is a just side effect.

[qwwdfsad]

Let's make it a bit less ambigous? "Calling toList on channels that are not closed" or something like that

[qwwdfsad]

Let's use produce for that?
Esp. here, where finally block is required otherwise

[globsterg]

I found produce too high-level and thought that using it could detract from the point of the sample. Is it wrong? Is produce common knowledge and part of any coroutine user's toolkit?

[dkhalanskyjb]

produce is more high-level, but it's also the idiomatic way to create a producer coroutine, so it's worth mentioning. It's true that it may overwhelm the reader, but we can probably work around this by adding extensive comments.

[qwwdfsad]

Nice catch!

[qwwdfsad]

Thanks! All good except one redundant example

[qwwdfsad]

This example is irrelevant to produce documentation, it's Channel doc that should explain that

[dkhalanskyjb]

I beg to differ. produce calls the Channel function, passing a null to onUndeliveredElement. This is produce's implementation detail (that we must document) and not the Channel's.

[dkhalanskyjb]

Or do you mean the snippet below? It's not an example, it's an explanation of how to approximate the produce above with an explicitly created channel. Would it work for you if I explain this in text explicitly?

[qwwdfsad]

I mean the snippet itself, yes. I would say it's sufficient to refer to onUndeliveredElement where it has more comprehensive explanation and self-sufficient example

[dkhalanskyjb]

Non-obvious things this snippet highlights:

• Where the onUndeliveredParameter is (you can't refer to it directly, the user has to chase the docs)
• finally with the close in the coroutine

[qwwdfsad]

Where the onUndeliveredParameter is (you can't refer to it directly, the user has to chase the docs)

• "If this is unsuitable, please create a [Channel] manually and pass the onUndeliveredElement callback to the constructor: [Channel(onUndeliveredElement = ...)]]Channel]" probably will suffice.

I realize that using it might be less obvious, but still believe it's not the produce's documentation job to explain that