Clarify documentation for IO dispatcher (#2286)

Fixes #2272

1 files changed, 5 insertions, 1 deletions

diff --git a/kotlinx-coroutines-core/jvm/src/Dispatchers.kt b/kotlinx-coroutines-core/jvm/src/Dispatchers.kt
index 8cd3bb1b..8033fb38 100644
--- a/kotlinx-coroutines-core/jvm/src/Dispatchers.kt
+++ b/kotlinx-coroutines-core/jvm/src/Dispatchers.kt
@@ -97,7 +97,7 @@ public actual object Dispatchers {
      * The [CoroutineDispatcher] that is designed for offloading blocking IO tasks to a shared pool of threads.
      *
      * Additional threads in this pool are created and are shutdown on demand.
-     * The number of threads used by this dispatcher is limited by the value of
+     * The number of threads used by tasks in this dispatcher is limited by the value of
      * "`kotlinx.coroutines.io.parallelism`" ([IO_PARALLELISM_PROPERTY_NAME]) system property.
      * It defaults to the limit of 64 threads or the number of cores (whichever is larger).
      *
@@ -106,9 +106,13 @@ public actual object Dispatchers {
      * If you need a higher number of parallel threads,
      * you should use a custom dispatcher backed by your own thread pool.
      *
+     * ### Implementation note
+     *
      * This dispatcher shares threads with a [Default][Dispatchers.Default] dispatcher, so using
      * `withContext(Dispatchers.IO) { ... }` does not lead to an actual switching to another thread —
      * typically execution continues in the same thread.
+     * As a result of thread sharing, more than 64 (default parallelism) threads can be created (but not used)
+     * during operations over IO dispatcher.
      */
     @JvmStatic
     public val IO: CoroutineDispatcher = DefaultScheduler.IO