Clarify documentation around Dispatcher.IO parallelism

Author: wojtek-kalicinski

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

@@ -101,6 +101,11 @@ public actual object Dispatchers {
      * "`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).
      *
+     * Moreover, the maximum configurable number of threads is capped by the
+     * `kotlinx.coroutines.scheduler.max.pool.size` system property.
+     * If you need a higher number of parallel threads,
+     * you should use a custom dispatcher backed by your own thread pool.
+     *
      * 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.