From 57a800bd1d1ff25b9f74821d508b94ddf96cf5d9 Mon Sep 17 00:00:00 2001
From: ahmed-tabib <43772573+ahmed-tabib@users.noreply.github.com>
Date: Sat, 18 Jan 2025 21:02:40 +0100
Subject: [PATCH 1/5] await returns signal result - gdscript basics

---
 .../scripting/gdscript/gdscript_basics.rst    | 28 ++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/tutorials/scripting/gdscript/gdscript_basics.rst b/tutorials/scripting/gdscript/gdscript_basics.rst
index 3fe52838c89..9427043ac9c 100644
--- a/tutorials/scripting/gdscript/gdscript_basics.rst
+++ b/tutorials/scripting/gdscript/gdscript_basics.rst
@@ -2488,7 +2488,33 @@ For example, to stop execution until the user presses a button, you can do somet
         print("User confirmed")
         return true
 
-In this case, the ``wait_confirmation`` becomes a coroutine, which means that the caller also needs to await it::
+If the signal emits a **single** argument, ``await`` returns a value with the same type as the argument::
+
+    signal user_accepted(accepted_analytics: bool)
+
+    func wait_confirmation():
+        print("Prompting user")
+        var analytics: bool = await user_accepted
+        print("User confirmed")
+        if analytics:
+            print("User accepted analytics")
+        return true
+
+However, if the signal emits **multiple** arguments, ``await`` returns an ``Array[Variant]`` containing the signal arguments in order::
+
+    signal user_accepted(accepted_analytics: bool, accepted_crash_report_upload: bool)
+
+    func wait_confirmation():
+        print("Prompting user")
+        var result: Array[Variant] = await user_accepted
+        print("User confirmed")
+        if result[0]:
+            print("User accepted analytics")
+        if result[1]:
+            print("User accepted crash report upload")
+        return true
+
+When you use ``await`` inside ``wait_confirmation``, the function becomes a coroutine, which means that the caller also needs to await it::
 
     func request_confirmation():
         print("Will ask the user")

From 293952f7751747b3a07f8d786bbd0e4da19061a1 Mon Sep 17 00:00:00 2001
From: ahmed-tabib <43772573+ahmed-tabib@users.noreply.github.com>
Date: Sat, 18 Jan 2025 21:43:37 +0100
Subject: [PATCH 2/5] dynamic typing in examples - writing guidelines
 compliance

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

diff --git a/tutorials/scripting/gdscript/gdscript_basics.rst b/tutorials/scripting/gdscript/gdscript_basics.rst
index 9427043ac9c..fa02428c03e 100644
--- a/tutorials/scripting/gdscript/gdscript_basics.rst
+++ b/tutorials/scripting/gdscript/gdscript_basics.rst
@@ -2471,6 +2471,7 @@ Our ``BattleLog`` node receives each element in the binds array as an extra argu
         var damage = old_value - new_value
         label.text += character_name + " took " + str(damage) + " damage."
 
+.. _doc_gdscript_awaiting_signals_or_coroutines:
 
 Awaiting signals or coroutines
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2490,11 +2491,11 @@ For example, to stop execution until the user presses a button, you can do somet
 
 If the signal emits a **single** argument, ``await`` returns a value with the same type as the argument::
 
-    signal user_accepted(accepted_analytics: bool)
+    signal user_accepted(accepted_analytics)
 
     func wait_confirmation():
         print("Prompting user")
-        var analytics: bool = await user_accepted
+        var analytics = await user_accepted
         print("User confirmed")
         if analytics:
             print("User accepted analytics")
@@ -2502,11 +2503,11 @@ If the signal emits a **single** argument, ``await`` returns a value with the sa
 
 However, if the signal emits **multiple** arguments, ``await`` returns an ``Array[Variant]`` containing the signal arguments in order::
 
-    signal user_accepted(accepted_analytics: bool, accepted_crash_report_upload: bool)
+    signal user_accepted(accepted_analytics, accepted_crash_report_upload)
 
     func wait_confirmation():
         print("Prompting user")
-        var result: Array[Variant] = await user_accepted
+        var result = await user_accepted
         print("User confirmed")
         if result[0]:
             print("User accepted analytics")

From 22db736315a9e288b237cf9cf77e43d91646bb2a Mon Sep 17 00:00:00 2001
From: ahmed-tabib <43772573+ahmed-tabib@users.noreply.github.com>
Date: Sat, 18 Jan 2025 21:55:17 +0100
Subject: [PATCH 3/5] Mention awaiting signals in the signals step by step
 guide.

---
 getting_started/step_by_step/signals.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/getting_started/step_by_step/signals.rst b/getting_started/step_by_step/signals.rst
index 9d07f0ffdcf..f6d9fd7f1e5 100644
--- a/getting_started/step_by_step/signals.rst
+++ b/getting_started/step_by_step/signals.rst
@@ -543,6 +543,13 @@ To emit values along with the signal, add them as extra arguments to the
         EmitSignal(SignalName.HealthChanged, oldHealth, _health);
     }
 
+Awaiting signals
+-------
+
+The ``await`` keyword can be used to wait until a signal is emitted. If the signal emits one argument it will be returned by ``await``. If the signal emits multiple arguments ``await`` will return an :ref:`Array<class_Array>` containing the arguments in order.
+
+See :ref:`Awaiting signals or coroutines<doc_gdscript_awaiting_signals_or_coroutines>`.
+
 Summary
 -------
 

From b8a97a8b4c4b71d7e29498aece469693fbc5778c Mon Sep 17 00:00:00 2001
From: ahmed-tabib <43772573+ahmed-tabib@users.noreply.github.com>
Date: Sat, 18 Jan 2025 21:58:14 +0100
Subject: [PATCH 4/5] Use Array class document reference.

---
 tutorials/scripting/gdscript/gdscript_basics.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tutorials/scripting/gdscript/gdscript_basics.rst b/tutorials/scripting/gdscript/gdscript_basics.rst
index fa02428c03e..a8ca5278f61 100644
--- a/tutorials/scripting/gdscript/gdscript_basics.rst
+++ b/tutorials/scripting/gdscript/gdscript_basics.rst
@@ -2501,7 +2501,7 @@ If the signal emits a **single** argument, ``await`` returns a value with the sa
             print("User accepted analytics")
         return true
 
-However, if the signal emits **multiple** arguments, ``await`` returns an ``Array[Variant]`` containing the signal arguments in order::
+However, if the signal emits **multiple** arguments, ``await`` returns an :ref:`Array<class_Array>` containing the signal arguments in order::
 
     signal user_accepted(accepted_analytics, accepted_crash_report_upload)
 

From d34f5f6ed042342eebf021367e924c728db70d68 Mon Sep 17 00:00:00 2001
From: ahmed-tabib <43772573+ahmed-tabib@users.noreply.github.com>
Date: Mon, 20 Jan 2025 12:14:35 +0100
Subject: [PATCH 5/5] fixed title underline too short

---
 getting_started/step_by_step/signals.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/getting_started/step_by_step/signals.rst b/getting_started/step_by_step/signals.rst
index f6d9fd7f1e5..af1d9ae8c77 100644
--- a/getting_started/step_by_step/signals.rst
+++ b/getting_started/step_by_step/signals.rst
@@ -544,7 +544,7 @@ To emit values along with the signal, add them as extra arguments to the
     }
 
 Awaiting signals
--------
+----------------
 
 The ``await`` keyword can be used to wait until a signal is emitted. If the signal emits one argument it will be returned by ``await``. If the signal emits multiple arguments ``await`` will return an :ref:`Array<class_Array>` containing the arguments in order.