From ba722ea0676de0b36689519339c06b7c18b7fee3 Mon Sep 17 00:00:00 2001
From: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com>
Date: Wed, 28 Feb 2024 14:34:13 +0100
Subject: [PATCH] [Doc] Clarify some details about deferred calls

(cherry picked from commit 1cc5b0aa0d2ab0da6c82cad736e9cd50b0771251)
---
 doc/classes/Callable.xml | 1 +
 doc/classes/Object.xml   | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/classes/Callable.xml b/doc/classes/Callable.xml
index b903e98319d..5af0597e20b 100644
--- a/doc/classes/Callable.xml
+++ b/doc/classes/Callable.xml
@@ -113,6 +113,7 @@
 				func _ready():
 				    grab_focus.call_deferred()
 				[/codeblock]
+				[b]Note:[/b] Deferred calls are processed at idle time. Idle time happens mainly at the end of process and physics frames. In it, deferred calls will be run until there are none left, which means you can defer calls from other deferred calls and they'll still be run in the current idle time cycle. This means you should not call a method deferred from itself (or from a method called by it), as this causes infinite recursion the same way as if you had called the method directly.
 				See also [method Object.call_deferred].
 			</description>
 		</method>
diff --git a/doc/classes/Object.xml b/doc/classes/Object.xml
index e4f4d7682b9..011092ce2c9 100644
--- a/doc/classes/Object.xml
+++ b/doc/classes/Object.xml
@@ -377,7 +377,7 @@
 			<param index="0" name="method" type="StringName" />
 			<description>
 				Calls the [param method] on the object during idle time. Always returns null, [b]not[/b] the method's result.
-				Idle time happens mainly at the end of process and physics frames. In it, deferred calls will be run until there are none left, which means you can defer calls from other deferred calls and they'll still be run in the current idle time cycle. If not done carefully, this can result in infinite recursion without causing a stack overflow, which will hang the game similarly to an infinite loop.
+				Idle time happens mainly at the end of process and physics frames. In it, deferred calls will be run until there are none left, which means you can defer calls from other deferred calls and they'll still be run in the current idle time cycle. This means you should not call a method deferred from itself (or from a method called by it), as this causes infinite recursion the same way as if you had called the method directly.
 				This method supports a variable number of arguments, so parameters can be passed as a comma separated list.
 				[codeblocks]
 				[gdscript]