Improve docs

Author: dkhalanskyjb

kotlinx-coroutines-core/jvm/src/debug/CoroutineDebugging.kt

@@ -2,10 +2,20 @@
  * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
+/* This package name is like this so that
+1) the artificial stack frames look pretty, and
+2) the IDE reliably navigates to this file. */
 package _COROUTINE
 
 /**
  * A collection of artificial stack trace elements to be included in stack traces by the coroutines machinery.
+ *
+ * There are typically two ways in which one can encounter an artificial stack frame:
+ * 1. By using the debug mode, via the stacktrace recovery mechanism; see
+ * https://github.com/Kotlin/kotlinx.coroutines/blob/master/docs/topics/debugging.md#stacktrace-recovery. The usual way
+ * to enable the debug mode is with the [kotlinx.coroutines.DEBUG_PROPERTY_NAME] system property.
+ * 2. By looking at the output of DebugProbes; see
+ * https://github.com/Kotlin/kotlinx.coroutines/tree/master/kotlinx-coroutines-debug.
  */
 internal class ArtificialStackFrames {
     /**
@@ -35,10 +45,20 @@ internal class ArtificialStackFrames {
     fun coroutineBoundary(): StackTraceElement = Exception().artificialFrame(_BOUNDARY::class.java.simpleName)
 }
 
+// These are needed for the IDE navigation to detect that this file does contain the definition.
 private class _CREATION
 private class _BOUNDARY
 
 internal val ARTIFICIAL_FRAME_PACKAGE_NAME = "_COROUTINE"
 
+/**
+ * Forms an artificial stack frame with the given class name.
+ *
+ * It consists of the following parts:
+ * 1. The package name, it seems, is needed for the IDE to detect stack trace elements reliably. It is `_COROUTINE` since
+ * this is a valid identifier.
+ * 2. Class names represents what type of artificial frame this is.
+ * 3. The method name is `_`. The methods not being present in class definitions does not seem to affect navigation.
+ */
 private fun Throwable.artificialFrame(name: String): StackTraceElement =
     with(stackTrace[0]) { StackTraceElement(ARTIFICIAL_FRAME_PACKAGE_NAME + "." + name, "_", fileName, lineNumber) }