Add @deprecated and @experimental GDScript annotations pointing t…

…o comments

These annotations don't exist at a source level, so the new annotations
are only here to point to the documentation comment syntax.

This makes it easier to discover the feature as it'll now appear
in the help search as well.

modules/gdscript/doc_classes/@GDScript.xml

@@ -281,6 +281,30 @@
 		</constant>
 	</constants>
 	<annotations>
+		<annotation name="@deprecated">
+			<return type="void" />
+			<description>
+				Indicates that a class, member, property, constant or signal is deprecated. This usually means the value marked as deprecated will be removed in a future version.
+				[b]Note:[/b] This annotation does not exist at a source level. Use [code]## @deprecated Reason here[/code] as a comment instead.
+				[codeblock]
+				## @deprecated: This is superseded by [method some_other_function].
+				func some_function():
+				    pass
+				[/codeblock]
+			</description>
+		</annotation>
+		<annotation name="@experimental">
+			<return type="void" />
+			<description>
+				Indicates that a class, member, property, constant or signal is experimental. This usually means there is no compatibility guarantee provided for users of the value marked as experimental.
+				[b]Note:[/b] This annotation does not exist at a source level. Use [code]## @experimental Reason here[/code] as a comment instead.
+				[codeblock]
+				## @experimental: Not all features in this function are implemented yet. The last parameter currently doesn't do anything.
+				func some_function(a, b, c):
+				    pass
+				[/codeblock]
+			</description>
+		</annotation>
 		<annotation name="@export">
 			<return type="void" />
 			<description>

modules/gdscript/gdscript_parser.cpp

@@ -131,6 +131,10 @@ GDScriptParser::GDScriptParser() {
 		register_annotation(MethodInfo("@warning_ignore", PropertyInfo(Variant::STRING, "warning")), AnnotationInfo::CLASS_LEVEL | AnnotationInfo::STATEMENT, &GDScriptParser::warning_annotations, varray(), true);
 		// Networking.
 		register_annotation(MethodInfo("@rpc", PropertyInfo(Variant::STRING, "mode"), PropertyInfo(Variant::STRING, "sync"), PropertyInfo(Variant::STRING, "transfer_mode"), PropertyInfo(Variant::INT, "transfer_channel")), AnnotationInfo::FUNCTION, &GDScriptParser::rpc_annotation, varray("authority", "call_remote", "unreliable", 0));
+
+		// Nonexistent annotations at a source level. Only present to give error messages advising to use them within documentation comments instead.
+		register_annotation(MethodInfo("@deprecated", PropertyInfo(Variant::STRING, "message")), AnnotationInfo::CLASS_LEVEL | AnnotationInfo::STATEMENT, &GDScriptParser::deprecated_annotation, varray(""));
+		register_annotation(MethodInfo("@experimental", PropertyInfo(Variant::STRING, "message")), AnnotationInfo::CLASS_LEVEL | AnnotationInfo::STATEMENT, &GDScriptParser::experimental_annotation, varray(""));
 	}
 
 #ifdef DEBUG_ENABLED
@@ -4903,6 +4907,20 @@ bool GDScriptParser::static_unload_annotation(AnnotationNode *p_annotation, Node
 	return true;
 }
 
+bool GDScriptParser::deprecated_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class) {
+#ifdef DEBUG_ENABLED
+	push_error(R"("@deprecated" annotation does not exist at a source level. Use "## @deprecated: Reason here." as a comment instead.)", p_annotation);
+	return false;
+#endif
+}
+
+bool GDScriptParser::experimental_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class) {
+#ifdef DEBUG_ENABLED
+	push_error(R"("@experimental" annotation does not exist at a source level. Use "## @experimental: Reason here." as a comment instead.)", p_annotation);
+	return false;
+#endif
+}
+
 GDScriptParser::DataType GDScriptParser::SuiteNode::Local::get_datatype() const {
 	switch (type) {
 		case CONSTANT:

modules/gdscript/gdscript_parser.h

@@ -1517,6 +1517,8 @@ class GDScriptParser {
 	bool warning_annotations(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class);
 	bool rpc_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class);
 	bool static_unload_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class);
+	bool deprecated_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class);
+	bool experimental_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class);
 	// Statements.
 	Node *parse_statement();
 	VariableNode *parse_variable(bool p_is_static);