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/gdscript_parser.cpp

@@ -1624,7 +1624,15 @@ GDScriptParser::AnnotationNode *GDScriptParser::parse_annotation(uint32_t p_vali
 	bool valid = true;
 
 	if (!valid_annotations.has(annotation->name)) {
-		push_error(vformat(R"(Unrecognized annotation: "%s".)", annotation->name));
+		if (annotation->name == "@deprecated") {
+			push_error(R"("@deprecated" annotation does not exist. Use "## @deprecated: Reason here." instead.)");
+		} else if (annotation->name == "@experimental") {
+			push_error(R"("@experimental" annotation does not exist. Use "## @experimental: Reason here." instead.)");
+		} else if (annotation->name == "@tutorial") {
+			push_error(R"("@tutorial" annotation does not exist. Use "## @tutorial(Title): https://example.com" instead.)");
+		} else {
+			push_error(vformat(R"(Unrecognized annotation: "%s".)", annotation->name));
+		}
 		valid = false;
 	}
 

modules/gdscript/tests/scripts/parser/errors/annotation_deprecated.gd

@@ -0,0 +1,5 @@
+# This annotation should be used within a documentation comment instead:
+# ## @deprecated: Reason here.
+
+@deprecated
+var some_variable = "value"

modules/gdscript/tests/scripts/parser/errors/annotation_deprecated.out

@@ -0,0 +1,2 @@
+GDTEST_PARSER_ERROR
+"@deprecated" annotation does not exist. Use "## @deprecated: Reason here." instead.

modules/gdscript/tests/scripts/parser/errors/annotation_experimental.gd

@@ -0,0 +1,6 @@
+# This annotation should be used within a documentation comment instead:
+# ## @experimental: Reason here.
+
+@experimental("This function isn't implemented yet.")
+func say_hello():
+    pass

modules/gdscript/tests/scripts/parser/errors/annotation_experimental.out

@@ -0,0 +1,2 @@
+GDTEST_PARSER_ERROR
+"@experimental" annotation does not exist. Use "## @experimental: Reason here." instead.

modules/gdscript/tests/scripts/parser/errors/annotation_tutorial.gd

@@ -0,0 +1,5 @@
+# This annotation should be used within a documentation comment instead:
+# ## @tutorial(Title): https://example.com
+
+@tutorial("https://example.com")
+const SOME_CONSTANT = "value"

modules/gdscript/tests/scripts/parser/errors/annotation_tutorial.out

@@ -0,0 +1,2 @@
+GDTEST_PARSER_ERROR
+"@tutorial" annotation does not exist. Use "## @tutorial(Title): https://example.com" instead.