From be41e6f84e81e8e64e672c834f9678be14d56f6e Mon Sep 17 00:00:00 2001
From: Danil Alexeev <danil@alexeev.xyz>
Date: Mon, 21 Oct 2024 11:36:59 +0300
Subject: [PATCH] Clarify `EngineDebugger` and `EditorDebugger*` documentation

---
 doc/classes/EditorDebuggerPlugin.xml       | 32 ++++++++++++++++++----
 doc/classes/EditorDebuggerSession.xml      |  2 +-
 doc/classes/EngineDebugger.xml             |  3 +-
 editor/debugger/script_editor_debugger.cpp |  2 +-
 4 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/doc/classes/EditorDebuggerPlugin.xml b/doc/classes/EditorDebuggerPlugin.xml
index a519e43bc69..d513a4fce06 100644
--- a/doc/classes/EditorDebuggerPlugin.xml
+++ b/doc/classes/EditorDebuggerPlugin.xml
@@ -15,18 +15,20 @@
 
 		class ExampleEditorDebugger extends EditorDebuggerPlugin:
 
-		    func _has_capture(prefix):
-		        # Return true if you wish to handle message with this prefix.
-		        return prefix == "my_plugin"
+		    func _has_capture(capture):
+		        # Return true if you wish to handle messages with the prefix "my_plugin:".
+		        return capture == "my_plugin"
 
 		    func _capture(message, data, session_id):
 		        if message == "my_plugin:ping":
 		            get_session(session_id).send_message("my_plugin:echo", data)
+		            return true
+		        return false
 
 		    func _setup_session(session_id):
 		        # Add a new tab in the debugger session UI containing a label.
 		        var label = Label.new()
-		        label.name = "Example plugin"
+		        label.name = "Example plugin" # Will be used as the tab title.
 		        label.text = "Example plugin"
 		        var session = get_session(session_id)
 		        # Listens to the session started and stopped signals.
@@ -43,6 +45,24 @@
 		    remove_debugger_plugin(debugger)
 		[/gdscript]
 		[/codeblocks]
+		To connect on the running game side, use the [EngineDebugger] singleton:
+		[codeblocks]
+		[gdscript]
+		extends Node
+
+		func _ready():
+		    EngineDebugger.register_message_capture("my_plugin", _capture)
+		    EngineDebugger.send_message("my_plugin:ping", ["test"])
+
+		func _capture(message, data):
+		    # Note that the "my_plugin:" prefix is not used here.
+		    if message == "echo":
+		        prints("Echo received:", data)
+		        return true
+		    return false
+		[/gdscript]
+		[/codeblocks]
+		[b]Note:[/b] While the game is running, [method @GlobalScope.print] and similar functions [i]called in the editor[/i] do not print anything, the Output Log prints only game messages.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -68,7 +88,7 @@
 			<param index="1" name="data" type="Array" />
 			<param index="2" name="session_id" type="int" />
 			<description>
-				Override this method to process incoming messages. The [param session_id] is the ID of the [EditorDebuggerSession] that received the message (which you can retrieve via [method get_session]).
+				Override this method to process incoming messages. The [param session_id] is the ID of the [EditorDebuggerSession] that received the [param message]. Use [method get_session] to retrieve the session. This method should return [code]true[/code] if the message is recognized.
 			</description>
 		</method>
 		<method name="_goto_script_line" qualifiers="virtual">
@@ -90,7 +110,7 @@
 			<return type="void" />
 			<param index="0" name="session_id" type="int" />
 			<description>
-				Override this method to be notified whenever a new [EditorDebuggerSession] is created (the session may be inactive during this stage).
+				Override this method to be notified whenever a new [EditorDebuggerSession] is created. Note that the session may be inactive during this stage.
 			</description>
 		</method>
 		<method name="get_session">
diff --git a/doc/classes/EditorDebuggerSession.xml b/doc/classes/EditorDebuggerSession.xml
index b4e754cc7e1..f5fa3e34d5e 100644
--- a/doc/classes/EditorDebuggerSession.xml
+++ b/doc/classes/EditorDebuggerSession.xml
@@ -14,7 +14,7 @@
 			<return type="void" />
 			<param index="0" name="control" type="Control" />
 			<description>
-				Adds the given [param control] to the debug session UI in the debugger bottom panel.
+				Adds the given [param control] to the debug session UI in the debugger bottom panel. The [param control]'s node name will be used as the tab title.
 			</description>
 		</method>
 		<method name="is_active">
diff --git a/doc/classes/EngineDebugger.xml b/doc/classes/EngineDebugger.xml
index bcc1ac5299c..3540f098ba3 100644
--- a/doc/classes/EngineDebugger.xml
+++ b/doc/classes/EngineDebugger.xml
@@ -113,7 +113,8 @@
 			<param index="1" name="callable" type="Callable" />
 			<description>
 				Registers a message capture with given [param name]. If [param name] is "my_message" then messages starting with "my_message:" will be called with the given callable.
-				Callable must accept a message string and a data array as argument. If the message and data are valid then callable must return [code]true[/code] otherwise [code]false[/code].
+				The callable must accept a message string and a data array as argument. The callable should return [code]true[/code] if the message is recognized.
+				[b]Note:[/b] The callable will receive the message with the prefix stripped, unlike [method EditorDebuggerPlugin._capture]. See the [EditorDebuggerPlugin] description for an example.
 			</description>
 		</method>
 		<method name="register_profiler">
diff --git a/editor/debugger/script_editor_debugger.cpp b/editor/debugger/script_editor_debugger.cpp
index cbe7910518c..73c59707d23 100644
--- a/editor/debugger/script_editor_debugger.cpp
+++ b/editor/debugger/script_editor_debugger.cpp
@@ -827,7 +827,7 @@ void ScriptEditorDebugger::_parse_message(const String &p_msg, uint64_t p_thread
 
 		bool parsed = EditorDebuggerNode::get_singleton()->plugins_capture(this, p_msg, p_data);
 		if (!parsed) {
-			WARN_PRINT("unknown message " + p_msg);
+			WARN_PRINT("Unknown message: " + p_msg);
 		}
 	}
 }