added @override to help with explicitly overriding the base method

Author: Lazy-Rabbit-2001

doc/classes/ProjectSettings.xml

@@ -546,7 +546,10 @@
 			When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when the [code]@onready[/code] annotation is used together with the [code]@export[/code] annotation, since it may not behave as expected.
 		</member>
 		<member name="debug/gdscript/warnings/override_non_virtual_method" type="int" setter="" getter="" default="1">
-			When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a method tries to override the one that is not annotated by [code]@virtual[/code] in the super class, since such behavior will lead to unexpected and unsafe behaviors, unless you know what you are doing.
+			When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a method tries to override the one that is not annotated by [code]@virtual[/code] from the base class, since such behavior will lead to unexpected and unsafe behaviors, unless you know what you are doing.
+		</member>
+		<member name="debug/gdscript/warnings/override_without_override_annotation" type="int" setter="" getter="" default="1">
+			When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a method tries to override the one annotated by [code]@virtual[/code] from the base class, without an explicit annotation [code]@override[/code].
 		</member>
 		<member name="debug/gdscript/warnings/property_used_as_function" type="int" setter="" getter="" default="1" deprecated="This warning is never produced. Instead, an error is generated if the expression type is known at compile time.">
 			When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when using a property as if it is a function.

modules/gdscript/doc_classes/@GDScript.xml

@@ -739,6 +739,27 @@
 				[/codeblock]
 			</description>
 		</annotation>
+		<annotation name="@override">
+			<return type="void" />
+			<description>
+				Mark that the following method overrides the one annotated by [annotation @virtual] from the base class.
+				If you override a method from the base class without this annotation, you will get a warning (or an error).
+				[codeblock]
+				func _init():
+				    B.new().test() # Prints B
+
+
+				class A:
+				    @virtual func test():
+				        print("A")
+
+				class B extends A:
+				    func test():
+				        print("B") # Warning (or an error) about overriding a virtual method without explicit overriding.
+				[/codeblock]
+				You can ignore the warning as long as you know what you are doing.
+			</description>
+		</annotation>
 		<annotation name="@rpc">
 			<return type="void" />
 			<param index="0" name="mode" type="String" default="&quot;authority&quot;" />
@@ -787,6 +808,7 @@
 			<return type="void" />
 			<description>
 				Mark a method as a virtual method. A virtual method is a method that can be overridden by subclasses.
+				To override a virtual method, it is better to use an [annotation @override] annotation for the method in the subclass.
 				[codeblock]
 				func _init():
 				    B.new().test() # Prints B.
@@ -797,13 +819,13 @@
 				        print("A")
 
 				class B extends A:
-				    func test():
+				    @override func test():
 				        print("B")
 				[/codeblock]
 				If a method is trying to override a non-virtual method, a warning (or an error) will be thrown.
 				[codeblock]
 				func _init():
-				    B.new().test() # Prints B, with a warning (or an error) about overriding a non-virtual method.
+				    B.new().test() # Prints B
 
 
 				class A:
@@ -812,7 +834,7 @@
 
 				class B extends A:
 				    func test():
-				        print("B")
+				        print("B") # Warning (or an error) about overriding a non-virtual method.
 				[/codeblock]
 				You can ignore the warning as long as you know what you are doing.
 			</description>

modules/gdscript/gdscript_analyzer.cpp

@@ -1870,11 +1870,13 @@ void GDScriptAnalyzer::resolve_function_signature(GDScriptParser::FunctionNode *
 				push_error(vformat(R"(The function signature doesn't match the parent. Parent signature is "%s".)", parent_signature), p_function);
 			}
 
-			// Non-virtual methods cannot be overridden.
+			// (Non-)virtual methods overriding warnings
 			if (base_type.class_type != nullptr && base_type.class_type->has_function(p_function->identifier->name)) {
 				GDScriptParser::FunctionNode *parent_func = base_type.class_type->get_member(p_function->identifier->name).function;
 				if (!parent_func->is_annotated_virtual) {
 					parser->push_warning(p_function, GDScriptWarning::OVERRIDE_NON_VIRTUAL_METHOD, function_name);
+				} else if (!p_function->is_annotated_overriding) {
+					parser->push_warning(p_function, GDScriptWarning::OVERRIDE_WITHOUT_OVERRIDE_ANNOATION, function_name);
 				}
 			}
 

modules/gdscript/gdscript_parser.cpp

