Docs: add about -Xdebug to disable "was optimise out"

docs/topics/debug-coroutines-with-idea.md

@@ -100,3 +100,17 @@ The tutorial assumes you have prior knowledge of the [coroutines](coroutines-gui
     * The third coroutine is calculating the value of `b` – it has the **RUNNING** status.
 
 Using IntelliJ IDEA debugger, you can dig deeper into each coroutine to debug your code.
+
+### Debug suspend functions
+
+If you use `suspend` functions, in the debugger, you might see the "was optimised out" text next to a variable's name:
+
+![Variable "a" was optimised out](variable-optimised-out.png)
+
+This text means that the variable's lifetime was decreased, and the variable doesn't exist anymore.
+Debugging code with optimised variables is hard because you don't see their values.
+You can disable this behavior with the `-Xdebug` compiler option.
+
+> __Never use this flag in production__: `-Xdebug` can [cause memory leaks](https://youtrack.jetbrains.com/issue/KT-48678/Coroutine-debugger-disable-was-optimised-out-compiler-feature#focus=Comments-27-6015585.0-0).
+>
+{type="warning"}

docs/topics/debug-flow-with-idea.md

@@ -102,6 +102,20 @@ Create a Kotlin [flow](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-cor
 
     ![Debug the coroutine](flow-debug-2.png)
 
+### Debug suspend functions
+
+If you use `suspend` functions, in the debugger, you might see the "was optimised out" text next to a variable's name:
+
+![Variable "a" was optimised out](variable-optimised-out.png)
+
+This text means that the variable's lifetime was decreased, and the variable doesn't exist anymore.
+Debugging code with optimised variables is hard because you don't see their values.
+You can disable this behavior with the `-Xdebug` compiler option.
+
+> __Never use this flag in production__: `-Xdebug` can [cause memory leaks](https://youtrack.jetbrains.com/issue/KT-48678/Coroutine-debugger-disable-was-optimised-out-compiler-feature#focus=Comments-27-6015585.0-0).
+>
+{type="warning"}
+
 ## Add a concurrently running coroutine
 
 1. Open the `Main.kt` file in `src/main/kotlin`.