Improve documentation

docs/basics.md

@@ -75,7 +75,8 @@ Here we are launching a new coroutine in the [GlobalScope], meaning that the lif
 coroutine is limited only by the lifetime of the whole application.  
 
 You can achieve the same result replacing
-`GlobalScope.launch { ... }` with `thread { ... }` and `delay(...)` with `Thread.sleep(...)`. Try it.
+`GlobalScope.launch { ... }` with `thread { ... }` and `delay(...)` with `Thread.sleep(...)`. 
+Try it (don't forget to import `kotlin.concurrent.thread`).
 
 If you start by replacing `GlobalScope.launch` by `thread`, the compiler produces the following error:
 

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

@@ -29,46 +29,29 @@ import kotlin.coroutines.*
  */
 public abstract class CoroutineDispatcher :
     AbstractCoroutineContextElement(ContinuationInterceptor), ContinuationInterceptor {
+
     /**
-     * Returns `true` if the execution shall be dispatched onto another thread.
+     * Returns `true` if the execution of the coroutine should be performed with [dispatch] method.
      * The default behavior for most dispatchers is to return `true`.
      *
-     * This method should never be used from general code, it is used only by `kotlinx.coroutines`
-     * internals and its contract with the rest of the API is an implementation detail.
-     *
-     * UI dispatchers _should not_ override `isDispatchNeeded`, but leave the default implementation that
-     * returns `true`. To understand the rationale beyond this recommendation, consider the following code:
+     * If this method returns `false`, the coroutine is resumed immediately in the current thread,
+     * potentially forming an event-loop to prevent stack overflows.
+     * The event loop is an advanced topic and its implications can be found in [Dispatchers.Unconfined] documentation.
      *
-     * ```kotlin
-     * fun asyncUpdateUI() = async(Dispatchers.Main) {
-     *     // do something here that updates something in UI
-     * }
-     * ```
+     * A dispatcher can override this method to provide a performance optimization and avoid paying a cost of an unnecessary dispatch.
+     * E.g. [MainCoroutineDispatcher.immediate] checks whether we are already in the required UI thread in this method and avoids
+     * an additional dispatch when it is not required.
      *
-     * When you invoke `asyncUpdateUI` in some background thread, it immediately continues to the next
-     * line, while the UI update happens asynchronously in the UI thread. However, if you invoke
-     * it in the UI thread itself, it will update the UI _synchronously_ if your `isDispatchNeeded` is
-     * overridden with a thread check. Checking if we are already in the UI thread seems more
-     * efficient (and it might indeed save a few CPU cycles), but this subtle and context-sensitive
-     * difference in behavior makes the resulting async code harder to debug.
+     * While this approach can be more efficient, it is not chosen by default to provide a consistent dispatching behaviour
+     * so that users won't observe unexpected and non-consistent order of events by default.
      *
-     * Basically, the choice here is between the "JS-style" asynchronous approach (async actions
-     * are always postponed to be executed later in the event dispatch thread) and "C#-style" approach
-     * (async actions are executed in the invoker thread until the first suspension point).
-     * While the C# approach seems to be more efficient, it ends up with recommendations like
-     * "use `yield` if you need to ....". This is error-prone. The JS-style approach is more consistent
-     * and does not require programmers to think about whether they need to yield or not.
-     *
-     * However, coroutine builders like [launch][CoroutineScope.launch] and [async][CoroutineScope.async] accept an optional [CoroutineStart]
-     * parameter that allows one to optionally choose the C#-style [CoroutineStart.UNDISPATCHED] behavior
-     * whenever it is needed for efficiency.
+     * Coroutine builders like [launch][CoroutineScope.launch] and [async][CoroutineScope.async] accept an optional [CoroutineStart]
+     * parameter that allows one to optionally choose the [undispatched][CoroutineStart.UNDISPATCHED] behavior to start coroutine immediately,
+     * but to be resumed only in the provided dispatcher.
      *
      * This method should generally be exception-safe. An exception thrown from this method
      * may leave the coroutines that use this dispatcher in the inconsistent and hard to debug state.
-     *
-     * **Note: This is an experimental api.** Execution semantics of coroutines may change in the future when this function returns `false`.
      */
-    @ExperimentalCoroutinesApi
     public open fun isDispatchNeeded(context: CoroutineContext): Boolean = true
 
     /**

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

@@ -65,7 +65,12 @@ public inline fun CoroutineExceptionHandler(crossinline handler: (CoroutineConte
  *     * if there is a [Job] in the context, then [Job.cancel] is invoked;
  *     * Otherwise, all instances of [CoroutineExceptionHandler] found via [ServiceLoader]
  *     * and current thread's [Thread.uncaughtExceptionHandler] are invoked.
- **/
+ *
+ * [CoroutineExceptionHandler] can be invoked from an arbitrary dispatcher used by coroutines in the current job hierarchy.
+ * For example, if one has a `MainScope` and launches children of the scope in main and default dispatchers, then exception handler can
+ * be invoked either in main or in default dispatcher thread regardless of
+ * which particular dispatcher coroutine that has thrown an exception used.
+ */
 public interface CoroutineExceptionHandler : CoroutineContext.Element {
     /**
      * Key for [CoroutineExceptionHandler] instance in the coroutine context.

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

@@ -66,7 +66,7 @@ public expect object Dispatchers {
      * Can print both "1 2 3" and "1 3 2", this is an implementation detail that can be changed.
      * But it is guaranteed that "Done" will be printed only when both `withContext` calls are completed.
      *
-     * Note that if you need your coroutine to be confined to a particular thread or a thread-pool after resumption,
+     * If you need your coroutine to be confined to a particular thread or a thread-pool after resumption,
      * but still want to execute it in the current call-frame until its first suspension, then you can use
      * an optional [CoroutineStart] parameter in coroutine builders like
      * [launch][CoroutineScope.launch] and [async][CoroutineScope.async] setting it to

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

@@ -18,6 +18,7 @@ public abstract class MainCoroutineDispatcher : CoroutineDispatcher() {
      *
      * Immediate dispatcher is safe from stack overflows and in case of nested invocations forms event-loop similar to [Dispatchers.Unconfined].
      * The event loop is an advanced topic and its implications can be found in [Dispatchers.Unconfined] documentation.
+     * The formed event-loop is shared with [Unconfined] and other immediate dispatchers, potentially overlapping tasks between them.
      *
      * Example of usage:
      * ```