From 443d5e9be5453513b6fd3824e149d19b3831e77f Mon Sep 17 00:00:00 2001
From: tetrapod00 <145553014+tetrapod00@users.noreply.github.com>
Date: Mon, 19 Aug 2024 17:03:21 -0700
Subject: [PATCH] Add documentation for GDScript when statement

---
 tutorials/scripting/gdscript/gdscript_basics.rst | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/tutorials/scripting/gdscript/gdscript_basics.rst b/tutorials/scripting/gdscript/gdscript_basics.rst
index 0f1451799d4..9f2742ff3dc 100644
--- a/tutorials/scripting/gdscript/gdscript_basics.rst
+++ b/tutorials/scripting/gdscript/gdscript_basics.rst
@@ -165,6 +165,8 @@ in case you want to take a look under the hood.
 +------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
 | match      | See match_.                                                                                                                                       |
 +------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+| when       | Used by `pattern guards <Pattern guards_>`_ in ``match`` statements.                                                                              |
++------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
 | break      | Exits the execution of the current ``for`` or ``while`` loop.                                                                                     |
 +------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
 | continue   | Immediately skips to the next iteration of the ``for`` or ``while`` loop.                                                                         |
@@ -1654,10 +1656,10 @@ Basic syntax
 
 ::
 
-    match <expression>:
+    match <test value>:
         <pattern(s)>:
             <block>
-        <pattern(s)> when <guard expression>:
+        <pattern(s)> when <pattern guard>:
             <block>
         <...>
 
@@ -1790,9 +1792,13 @@ The following pattern types are available:
 Pattern guards
 """"""""""""""
 
+A *pattern guard* is an optional condition that follows the pattern list
+and allows you to make additional checks before choosing a ``match`` branch.
+Unlike a pattern, a pattern guard can be an arbitrary expression.
+
 Only one branch can be executed per ``match``. Once a branch is chosen, the rest are not checked.
 If you want to use the same pattern for multiple branches or to prevent choosing a branch with too general pattern,
-you can specify a guard expression after the list of patterns with the ``when`` keyword::
+you can specify a pattern guard after the list of patterns with the ``when`` keyword::
 
     match point:
         [0, 0]:
@@ -1808,9 +1814,9 @@ you can specify a guard expression after the list of patterns with the ``when``
         [var x, var y]:
             print("Point (%s, %s)" % [x, y])
 
-- If there is no matching pattern for the current branch, the guard expression
+- If there is no matching pattern for the current branch, the pattern guard
   is **not** evaluated and the patterns of the next branch are checked.
-- If a matching pattern is found, the guard expression is evaluated.
+- If a matching pattern is found, the pattern guard is evaluated.
 
   - If it's true, then the body of the branch is executed and ``match`` ends.
   - If it's false, then the patterns of the next branch are checked.