~ Updated asCoroutineDispatcher docs

Author: elizarov

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

@@ -38,13 +38,23 @@ public abstract class ExecutorCoroutineDispatcher: CoroutineDispatcher(), Closea
 
 /**
  * Converts an instance of [ExecutorService] to an implementation of [ExecutorCoroutineDispatcher].
+ *
+ * Note, that if the underlying executor uses limited queues and throws [RejectedExecutionException] on
+ * attempt to submit a task, then the [Job] of the affected task is [cancelled][Job.cancel] and the
+ * task is submitted to the default single-threaded executor, so that the affected coroutine can cleanup its
+ * resources and promptly complete.
  */
 @JvmName("from") // this is for a nice Java API, see issue #255
 public fun ExecutorService.asCoroutineDispatcher(): ExecutorCoroutineDispatcher =
     ExecutorCoroutineDispatcherImpl(this)
 
 /**
  * Converts an instance of [Executor] to an implementation of [CoroutineDispatcher].
+ *
+ * Note, that if the underlying executor uses limited queues and throws [RejectedExecutionException] on
+ * attempt to submit a task, then the [Job] of the affected task is [cancelled][Job.cancel] and the
+ * task is submitted to the default single-threaded executor, so that the affected coroutine can cleanup its
+ * resources and promptly complete.
  */
 @JvmName("from") // this is for a nice Java API, see issue #255
 public fun Executor.asCoroutineDispatcher(): CoroutineDispatcher =