~ Doc for newSingleThreadContext/newFixedThreadPoolContext

kotlinx-coroutines-core/jvm/src/Executors.kt

@@ -39,8 +39,9 @@ public abstract class ExecutorCoroutineDispatcher: CoroutineDispatcher(), Closea
 /**
  * Converts an instance of [ExecutorService] to an implementation of [ExecutorCoroutineDispatcher].
  *
- * Note, that if the underlying executor throws [RejectedExecutionException] on
- * attempt to submit a continuation task (it typically happens on executor shutdown or when it uses limited queues),
+ * If the underlying executor throws [RejectedExecutionException] on
+ * attempt to submit a continuation task (it happens when [closing][ExecutorCoroutineDispatcher.close] the
+ * resulting dispatcher, on underlying executor [shutdown][ExecutorService.shutdown], or when it uses limited queues),
  * then the [Job] of the affected task is [cancelled][Job.cancel] and the task is submitted to the
  * [Dispatchers.IO], so that the affected coroutine can cleanup its resources and promptly complete.
  */
@@ -51,8 +52,9 @@ public fun ExecutorService.asCoroutineDispatcher(): ExecutorCoroutineDispatcher
 /**
  * Converts an instance of [Executor] to an implementation of [CoroutineDispatcher].
  *
- * Note, that if the underlying executor throws [RejectedExecutionException] on
- * attempt to submit a continuation task (it typically happens on executor shutdown or when it uses limited queues),
+ * If the underlying executor throws [RejectedExecutionException] on
+ * attempt to submit a continuation task (it happens when [closing][ExecutorCoroutineDispatcher.close] the
+ * resulting dispatcher, on underlying executor [shutdown][ExecutorService.shutdown], or when it uses limited queues),
  * then the [Job] of the affected task is [cancelled][Job.cancel] and the task is submitted to the
  * [Dispatchers.IO], so that the affected coroutine can cleanup its resources and promptly complete.
  */

kotlinx-coroutines-core/jvm/src/ThreadPoolDispatcher.kt

@@ -14,6 +14,11 @@ import kotlin.coroutines.*
  * **NOTE: The resulting [ExecutorCoroutineDispatcher] owns native resources (its thread).
  * Resources are reclaimed by [ExecutorCoroutineDispatcher.close].**
  *
+ * If the resulting dispatcher is [closed][ExecutorCoroutineDispatcher.close] and
+ * attempt to submit a continuation task is made,
+ * then the [Job] of the affected task is [cancelled][Job.cancel] and the task is submitted to the
+ * [Dispatchers.IO], so that the affected coroutine can cleanup its resources and promptly complete.
+ *
  * **NOTE: This API will be replaced in the future**. A different API to create thread-limited thread pools
  * that is based on a shared thread-pool and does not require the resulting dispatcher to be explicitly closed
  * will be provided, thus avoiding potential thread leaks and also significantly improving performance, due
@@ -35,6 +40,11 @@ public fun newSingleThreadContext(name: String): ExecutorCoroutineDispatcher =
  * **NOTE: The resulting [ExecutorCoroutineDispatcher] owns native resources (its threads).
  * Resources are reclaimed by [ExecutorCoroutineDispatcher.close].**
  *
+ * If the resulting dispatcher is [closed][ExecutorCoroutineDispatcher.close] and
+ * attempt to submit a continuation task is made,
+ * then the [Job] of the affected task is [cancelled][Job.cancel] and the task is submitted to the
+ * [Dispatchers.IO], so that the affected coroutine can cleanup its resources and promptly complete.
+ *
  * **NOTE: This API will be replaced in the future**. A different API to create thread-limited thread pools
  * that is based on a shared thread-pool and does not require the resulting dispatcher to be explicitly closed
  * will be provided, thus avoiding potential thread leaks and also significantly improving performance, due