Repository: Kotlin/kotlinx.coroutines
File: kotlinx-coroutines-core/common/src/channels/Produce.kt (Kotlin)

Code before:
 * ### Coroutine context
 *
 * The coroutine context is inherited from this [CoroutineScope]. Additional context elements can be specified with the [context] argument.
 * If the context does not have any dispatcher or other [ContinuationInterceptor], then [Dispatchers.Default] is used.
 * The parent job is inherited from the [CoroutineScope] as well, but it can also be overridden
 * with a corresponding [context] element.
 *
 * See [newCoroutineContext] for a description of debugging facilities available for newly created coroutines.
 *
 * ### Undelivered elements
 *
 * Some values that [produce] creates may be lost:
 *
 * ```
 * val channel = produce(Dispatchers.Default, capacity = 5) {
 *     repeat(100) {
 *         send(it)
 *         println("Sent $it")
 *     }
 * }
 * channel.cancel() // no elements can be received after this!
 * ```
 *
 * There is no way to recover these lost elements.
 * If this is unsuitable, please create a [Channel] manually and pass the `onUndeliveredElement` callback to the
 * constructor.
 *
 * ```
 * fun Int.close() {
 *     println("Closing $this")
 * }
 * val channel = Channel<Int>(5, onUndeliveredElement = Int::close)
 * launch(start = CoroutineStart.UNDISPATCHED) {
 *     try {
 *         repeat(100) {
 *             channel.send(it)
 *             println("Sent $it")
 *         }
 *     } finally {
 *         channel.close() // don't forget to close the channel
 *     }
 * }
 * channel.cancel() // the elements in the buffer will be cleaned up
 * ```
 *
 * ### Usage example
 *
 * ```
 * /* Generate random integers until we find the square root of 9801.
 *    To calculate whether the given number is that square root,
 *    use several coroutines that separately process these integers.

Review comment (suggestion):
This example is irrelevant to `produce` documentation, it's `Channel` doc that should explain that

Code after:
 * ### Coroutine context
 *
 * The coroutine context is inherited from this [CoroutineScope]. Additional context elements can be specified with the [context] argument.
 * If the context does not have any dispatcher or other [ContinuationInterceptor], then [Dispatchers.Default] is used.
 * The parent job is inherited from the [CoroutineScope] as well, but it can also be overridden
 * with a corresponding [context] element.
 *
 * See [newCoroutineContext] for a description of debugging facilities available for newly created coroutines.
 *
 * ### Undelivered elements
 *
 * Some values that [produce] creates may be lost:
 *
 * ```
 * val channel = produce(Dispatchers.Default, capacity = 5) {
 *     repeat(100) {
 *         send(it)
 *         println("Sent $it")
 *     }
 * }
 * channel.cancel() // no elements can be received after this!
 * ```
 *
 * There is no way to recover these lost elements.
 * If this is unsuitable, please create a [Channel] manually and pass the `onUndeliveredElement` callback to the
 * constructor: [Channel(onUndeliveredElement = ...)][Channel].
 *
 * ### Usage example
 *
 * ```
 * /* Generate random integers until we find the square root of 9801.
 *    To calculate whether the given number is that square root,
 *    use several coroutines that separately process these integers.
 *    Alternatively, we may randomly give up during value generation.
 *    `produce` is used to generate the integers and put them into a
 *    channel, from which the square-computing coroutines take them. */
 * val parentScope = CoroutineScope(SupervisorJob())
 * val channel = parentScope.produce<Int>(
 *     Dispatchers.IO,
 *     capacity = 16 // buffer of size 16
 * ) {
 *     // this code will run on Dispatchers.IO
 *     while (true) {
 *         val request = run {
 *             // simulate waiting for the next request
 *             delay(5.milliseconds)
 *             val randomInt = Random.nextInt(-1, 100)
 *             if (randomInt == -1) {
 *                 // external termination request received
 *                 println("Producer: no longer accepting requests")
 *                 return@produce