Documentation: Add support for deprecated/experimental messages

8 files changed, 45 insertions, 18 deletions

diff --git a/modules/gdscript/doc_classes/@GDScript.xml b/modules/gdscript/doc_classes/@GDScript.xml
index 933bfba5ba..9982edfbd3 100644
--- a/modules/gdscript/doc_classes/@GDScript.xml
+++ b/modules/gdscript/doc_classes/@GDScript.xml
@@ -57,12 +57,11 @@
 				[/codeblock]
 			</description>
 		</method>
-		<method name="convert" is_deprecated="true">
+		<method name="convert" deprecated="Use [method @GlobalScope.type_convert] instead.">
 			<return type="Variant" />
 			<param index="0" name="what" type="Variant" />
 			<param index="1" name="type" type="int" />
 			<description>
-				[i]Deprecated.[/i] Use [method @GlobalScope.type_convert] instead.
 				Converts [param what] to [param type] in the best way possible. The [param type] uses the [enum Variant.Type] values.
 				[codeblock]
 				var a = [4, 2.5, 1.2]
diff --git a/modules/gdscript/editor/gdscript_docgen.cpp b/modules/gdscript/editor/gdscript_docgen.cpp
index 659140b9b1..601db5414b 100644
--- a/modules/gdscript/editor/gdscript_docgen.cpp
+++ b/modules/gdscript/editor/gdscript_docgen.cpp
@@ -268,7 +268,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_
 		doc.tutorials.append(td);
 	}
 	doc.is_deprecated = p_class->doc_data.is_deprecated;
+	doc.deprecated_message = p_class->doc_data.deprecated_message;
 	doc.is_experimental = p_class->doc_data.is_experimental;
