Better docs on coroutines debugging property

* Mention in the guide that `-ea` turns it on.
* Give a link to DEBUG_PROPERTY_NAME instead of newCoroutineContext.
  The later does not have details on its page anymore, since
  the details were only mentioned in JVM version.
* Move description in of debugging facilities to DEBUG_PROPERTY_NAME
  in the code.

Author: elizarov

docs/coroutine-context-and-dispatchers.md

@@ -221,7 +221,8 @@ The `log` function prints the name of the thread in square brackets and you can
 thread, but the identifier of the currently executing coroutine is appended to it. This identifier 
 is consecutively assigned to all created coroutines when debugging mode is turned on.
 
-You can read more about debugging facilities in the documentation for [newCoroutineContext] function.
+> Debugging mode is also turned on when JVM is run with `-ea` option.
+You can read more about debugging facilities in the documentation for [DEBUG_PROPERTY_NAME] property.
 
 ### Jumping between threads
 
@@ -695,7 +696,7 @@ that should be implemented.
 [ExecutorCoroutineDispatcher.close]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-executor-coroutine-dispatcher/close.html
 [runBlocking]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/run-blocking.html
 [delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/delay.html
-[newCoroutineContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/new-coroutine-context.html
+[DEBUG_PROPERTY_NAME]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-d-e-b-u-g_-p-r-o-p-e-r-t-y_-n-a-m-e.html
 [withContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/with-context.html
 [isActive]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/is-active.html
 [CoroutineScope.coroutineContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/coroutine-context.html

kotlinx-coroutines-core/common/README.md

@@ -65,7 +65,7 @@ helper function. [NonCancellable] job object is provided to suppress cancellatio
 
 This module provides debugging facilities for coroutines (run JVM with `-ea` or `-Dkotlinx.coroutines.debug` options) 
 and [newCoroutineContext] function to write user-defined coroutine builders that work with these
-debugging facilities.
+debugging facilities. See [DEBUG_PROPERTY_NAME] for more details.
 
 This module provides a special CoroutineContext type [TestCoroutineCoroutineContext][kotlinx.coroutines.test.TestCoroutineContext] that
 allows the writer of code that contains Coroutines with delays and timeouts to write non-flaky unit-tests for that code allowing these tests to
@@ -124,6 +124,7 @@ Low-level primitives for finer-grained control of coroutines.
 [Deferred.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/await.html
 [Deferred.onAwait]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/on-await.html
 [newCoroutineContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/new-coroutine-context.html
+[DEBUG_PROPERTY_NAME]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-d-e-b-u-g_-p-r-o-p-e-r-t-y_-n-a-m-e.html
 <!--- INDEX kotlinx.coroutines.sync -->
 [kotlinx.coroutines.sync.Mutex]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-mutex/index.html
 [kotlinx.coroutines.sync.Mutex.lock]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.sync/-mutex/lock.html

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

@@ -26,24 +26,7 @@ internal actual fun createDefaultDispatcher(): CoroutineDispatcher =
  * Creates context for the new coroutine. It installs [Dispatchers.Default] when no other dispatcher nor
  * [ContinuationInterceptor] is specified, and adds optional support for debugging facilities (when turned on).
  *
- * **Debugging facilities:** In debug mode every coroutine is assigned a unique consecutive identifier.
- * Every thread that executes a coroutine has its name modified to include the name and identifier of the
- * currently running coroutine.
- * When one coroutine is suspended and resumes another coroutine that is dispatched in the same thread,
- * then the thread name displays
- * the whole stack of coroutine descriptions that are being executed on this thread.
- *
- * Enable debugging facilities with "`kotlinx.coroutines.debug`" ([DEBUG_PROPERTY_NAME]) system property
- * , use the following values:
- * * "`auto`" (default mode, [DEBUG_PROPERTY_VALUE_AUTO]) -- enabled when assertions are enabled with "`-ea`" JVM option.
- * * "`on`" ([DEBUG_PROPERTY_VALUE_ON]) or empty string -- enabled.
- * * "`off`" ([DEBUG_PROPERTY_VALUE_OFF]) -- disabled.
- *
- * Coroutine name can be explicitly assigned using [CoroutineName] context element.
- * The string "coroutine" is used as a default name.
- *
- * **Note: This is an experimental api.**
- *   Behavior of this function may change in the future with respect to its support for debugging facilities.
+ * See [DEBUG_PROPERTY_NAME] for description of debugging facilities on JVM.
  */
 @ExperimentalCoroutinesApi
 public actual fun CoroutineScope.newCoroutineContext(context: CoroutineContext): CoroutineContext {

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

@@ -12,7 +12,26 @@ import java.util.concurrent.atomic.*
 import kotlin.internal.InlineOnly
 
 /**
- * Name of the property that controls coroutine debugging. See [newCoroutineContext][CoroutineScope.newCoroutineContext].
+ * Name of the property that controls coroutine debugging.
+ *
+ * ### Debugging facilities
+ *
+ * In debug mode every coroutine is assigned a unique consecutive identifier.
+ * Every thread that executes a coroutine has its name modified to include the name and identifier of
+ * the currently running coroutine.
+ *
+ * Enable debugging facilities with "`kotlinx.coroutines.debug`" ([DEBUG_PROPERTY_NAME]) system property,
+ * use the following values:
+ *
+ * * "`auto`" (default mode, [DEBUG_PROPERTY_VALUE_AUTO]) -- enabled when assertions are enabled with "`-ea`" JVM option.
+ * * "`on`" ([DEBUG_PROPERTY_VALUE_ON]) or empty string -- enabled.
+ * * "`off`" ([DEBUG_PROPERTY_VALUE_OFF]) -- disabled.
+ *
+ * Coroutine name can be explicitly assigned using [CoroutineName] context element.
+ * The string "coroutine" is used as a default name.
+ *
+ * Debugging facilities are implemented by [newCoroutineContext][CoroutineScope.newCoroutineContext] function that
+ * is used in all coroutine builders to create context of a new coroutine.
  */
 public const val DEBUG_PROPERTY_NAME = "kotlinx.coroutines.debug"
 
@@ -58,17 +77,17 @@ public interface CopyableThrowable<T> where T : Throwable, T : CopyableThrowable
 }
 
 /**
- * Automatic debug configuration value for [DEBUG_PROPERTY_NAME]. See [newCoroutineContext][CoroutineScope.newCoroutineContext].
+ * Automatic debug configuration value for [DEBUG_PROPERTY_NAME].
  */
 public const val DEBUG_PROPERTY_VALUE_AUTO = "auto"
 
 /**
- * Debug turned on value for [DEBUG_PROPERTY_NAME]. See [newCoroutineContext][CoroutineScope.newCoroutineContext].
+ * Debug turned on value for [DEBUG_PROPERTY_NAME].
  */
 public const val DEBUG_PROPERTY_VALUE_ON = "on"
 
 /**
- * Debug turned on value for [DEBUG_PROPERTY_NAME]. See [newCoroutineContext][CoroutineScope.newCoroutineContext].
+ * Debug turned on value for [DEBUG_PROPERTY_NAME].
  */
 public const val DEBUG_PROPERTY_VALUE_OFF = "off"