Re-structure DebugProbes documentation and mention classloading (#4024)

* Re-structure DebugProbes documentation and mention classloading

Fixes #4000

Co-authored-by: Dmitry Khalanskiy <[email protected]>

Author: qwwdfsad

kotlinx-coroutines-debug/src/DebugProbes.kt

@@ -9,11 +9,12 @@ import java.lang.management.*
 import kotlin.coroutines.*
 
 /**
- * Debug probes support.
+ * Kotlin debug probes support.
  *
  * Debug probes is a dynamic attach mechanism which installs multiple hooks into coroutines machinery.
- * It slows down all coroutine-related code, but in return provides a lot of diagnostic information, including
- * asynchronous stack-traces and coroutine dumps (similar to [ThreadMXBean.dumpAllThreads] and `jstack` via [DebugProbes.dumpCoroutines].
+ * It slows down all coroutine-related code, but in return provides diagnostic information, including
+ * asynchronous stacktraces, coroutine dumps (similar to [ThreadMXBean.dumpAllThreads] and `jstack`) via [DebugProbes.dumpCoroutines],
+ * and programmatic introspection of all alive coroutines.
  * All introspecting methods throw [IllegalStateException] if debug probes were not installed.
  *
  * ### Consistency guarantees
@@ -24,16 +25,26 @@ import kotlin.coroutines.*
  * In practice, it means that for snapshotting operations in progress, for each concurrent coroutine either
  * the state prior to the operation or the state that was reached during the current operation is observed.
  *
- * ### Installed hooks
- * * `probeCoroutineResumed` is invoked on every [Continuation.resume].
- * * `probeCoroutineSuspended` is invoked on every continuation suspension.
- * * `probeCoroutineCreated` is invoked on every coroutine creation.
- *
  * ### Overhead
- *  * Every created coroutine is stored in a concurrent hash map and hash map is looked up and
+ *
+ *  - Every created coroutine is stored in a concurrent hash map, and the hash map is looked up in and
  *    updated on each suspension and resumption.
- *  * If [DebugProbes.enableCreationStackTraces] is enabled, stack trace of the current thread is captured on
+ *  - If [DebugProbes.enableCreationStackTraces] is enabled, stack trace of the current thread is captured on
  *    each created coroutine that is a rough equivalent of throwing an exception per each created coroutine.
+ *
+ * ### Internal machinery and classloading.
+ *
+ * Under the hood, debug probes replace internal `kotlin.coroutines.jvm.internal.DebugProbesKt` class that has the following
+ * empty static methods:
+ *
+ * - `probeCoroutineResumed` that is invoked on every [Continuation.resume].
+ * - `probeCoroutineSuspended` that is invoked on every continuation suspension.
+ * - `probeCoroutineCreated` that is invoked on every coroutine creation.
+ *
+ * with a `kotlinx-coroutines`-specific class to keep track of all the coroutines machinery.
+ *
+ * The new class is located in the `kotlinx-coroutines-core` module, meaning that all target application classes that use
+ * coroutines and `suspend` functions have to be loaded by the classloader in which `kotlinx-coroutines-core` classes are available.
  */
 @ExperimentalCoroutinesApi
 public object DebugProbes {