+	doc.experimental_message = p_class->doc_data.experimental_message;
 
 	for (const GDP::ClassNode::Member &member : p_class->members) {
 		switch (member.type) {
@@ -295,7 +297,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_
 				const_doc.is_value_valid = true;
 				const_doc.description = m_const->doc_data.description;
 				const_doc.is_deprecated = m_const->doc_data.is_deprecated;
+				const_doc.deprecated_message = m_const->doc_data.deprecated_message;
 				const_doc.is_experimental = m_const->doc_data.is_experimental;
+				const_doc.experimental_message = m_const->doc_data.experimental_message;
 				doc.constants.push_back(const_doc);
 			} break;
 
@@ -309,7 +313,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_
 				method_doc.name = func_name;
 				method_doc.description = m_func->doc_data.description;
 				method_doc.is_deprecated = m_func->doc_data.is_deprecated;
+				method_doc.deprecated_message = m_func->doc_data.deprecated_message;
 				method_doc.is_experimental = m_func->doc_data.is_experimental;
+				method_doc.experimental_message = m_func->doc_data.experimental_message;
 				method_doc.qualifiers = m_func->is_static ? "static" : "";
 
 				if (m_func->return_type) {
@@ -349,7 +355,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_
 				signal_doc.name = signal_name;
 				signal_doc.description = m_signal->doc_data.description;
 				signal_doc.is_deprecated = m_signal->doc_data.is_deprecated;
+				signal_doc.deprecated_message = m_signal->doc_data.deprecated_message;
 				signal_doc.is_experimental = m_signal->doc_data.is_experimental;
+				signal_doc.experimental_message = m_signal->doc_data.experimental_message;
 
 				for (const GDScriptParser::ParameterNode *p : m_signal->parameters) {
 					DocData::ArgumentDoc arg_doc;
@@ -371,7 +379,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_
 				prop_doc.name = var_name;
 				prop_doc.description = m_var->doc_data.description;
 				prop_doc.is_deprecated = m_var->doc_data.is_deprecated;
+				prop_doc.deprecated_message = m_var->doc_data.deprecated_message;
 				prop_doc.is_experimental = m_var->doc_data.is_experimental;
+				prop_doc.experimental_message = m_var->doc_data.experimental_message;
 				_doctype_from_gdtype(m_var->get_datatype(), prop_doc.type, prop_doc.enumeration);
 
 				switch (m_var->property) {
@@ -417,7 +427,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_
 				DocData::EnumDoc enum_doc;
 				enum_doc.description = m_enum->doc_data.description;
 				enum_doc.is_deprecated = m_enum->doc_data.is_deprecated;
+				enum_doc.deprecated_message = m_enum->doc_data.deprecated_message;
 				enum_doc.is_experimental = m_enum->doc_data.is_experimental;
+				enum_doc.experimental_message = m_enum->doc_data.experimental_message;
 				doc.enums[name] = enum_doc;
 
 				for (const GDP::EnumNode::Value &val : m_enum->values) {
@@ -428,7 +440,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_
 					const_doc.enumeration = name;
 					const_doc.description = val.doc_data.description;
 					const_doc.is_deprecated = val.doc_data.is_deprecated;
+					const_doc.deprecated_message = val.doc_data.deprecated_message;
 					const_doc.is_experimental = val.doc_data.is_experimental;
+					const_doc.experimental_message = val.doc_data.experimental_message;
 
 					doc.constants.push_back(const_doc);
 				}
@@ -448,7 +462,9 @@ void GDScriptDocGen::_generate_docs(GDScript *p_script, const GDP::ClassNode *p_
 				const_doc.enumeration = "@unnamed_enums";
 				const_doc.description = m_enum_val.doc_data.description;
 				const_doc.is_deprecated = m_enum_val.doc_data.is_deprecated;
+				const_doc.deprecated_message = m_enum_val.doc_data.deprecated_message;
 				const_doc.is_experimental = m_enum_val.doc_data.is_experimental;
+				const_doc.experimental_message = m_enum_val.doc_data.experimental_message;
 				doc.constants.push_back(const_doc);
 			} break;
 
diff --git a/modules/gdscript/gdscript_parser.cpp b/modules/gdscript/gdscript_parser.cpp
index 649bd735c6..4625855329 100644
--- a/modules/gdscript/gdscript_parser.cpp
+++ b/modules/gdscript/gdscript_parser.cpp
@@ -3609,11 +3609,17 @@ GDScriptParser::MemberDocData GDScriptParser::parse_doc_comment(int p_line, bool
 
 		if (state == DOC_LINE_NORMAL) {
 			String stripped_line = doc_line.strip_edges();
-			if (stripped_line.begins_with("@deprecated")) {
+			if (stripped_line == "@deprecated" || stripped_line.begins_with("@deprecated:")) {
 				result.is_deprecated = true;
+				if (stripped_line.begins_with("@deprecated:")) {
+					result.deprecated_message = stripped_line.trim_prefix("@deprecated:").strip_edges();
+				}
 				continue;
-			} else if (stripped_line.begins_with("@experimental")) {
+			} else if (stripped_line == "@experimental" || stripped_line.begins_with("@experimental:")) {
 				result.is_experimental = true;
+				if (stripped_line.begins_with("@experimental:")) {
+					result.experimental_message = stripped_line.trim_prefix("@experimental:").strip_edges();
+				}
 				continue;
 			}
 		}
@@ -3712,11 +3718,17 @@ GDScriptParser::ClassDocData GDScriptParser::parse_class_doc_comment(int p_line,
 
 				result.tutorials.append(Pair<String, String>(title, link));
 				continue;
-			} else if (stripped_line.begins_with("@deprecated")) {
+			} else if (stripped_line == "@deprecated" || stripped_line.begins_with("@deprecated:")) {
 				result.is_deprecated = true;
+				if (stripped_line.begins_with("@deprecated:")) {
+					result.deprecated_message = stripped_line.trim_prefix("@deprecated:").strip_edges();
+				}
 				continue;
-			} else if (stripped_line.begins_with("@experimental")) {
+			} else if (stripped_line == "@experimental" || stripped_line.begins_with("@experimental:")) {
 				result.is_experimental = true;
+				if (stripped_line.begins_with("@experimental:")) {
+					result.experimental_message = stripped_line.trim_prefix("@experimental:").strip_edges();
+				}
 				continue;
 			}
 		}
diff --git a/modules/gdscript/gdscript_parser.h b/modules/gdscript/gdscript_parser.h
index c064a2d0f4..6664e6df04 100644
--- a/modules/gdscript/gdscript_parser.h
+++ b/modules/gdscript/gdscript_parser.h
@@ -274,13 +274,17 @@ public:
 		String description;
 		Vector<Pair<String, String>> tutorials;
 		bool is_deprecated = false;
+		String deprecated_message;
 		bool is_experimental = false;
+		String experimental_message;
 	};
 
 	struct MemberDocData {
 		String description;
 		bool is_deprecated = false;
+		String deprecated_message;
 		bool is_experimental = false;
+		String experimental_message;
 	};
 #endif // TOOLS_ENABLED
 
diff --git a/modules/gltf/doc_classes/GLTFDocument.xml b/modules/gltf/doc_classes/GLTFDocument.xml
index 1b52a82298..1f172633da 100644
--- a/modules/gltf/doc_classes/GLTFDocument.xml
+++ b/modules/gltf/doc_classes/GLTFDocument.xml
@@ -10,7 +10,7 @@
 	</description>
 	<tutorials>
 		<link title="Runtime file loading and saving">$DOCS_URL/tutorials/io/runtime_file_loading_and_saving.html</link>
-		<link title="glTF 'What the duck?' guide">https://www.khronos.org/files/gltf20-reference-guide.pdf</link>
+		<link title="glTF &apos;What the duck?&apos; guide">https://www.khronos.org/files/gltf20-reference-guide.pdf</link>
 		<link title="Khronos glTF specification">https://registry.khronos.org/glTF/</link>
 	</tutorials>
 	<methods>
diff --git a/modules/gltf/doc_classes/GLTFPhysicsBody.xml b/modules/gltf/doc_classes/GLTFPhysicsBody.xml
index ca66cd54b0..5cfc22f6b2 100644
--- a/modules/gltf/doc_classes/GLTFPhysicsBody.xml
+++ b/modules/gltf/doc_classes/GLTFPhysicsBody.xml
@@ -55,7 +55,7 @@
 		<member name="inertia_orientation" type="Quaternion" setter="set_inertia_orientation" getter="get_inertia_orientation" default="Quaternion(0, 0, 0, 1)">
 			The inertia orientation of the physics body. This defines the rotation of the inertia's principle axes relative to the object's local axes. This is only used when the body type is "rigid" or "vehicle" and [member inertia_diagonal] is set to a non-zero value.
 		</member>
-		<member name="inertia_tensor" type="Basis" setter="set_inertia_tensor" getter="get_inertia_tensor" default="Basis(0, 0, 0, 0, 0, 0, 0, 0, 0)" is_deprecated="true">
+		<member name="inertia_tensor" type="Basis" setter="set_inertia_tensor" getter="get_inertia_tensor" default="Basis(0, 0, 0, 0, 0, 0, 0, 0, 0)" deprecated="">
 			The inertia tensor of the physics body, in kilogram meter squared (kg⋅m²). This is only used when the body type is "rigid" or "vehicle".
 			When converted to a Godot [RigidBody3D] node, if this value is zero, then the inertia will be calculated automatically.
 		</member>
diff --git a/modules/gridmap/doc_classes/GridMap.xml b/modules/gridmap/doc_classes/GridMap.xml
index 3094a7bf80..da11cd216f 100644
--- a/modules/gridmap/doc_classes/GridMap.xml
+++ b/modules/gridmap/doc_classes/GridMap.xml
@@ -138,11 +138,11 @@
 				Returns the position of a grid cell in the GridMap's local coordinate space. To convert the returned value into global coordinates, use [method Node3D.to_global]. See also [method map_to_local].
 			</description>
 		</method>
-		<method name="resource_changed" is_deprecated="true">
+		<method name="resource_changed" deprecated="Use [signal Resource.changed] instead.">
 			<return type="void" />
 			<param index="0" name="resource" type="Resource" />
 			<description>
-				[i]Obsoleted.[/i] Use [signal Resource.changed] instead.
+				This method does nothing.
 			</description>
 		</method>
 		<method name="set_cell_item">
diff --git a/modules/multiplayer/doc_classes/SceneReplicationConfig.xml b/modules/multiplayer/doc_classes/SceneReplicationConfig.xml
index 1a51e4b6e9..8b9203d316 100644
--- a/modules/multiplayer/doc_classes/SceneReplicationConfig.xml
+++ b/modules/multiplayer/doc_classes/SceneReplicationConfig.xml
@@ -51,20 +51,18 @@
 				Returns whether the property identified by the given [param path] is configured to be synchronized on spawn.
 			</description>
 		</method>
-		<method name="property_get_sync" is_deprecated="true">
+		<method name="property_get_sync" deprecated="Use [method property_get_replication_mode] instead.">
 			<return type="bool" />
 			<param index="0" name="path" type="NodePath" />
 			<description>
 				Returns whether the property identified by the given [param path] is configured to be synchronized on process.
-				[i]Deprecated.[/i] Use [method property_get_replication_mode] instead.
 			</description>
 		</method>
-		<method name="property_get_watch" is_deprecated="true">
+		<method name="property_get_watch" deprecated="Use [method property_get_replication_mode] instead.">
 			<return type="bool" />
 			<param index="0" name="path" type="NodePath" />
 			<description>
 				Returns whether the property identified by the given [param path] is configured to be reliably synchronized when changes are detected on process.
-				[i]Deprecated.[/i] Use [method property_get_replication_mode] instead.
 			</description>
 		</method>
 		<method name="property_set_replication_mode">
@@ -83,22 +81,20 @@
 				Sets whether the property identified by the given [param path] is configured to be synchronized on spawn.
 			</description>
 		</method>
-		<method name="property_set_sync" is_deprecated="true">
+		<method name="property_set_sync" deprecated="Use [method property_set_replication_mode] with [constant REPLICATION_MODE_ALWAYS] instead.">
 			<return type="void" />
 			<param index="0" name="path" type="NodePath" />
 			<param index="1" name="enabled" type="bool" />
 			<description>
 				Sets whether the property identified by the given [param path] is configured to be synchronized on process.
-				[i]Deprecated.[/i] Use [method property_set_replication_mode] with [constant REPLICATION_MODE_ALWAYS] instead.
 			</description>
 		</method>
-		<method name="property_set_watch" is_deprecated="true">
+		<method name="property_set_watch" deprecated="Use [method property_set_replication_mode] with [constant REPLICATION_MODE_ON_CHANGE] instead.">
 			<return type="void" />
 			<param index="0" name="path" type="NodePath" />
 			<param index="1" name="enabled" type="bool" />
 			<description>
 				Sets whether the property identified by the given [param path] is configured to be reliably synchronized when changes are detected on process.
-				[i]Deprecated.[/i] Use [method property_set_replication_mode] with [constant REPLICATION_MODE_ON_CHANGE] instead.
 			</description>
 		</method>
 		<method name="remove_property">