@@ -99,6 +99,7 @@ GDScriptParser::GDScriptParser() {
 		// Onready annotation.
 		register_annotation(MethodInfo("@onready"), AnnotationInfo::VARIABLE, &GDScriptParser::onready_annotation);
 		// Virtual annotation
+		register_annotation(MethodInfo("@override"), AnnotationInfo::FUNCTION, &GDScriptParser::override_annotation);
 		register_annotation(MethodInfo("@virtual"), AnnotationInfo::FUNCTION, &GDScriptParser::virtual_annotation);
 		// Export annotations.
 		register_annotation(MethodInfo("@export"), AnnotationInfo::VARIABLE, &GDScriptParser::export_annotations<PROPERTY_HINT_NONE, Variant::NIL>);
@@ -4293,14 +4294,28 @@ bool GDScriptParser::virtual_annotation(AnnotationNode *p_annotation, Node *p_ta
 
 	FunctionNode *method = static_cast<FunctionNode *>(p_target);
 	if (method->is_annotated_virtual) {
-		push_error(R"("@virtual" annotation can only be used once per variable.)", p_annotation);
+		push_error(R"("@virtual" annotation can only be used once per method.)", p_annotation);
 		return false;
 	}
 
 	method->is_annotated_virtual = true;
 	return true;
 }
 
+bool GDScriptParser::override_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class) {
+	ERR_FAIL_COND_V_MSG(p_target->type != Node::FUNCTION, false, R"("@override" annotation can only be applied to class methods.)");
+	ERR_FAIL_COND_V_MSG(p_target->type == Node::LAMBDA, false, R"("@override" annotation cannot be applied to lambdas.)");
+
+	FunctionNode *method = static_cast<FunctionNode *>(p_target);
+	if (method->is_annotated_overriding) {
+		push_error(R"("@override" annotation can only be used once per method.)", p_annotation);
+		return false;
+	}
+
+	method->is_annotated_overriding = true;
+	return true;
+}
+
 static String _get_annotation_error_string(const StringName &p_annotation_name, const Vector<Variant::Type> &p_expected_types, const GDScriptParser::DataType &p_provided_type) {
 	Vector<String> types;
 	for (int i = 0; i < p_expected_types.size(); i++) {

modules/gdscript/gdscript_parser.h

@@ -856,6 +856,7 @@ class GDScriptParser {
 		bool is_static = false; // For lambdas it's determined in the analyzer.
 		bool is_coroutine = false;
 		bool is_annotated_virtual = false;
+		bool is_annotated_overriding = false;
 		Variant rpc_config;
 		MethodInfo info;
 		LambdaNode *source_lambda = nullptr;
@@ -1511,6 +1512,7 @@ class GDScriptParser {
 	bool static_unload_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class);
 	bool onready_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class);
 	bool virtual_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class);
+	bool override_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class);
 	template <PropertyHint t_hint, Variant::Type t_type>
 	bool export_annotations(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class);
 	bool export_storage_annotation(AnnotationNode *p_annotation, Node *p_target, ClassNode *p_class);

modules/gdscript/gdscript_warning.cpp

@@ -165,6 +165,9 @@ String GDScriptWarning::get_message() const {
 		case OVERRIDE_NON_VIRTUAL_METHOD:
 			CHECK_SYMBOLS(1);
 			return vformat(R"*(The method "%s()" overrides a non-virtual method from the base class. This may cause unexpected and unsafe behaviors.)*", symbols[0]);
+		case OVERRIDE_WITHOUT_OVERRIDE_ANNOATION:
+			CHECK_SYMBOLS(1);
+			return vformat(R"*(The method "%s()" overrides a virtual method from the base class without the "@override" annotation. Annotating the method with the annotation can better help you understand and clarify the code structure.)*", symbols[0]);
 #ifndef DISABLE_DEPRECATED
 		// Never produced. These warnings migrated from 3.x by mistake.
 		case PROPERTY_USED_AS_FUNCTION: // There is already an error.
@@ -242,6 +245,7 @@ String GDScriptWarning::get_name_from_code(Code p_code) {
 		"GET_NODE_DEFAULT_WITHOUT_ONREADY",
 		"ONREADY_WITH_EXPORT",
 		"OVERRIDE_NON_VIRTUAL_METHOD",
+		"OVERRIDE_WITHOUT_OVERRIDE_ANNOATION",
 #ifndef DISABLE_DEPRECATED
 		"PROPERTY_USED_AS_FUNCTION",
 		"CONSTANT_USED_AS_FUNCTION",

modules/gdscript/gdscript_warning.h

@@ -90,6 +90,7 @@ class GDScriptWarning {
 		GET_NODE_DEFAULT_WITHOUT_ONREADY, // A class variable uses `get_node()` (or the `$` notation) as its default value, but does not use the @onready annotation.
 		ONREADY_WITH_EXPORT, // The `@onready` annotation will set the value after `@export` which is likely not intended.
 		OVERRIDE_NON_VIRTUAL_METHOD, // The class method overrides a non-virtual one, which would cause potential problems.
+		OVERRIDE_WITHOUT_OVERRIDE_ANNOATION, // The class method overrides a virtual one without the `@override` annotation.
 #ifndef DISABLE_DEPRECATED
 		PROPERTY_USED_AS_FUNCTION, // Function not found, but there's a property with the same name.
 		CONSTANT_USED_AS_FUNCTION, // Function not found, but there's a constant with the same name.
@@ -148,6 +149,7 @@ class GDScriptWarning {
 		ERROR, // GET_NODE_DEFAULT_WITHOUT_ONREADY // May not work as expected.
 		ERROR, // ONREADY_WITH_EXPORT // May not work as expected.
 		WARN, // OVERRIDE_NON_VIRTUAL_METHOD
+		WARN, // OVERRIDE_WITHOUT_OVERRIDE_ANNOATION
 #ifndef DISABLE_DEPRECATED
 		WARN, // PROPERTY_USED_AS_FUNCTION
 		WARN, // CONSTANT_USED_AS_FUNCTION

modules/gdscript/tests/scripts/analyzer/features/external_inner_base.gd

@@ -1,4 +1,4 @@
 extends "inner_base.gd".InnerA.InnerAB
 
-func test():
+@override func test():
 	super.test()

modules/gdscript/tests/scripts/analyzer/features/function_match_parent_signature_with_default_dict_void.gd

@@ -10,5 +10,5 @@ class Parent:
 		pass
 
 class Child extends Parent:
-	func my_function(_par1: Dictionary = {}) -> void:
+	@override func my_function(_par1: Dictionary = {}) -> void:
 		pass

modules/gdscript/tests/scripts/analyzer/features/function_match_parent_signature_with_extra_parameters.gd

@@ -13,5 +13,5 @@ class Parent:
 		return par1
 
 class Child extends Parent:
-	func my_function(_par1: int, par2: int = 0) -> int:
+	@override func my_function(_par1: int, par2: int = 0) -> int:
 		return par2