Fix the documentation for the Main dispatcher (Kotlin#3879)

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