Merge pull request #3553 from Kotlin/new-compiler-option-for-disabling-optimizations

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

Author: PetrakovichVictoria

docs/images/variable-optimised-out.png

@@ -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.
+
+### Optimized-out variables
+
+If you use `suspend` functions, in the debugger, you might see the "was optimized out" text next to a variable's name:
+
+![Variable "a" was optimized out](variable-optimised-out.png)
+
+This text means that the variable's lifetime was decreased, and the variable doesn't exist anymore.
+It is difficult to debug code with optimized variables 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-coroutines-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)
 
+### Optimized-out variables
+
+If you use `suspend` functions, in the debugger, you might see the "was optimized out" text next to a variable's name:
+
+![Variable "a" was optimized out](variable-optimised-out.png)
+
+This text means that the variable's lifetime was decreased, and the variable doesn't exist anymore.
+It is difficult to debug code with optimized variables 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`.