Better documentation on CoroutineStart parameter

Author: elizarov

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Builders.kt

@@ -32,7 +32,8 @@ import kotlin.coroutines.experimental.intrinsics.suspendCoroutineOrReturn
  * The [context][CoroutineScope.context] of the parent coroutine from its [scope][CoroutineScope] may be used,
  * in which case the [Job] of the resulting coroutine is a child of the job of the parent coroutine.
  *
- * By default, the coroutine is immediately started.
+ * By default, the coroutine is immediately scheduled for execution.
+ * Other options can be specified via `start` parameter. See [CoroutineStart] for details.
  * An optional [start] parameter can be set to [CoroutineStart.LAZY] to start coroutine _lazily_. In this case,
  * the coroutine [Job] is created in _new_ state. It can be explicitly started with [start][Job.start] function
  * and will be started implicitly on the first invocation of [join][Job.join].

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CoroutineStart.kt

@@ -24,10 +24,16 @@ import kotlin.coroutines.experimental.startCoroutine
  * Defines start option for coroutines builders.
  * It is used in `start` parameter of [launch], [async], and [actor][kotlinx.coroutines.experimental.channels.actor]
  * coroutine builder functions.
+ *
+ * The summary of coroutine start options is:
+ * * [DEFAULT] -- immediately schedules coroutine for execution according to its context;
+ * * [LAZY] -- starts coroutine lazily, only when it is needed;
+ * * [ATOMIC] -- atomically (non-cancellably) schedules coroutine for execution according to its context;
+ * * [UNDISPATCHED] -- immediately executes coroutine until its first suspension point _in the current thread_.
  */
 public enum class CoroutineStart {
     /**
-     * Default -- schedules coroutine for execution according to its context.
+     * Default -- immediately schedules coroutine for execution according to its context.
      *
      * If the [CoroutineDispatcher] of the coroutine context returns `true` from [CoroutineDispatcher.isDispatchNeeded]
      * function as most dispatchers do, then the coroutine code is dispatched for execution later, while the code that
@@ -56,8 +62,8 @@ public enum class CoroutineStart {
     LAZY,
 
     /**
-     * Atomically schedules coroutines for execution according to its context. This is similar to [DEFAULT],
-     * but the coroutine cannot be cancelled before it starts executing.
+     * Atomically (non-cancellably) schedules coroutine for execution according to its context.
+     * This is similar to [DEFAULT], but the coroutine cannot be cancelled before it starts executing.
      *
      * Cancellability of coroutine at suspension points depends on the particular implementation details of
      * suspending functions as in [DEFAULT].
@@ -72,7 +78,7 @@ public enum class CoroutineStart {
     UNDISPATCHED;
 
     /**
-     * Starts the corresponding block as a coroutine with this coroutine start strategy.
+     * Starts the corresponding block with receiver as a coroutine with this coroutine start strategy.
      *
      * * [DEFAULT] uses [startCoroutineCancellable].
      * * [ATOMIC] uses [startCoroutine].

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Deferred.kt

@@ -105,7 +105,8 @@ public interface Deferred<out T> : Job {
  * The [context][CoroutineScope.context] of the parent coroutine from its [scope][CoroutineScope] may be used,
  * in which case the [Job] of the resulting coroutine is a child of the job of the parent coroutine.
  *
- * By default, the coroutine is immediately started.
+ * By default, the coroutine is immediately scheduled for execution.
+ * Other options can be specified via `start` parameter. See [CoroutineStart] for details.
  * An optional [start] parameter can be set to [CoroutineStart.LAZY] to start coroutine _lazily_. In this case,,
  * the resulting [Deferred] is created in _new_ state. It can be explicitly started with [start][Job.start]
  * function and will be started implicitly on the first invocation of [join][Job.join] or [await][Deferred.await].

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/Actor.kt

@@ -62,7 +62,8 @@ public interface ActorJob<in E> : Job, SendChannel<E> {
  * The [context][CoroutineScope.context] of the parent coroutine from its [scope][CoroutineScope] may be used,
  * in which case the [Job] of the resulting coroutine is a child of the job of the parent coroutine.
  *
- * By default, the coroutine is immediately started.
+ * By default, the coroutine is immediately scheduled for execution.
+ * Other options can be specified via `start` parameter. See [CoroutineStart] for details.
  * An optional [start] parameter can be set to [CoroutineStart.LAZY] to start coroutine _lazily_. In this case,
  * the coroutine [Job] is created in _new_ state. It can be explicitly started with [start][Job.start] function
  * and will be started implicitly on the first invocation of [join][Job.join] or on a first message