Fix the documentation for the Main dispatcher (#3879)

Author: dkhalanskyjb

README.md

@@ -26,7 +26,7 @@ suspend fun main() = coroutineScope {
 
 * [core](kotlinx-coroutines-core/README.md) — common coroutines across all platforms:
   * [launch] and [async] coroutine builders returning [Job] and [Deferred] light-weight futures with cancellation support;
-  * [Dispatchers] object with [Main][Dispatchers.Main] dispatcher for Android/Swing/JavaFx, and [Default][Dispatchers.Default] dispatcher for background coroutines;
+  * [Dispatchers] object with [Main][Dispatchers.Main] dispatcher for Android/Swing/JavaFx (which require the corresponding artifacts in runtime) and Darwin (included out of the box), and [Default][Dispatchers.Default] dispatcher for background coroutines;
   * [delay] and [yield] top-level suspending functions;
   * [Flow] — cold asynchronous stream with [flow][_flow] builder and comprehensive operator set ([filter], [map], etc);
   * [Channel], [Mutex], and [Semaphore] communication and synchronization primitives;
@@ -54,7 +54,7 @@ suspend fun main() = coroutineScope {
   * RxJava 2.x ([rxFlowable], [rxSingle], etc), and
   * RxJava 3.x ([rxFlowable], [rxSingle], etc), and
   * Project Reactor ([flux], [mono], etc).
-* [ui](ui/README.md) — modules that provide coroutine dispatchers for various single-threaded UI libraries:
+* [ui](ui/README.md) — modules that provide the [Main][Dispatchers.Main] dispatcher for various single-threaded UI libraries:
   * Android, JavaFX, and Swing.
 * [integration](integration/README.md) — modules that provide integration with various asynchronous callback- and future-based libraries:
   * Guava [ListenableFuture.await], and Google Play Services [Task.await];

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

@@ -31,13 +31,13 @@ public expect object Dispatchers {
      *   [`ServiceLoader`](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html).
      * - On JS it is equivalent to the [Default] dispatcher with [immediate][MainCoroutineDispatcher.immediate] support.
      * - On Native Darwin-based targets, it is a dispatcher backed by Darwin's main queue.
-     * - On other Native targets, it is a single-threaded dispatcher backed by a standalone worker.
+     * - On other Native targets, it is not available.
+     * - `Dispatchers.setMain` from the `kotlinx-coroutines-test` artifact can replace the main dispatcher with a mock one for testing.
      *
-     * In order to work with the `Main` dispatcher, the following artifact should be added to the project runtime dependencies:
+     * In order to work with the `Main` dispatcher on the JVM, the following artifact should be added to the project runtime dependencies:
      *  - `kotlinx-coroutines-android` — for Android Main thread dispatcher
      *  - `kotlinx-coroutines-javafx` — for JavaFx Application thread dispatcher
      *  - `kotlinx-coroutines-swing` — for Swing EDT dispatcher
-     *  - `kotlinx-coroutines-test` — for mocking the `Main` dispatcher in tests via `Dispatchers.setMain`
      */
     public val Main: MainCoroutineDispatcher