diff --git a/doc/classes/@GDScript.xml b/doc/classes/@GDScript.xml
index e3eceaa591c..ec7ee52da8a 100644
--- a/doc/classes/@GDScript.xml
+++ b/doc/classes/@GDScript.xml
@@ -1137,8 +1137,9 @@
 			<argument index="1" name="signal" type="String" default="&quot;&quot;">
 			</argument>
 			<description>
-				Stops the function execution and returns the current state. Call [method GDScriptFunctionState.resume] on the state to resume execution. This invalidates the state.
-				Returns anything that was passed to the resume function call. If passed an object and a signal, the execution is resumed when the object's signal is emitted.
+				Stops the function execution and returns the current suspended state to the calling function.
+				From the caller, call [method GDScriptFunctionState.resume] on the state to resume execution. This invalidates the state. Within the resumed function, [code]yield()[/code] returns whatever was passed to the [code]resume()[/code] function call.
+				If passed an object and a signal, the execution is resumed when the object emits the given signal. In this case, [code]yield()[/code] returns the argument passed to [code]emit_signal()[/code] if the signal takes only one argument, or an array containing all the arguments passed to [code]emit_signal()[/code] if the signal takes multiple arguments.
 			</description>
 		</method>
 	</methods>