From bc66a2aa221dee05691c1b069715d84e5c83f2d5 Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Sun, 8 Dec 2024 15:34:01 +0100
Subject: [PATCH] Add `@deprecated` and `@experimental` GDScript annotations
 pointing to 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                   | 10 +++++++++-
 .../scripts/parser/errors/annotation_deprecated.gd     |  5 +++++
 .../scripts/parser/errors/annotation_deprecated.out    |  2 ++
 .../scripts/parser/errors/annotation_experimental.gd   |  6 ++++++
 .../scripts/parser/errors/annotation_experimental.out  |  2 ++
 5 files changed, 24 insertions(+), 1 deletion(-)
 create mode 100644 modules/gdscript/tests/scripts/parser/errors/annotation_deprecated.gd
 create mode 100644 modules/gdscript/tests/scripts/parser/errors/annotation_deprecated.out
 create mode 100644 modules/gdscript/tests/scripts/parser/errors/annotation_experimental.gd
 create mode 100644 modules/gdscript/tests/scripts/parser/errors/annotation_experimental.out

diff --git a/modules/gdscript/gdscript_parser.cpp b/modules/gdscript/gdscript_parser.cpp
index 12e71004dbde..b636dd082899 100644
--- a/modules/gdscript/gdscript_parser.cpp
+++ b/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;
 	}
 
diff --git a/modules/gdscript/tests/scripts/parser/errors/annotation_deprecated.gd b/modules/gdscript/tests/scripts/parser/errors/annotation_deprecated.gd
new file mode 100644
index 000000000000..95569c48de70
--- /dev/null
+++ b/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"
diff --git a/modules/gdscript/tests/scripts/parser/errors/annotation_deprecated.out b/modules/gdscript/tests/scripts/parser/errors/annotation_deprecated.out
new file mode 100644
index 000000000000..6d1681bd7cd4
--- /dev/null
+++ b/modules/gdscript/tests/scripts/parser/errors/annotation_deprecated.out
@@ -0,0 +1,2 @@
+GDTEST_PARSER_ERROR
+"@deprecated" annotation does not exist at a source level. Use "## @deprecated: Reason here." as a comment instead.
diff --git a/modules/gdscript/tests/scripts/parser/errors/annotation_experimental.gd b/modules/gdscript/tests/scripts/parser/errors/annotation_experimental.gd
new file mode 100644
index 000000000000..ce00639de6d4
--- /dev/null
+++ b/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
diff --git a/modules/gdscript/tests/scripts/parser/errors/annotation_experimental.out b/modules/gdscript/tests/scripts/parser/errors/annotation_experimental.out
new file mode 100644
index 000000000000..cda274f01a34
--- /dev/null
+++ b/modules/gdscript/tests/scripts/parser/errors/annotation_experimental.out
@@ -0,0 +1,2 @@
+GDTEST_PARSER_ERROR
+"@experimental" annotation does not exist at a source level. Use "## @experimental: Reason here." as a comment instead.