From 36bb7e5ac579523bf6cc2e273d99ff9046947bbe Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Sat, 5 Oct 2024 00:33:56 +0200
Subject: [PATCH] Document expression evaluator in Debugger panel

---
 tutorials/scripting/debug/debugger_panel.rst | 53 ++++++++++++++++++--
 1 file changed, 50 insertions(+), 3 deletions(-)

diff --git a/tutorials/scripting/debug/debugger_panel.rst b/tutorials/scripting/debug/debugger_panel.rst
index a86d6b952..683e26ad9 100644
--- a/tutorials/scripting/debug/debugger_panel.rst
+++ b/tutorials/scripting/debug/debugger_panel.rst
@@ -10,10 +10,10 @@ debugger panel at the bottom of the screen. Click on **Debugger** to open it.
 
 The debugger panel is split into several tabs, each focusing on a specific task.
 
-Debugger
---------
+Stack Trace
+-----------
 
-The Debugger tab opens automatically when the GDScript compiler reaches
+The Stack Trace tab opens automatically when the GDScript compiler reaches
 a breakpoint in your code.
 
 It gives you a `stack trace <https://en.wikipedia.org/wiki/Stack_trace>`__,
@@ -55,6 +55,53 @@ This is where error and warning messages are printed while running the game.
 
 You can disable specific warnings in **Project Settings > Debug > GDScript**.
 
+Evaluator
+----------
+
+This tab contains an expression evaluator, also known as a :abbr:`REPL (Read-Eval-Print Loop)`.
+This is a more powerful complement to the Stack Variables tree available in the Stack Trace tab.
+
+When the project is interrupted in the debugger (due to a breakpoint or script
+error), you can enter an expression in the text field at the top. If the project
+is running, the expression field won't be editable, so you will need to set a
+breakpoint first. Expressions can be persisted across runs by unchecking **Clear on Run**,
+although they will be lost when the editor quits.
+
+Expressions are evaluated using :ref:`Godot's expression language
+<doc_evaluating_expressions>`, which allows you to perform arithmetic and call
+some functions within the expression. Expressions can refer to member variables,
+or local variables within the same scope as the line the breakpoint is on. You
+can also enter constant values, which makes it usable as a built-in calculator.
+
+Consider the following script:
+
+::
+
+    var counter = 0
+
+    func _process(delta):
+        counter += 1
+        if counter == 5:
+            var text = "Some text"
+            breakpoint
+        elif counter >= 6:
+            var other_text = "Some other text"
+            breakpoint
+
+If the debugger breaks on the **first** line containing ``breakpoint``, the following
+expressions return non-null values:
+
+- **Constant expression:** ``2 * PI + 5``
+- **Member variable:** ``counter``, ``counter ** 2``, ``sqrt(counter)``
+- **Local variable or function parameter:** ``delta``, ``text``, ``text.to_upper()``
+
+If the debugger breaks on the **second** line containing ``breakpoint``, the following
+expressions return non-null values:
+
+- **Constant expression:** ``2 * PI + 5``
+- **Member variable:** ``counter``, ``counter ** 2``, ``sqrt(counter)``
+- **Local variable or function parameter:** ``delta``, ``other_text``, ``other_text.to_upper()``
+
 Profiler
 --------