Document var x = await signal returns signal arguments.

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
 -------
 

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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2488,7 +2489,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)
+
+    func wait_confirmation():
+        print("Prompting user")
+        var analytics = await user_accepted
+        print("User confirmed")
+        if analytics:
+            print("User accepted analytics")
+        return true
+
+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)
+
+    func wait_confirmation():
+        print("Prompting user")
+        var result = 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")