Extend the KDoc for `CoroutineStart`

[globsterg]

trafficstars

One of the pieces of #4133.

@fzhinkin, could you take a look?

[qwwdfsad]

By the way, here is our samples guide, might be useful: https://github.com/Kotlin/api-guidelines/blob/main/team_docs/samples.md

[qwwdfsad]

Seeing this demoted to a draft, is it correct that we are waiting for your next updates?

[globsterg]

Seeing this demoted to a draft, is it correct that we are waiting for your next updates?

The idea was to do this:

If at any point you'll decide that it's enough -- no worries. Feel free to open a draft PR, let us know, and we'll handle it from there

(The quote is from https://github.com/Kotlin/kotlinx.coroutines/issues/4133#issuecomment-2133172830)

[qwwdfsad]

Thanks for the reminder. We'll take it from here in that case!

Thanks for the bootstrapping work and revamp! 👍

[SebastianAigner]

Just one question re. idiomatic-ness of by lazy over lazy-start: Is code like this a concern? It does make sense with the sematics of lazy, but it's unclear to me if that's also what one might expect when reading such code for the first time.

val work by lazy { scope.async { println("Running!"); 5 } }
work.invokeOnCompletion { // this access will start the coroutine
    println("Completed!")
}
delay(5000)
println(work.await())

[dkhalanskyjb]

I'm not sure how realistic this concern is, but adding a line of text to warn people about it surely can't hurt. Done.