Warn user when user-marked deprecated method is used

Note to self about methods for other non-user classes

Display warning for deprecated methods on built-in classes (like AnimationPlayer)

Protect from doc data being null

Push warning for user-defined signal marked as `@deprecated`

Recognize user-defined constant marked as `@deprecated`

Recognize user-defined enums and values in anonymous enums marked as `@deprecated`

Recognize user-defined property marked as `@deprecated`

Recognize local variable marked as `@deprecated`

Recognize built-in class (such as for constructors or static methods) marked as deprecated

Recognize global autoload marked as `@deprecated`

Recognize constant in `@GlobalScope` marked as deprecated

Recognize global script class(?) marked as deprecated

Recognize types from type hints in assignment statements marked as deprecated

Recognize signal from native class marked as deprecated

Recognize property from native class marked as deprecated

Recognize constant from native class marked as deprecated

Recognize enum from native class marked as deprecated

Recognize individual value in enum marked as deprecated

Recognize local constant marked as deprecated

Recognize inner class in expression marked as deprecated

Recognize individual value in user-defined named enum in inner class marked as deprecated

Fix recognition of individual value from native enum with enum name marked as deprecated

Remove some duplicate code

Update modules/gdscript/gdscript_warning.cpp

Co-authored-by: Micky <[email protected]>

Provide context for warning, including type and name, when available

Get rid of `auto` usages

Fix some crashes when trying to access a null identifier

Add test for warning

Fix variable redeclaration

Update test to use classes that don't crash

Try removing AnimationPlayer case from unit test

Add description in documentation for DEPRECATED_IDENTIFIER

Replace DEBUG_ENABLED with TOOLS_ENABLED

Add explanation for test case being commented out

Update doc/classes/ProjectSettings.xml

Co-authored-by: Micky <[email protected]>

Update test

Apply suggestions from code review

Co-authored-by: A Thousand Ships <[email protected]>

# Conflicts:
#	modules/gdscript/gdscript_analyzer.cpp

Update modules/gdscript/gdscript_analyzer.cpp

Co-authored-by: A Thousand Ships <[email protected]>

Author: Meorge

doc/classes/ProjectSettings.xml

@@ -527,6 +527,9 @@
 		<member name="debug/gdscript/warnings/confusable_local_usage" type="int" setter="" getter="" default="1">
 			When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when an identifier that will be shadowed below in the block is used.
 		</member>
+		<member name="debug/gdscript/warnings/deprecated_identifier" type="int" setter="" getter="" default="1">
+			When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when deprecated identifiers are used. These include any deprecated class, enum, constant, signal, property, and method.
+		</member>
 		<member name="debug/gdscript/warnings/deprecated_keyword" type="int" setter="" getter="" default="1">
 			When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when deprecated keywords are used.
 			[b]Note:[/b] There are currently no deprecated keywords, so this warning is never produced.

modules/gdscript/gdscript_analyzer.cpp

@@ -44,6 +44,10 @@
 #include "core/templates/hash_map.h"
 #include "scene/main/node.h"
 
+#ifdef TOOLS_ENABLED
+#include "editor/doc/editor_help.h"
+#endif
+
 #if defined(TOOLS_ENABLED) && !defined(DISABLE_DEPRECATED)
 #define SUGGEST_GODOT4_RENAMES
 #include "editor/project_upgrade/renames_map_3_to_4.h"
@@ -2088,6 +2092,57 @@ void GDScriptAnalyzer::resolve_assignable(GDScriptParser::AssignableNode *p_assi
 		type = specified_type;
 	}
 
+#ifdef TOOLS_ENABLED
+	DocTools *dd = EditorHelp::get_doc_data();
+	bool is_deprecated = false;
+	String new_value_type = "value";
+	String value_name = type.native_type;
+	switch (type.kind) {
+		case GDScriptParser::DataType::Kind::BUILTIN: // No built-in datatypes are deprecated.
+			break;
+		case GDScriptParser::DataType::Kind::NATIVE:
+			is_deprecated = dd && dd->class_list.has(type.native_type) && dd->class_list[type.native_type].is_deprecated;
+			new_value_type = "class";
+			break;
+		case GDScriptParser::DataType::Kind::SCRIPT: {
+			StringName class_name = type.script_type->get_doc_class_name();
+			is_deprecated = dd && dd->class_list.has(class_name) && dd->class_list[class_name].is_deprecated;
+			new_value_type = "class";
+			break;
+		}
+		case GDScriptParser::DataType::Kind::CLASS:
+			is_deprecated = type.class_type->doc_data.is_deprecated;
+			new_value_type = "class";
+
+			// TODO: Not recognizing the autoload name as a class type
+			// var my_var: MyAutoload  # <--- not getting this name
+			if (type.class_type && type.class_type->identifier) {
+				value_name = type.class_type->identifier->name;
+			} else {
+				value_name = "";
+			}
+			break;
+		case GDScriptParser::DataType::Kind::ENUM: {
+			StringName enum_type = type.enum_type; // Something like MyEnum.
+			GDScriptParser::ClassNode *class_type = type.class_type;
+			StringName class_name = (class_type && class_type->identifier) ? class_type->identifier->name : "@GlobalScope";
+			if (dd && dd->class_list.has(class_name)) {
+				DocData::ClassDoc class_doc = dd->class_list[class_name];
+				if (class_doc.enums.has(enum_type)) {
+					is_deprecated = class_doc.enums[enum_type].is_deprecated;
+				}
+			}
+			new_value_type = "enum";
+			break;
+		}
+		default:
+			break;
+	}
+	if (is_deprecated) {
+		parser->push_warning(p_assignable, GDScriptWarning::DEPRECATED_IDENTIFIER, new_value_type, value_name);
+	}
+#endif
+
 	if (p_assignable->initializer != nullptr) {
 		reduce_expression(p_assignable->initializer);
 
@@ -4040,6 +4095,38 @@ void GDScriptAnalyzer::reduce_identifier_from_base(GDScriptParser::IdentifierNod
 	StringName name = p_identifier->name;
 
 	if (base.kind == GDScriptParser::DataType::ENUM) {
+#ifdef TOOLS_ENABLED
+		StringName class_name;
+		DocTools *dd = EditorHelp::get_doc_data();
+		// TODO: Is this a proper way of detecting it's from a native class?
+		// e.g., "AnimationPlayer.AnimationProcessCallback"
+		// User-defined enums also seem to have a "native_type" so we can't
+		// detect actual native classes solely based on whether or not that
+		// string is defined.
+		if (base.native_type && !base.class_type) {
+			class_name = String(base.native_type).get_slicec('.', 0);
+		}
+
+		else if (base.class_type && base.class_type->identifier && base.class_type->identifier->name) {
+			class_name = base.class_type->identifier->name;
+			// It's an inner class, so we need to get the outer class's name
+			// as well to construct its full name as found in the doc data.
+			if (base.class_type->outer != nullptr && base.class_type->outer->identifier != nullptr) {
+				class_name = String(base.class_type->outer->identifier->name) + "." + class_name;
+			}
+		}
+
+		if (dd && dd->class_list.has(class_name)) {
+			for (const DocData::ConstantDoc &doc : dd->class_list[class_name].constants) {
+				if (doc.enumeration == base.enum_type && doc.name == name) {
+					if (doc.is_deprecated) {
+						parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "enum value", vformat("%s.%s", base.enum_type, doc.name));
+					}
+					break;
+				}
+			}
+		}
+#endif
 		if (base.is_meta_type) {
 			if (base.enum_values.has(name)) {
 				p_identifier->set_datatype(type_from_metatype(base));
@@ -4185,6 +4272,11 @@ void GDScriptAnalyzer::reduce_identifier_from_base(GDScriptParser::IdentifierNod
 					p_identifier->reduced_value = member.constant->initializer->reduced_value;
 					p_identifier->source = GDScriptParser::IdentifierNode::MEMBER_CONSTANT;
 					p_identifier->constant_source = member.constant;
+#ifdef TOOLS_ENABLED
+					if (member.constant->doc_data.is_deprecated) {
+						parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "constant", name);
+					}
+#endif
 					return;
 				}
 
@@ -4193,6 +4285,11 @@ void GDScriptAnalyzer::reduce_identifier_from_base(GDScriptParser::IdentifierNod
 					p_identifier->is_constant = true;
 					p_identifier->reduced_value = member.enum_value.value;
 					p_identifier->source = GDScriptParser::IdentifierNode::MEMBER_CONSTANT;
+#ifdef TOOLS_ENABLED
+					if (member.enum_value.doc_data.is_deprecated) {
+						parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "enum value", name);
+					}
+#endif
 					return;
 				}
 
@@ -4201,6 +4298,11 @@ void GDScriptAnalyzer::reduce_identifier_from_base(GDScriptParser::IdentifierNod
 					p_identifier->is_constant = true;
 					p_identifier->reduced_value = member.m_enum->dictionary;
 					p_identifier->source = GDScriptParser::IdentifierNode::MEMBER_CONSTANT;
+#ifdef TOOLS_ENABLED
+					if (member.m_enum->doc_data.is_deprecated) {
+						parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "enum", name);
+					}
+#endif
 					return;
 				}
 
@@ -4210,6 +4312,11 @@ void GDScriptAnalyzer::reduce_identifier_from_base(GDScriptParser::IdentifierNod
 						p_identifier->source = member.variable->is_static ? GDScriptParser::IdentifierNode::STATIC_VARIABLE : GDScriptParser::IdentifierNode::MEMBER_VARIABLE;
 						p_identifier->variable_source = member.variable;
 						member.variable->usages += 1;
+#ifdef TOOLS_ENABLED
+						if (member.variable->doc_data.is_deprecated) {
+							parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "property or variable", name);
+						}
+#endif
 						return;
 					}
 				} break;
@@ -4220,6 +4327,12 @@ void GDScriptAnalyzer::reduce_identifier_from_base(GDScriptParser::IdentifierNod
 						p_identifier->source = GDScriptParser::IdentifierNode::MEMBER_SIGNAL;
 						p_identifier->signal_source = member.signal;
 						member.signal->usages += 1;
+
+#ifdef TOOLS_ENABLED
+						if (member.signal->doc_data.is_deprecated) {
+							parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "signal", name);
+						}
+#endif
 						return;
 					}
 				} break;
@@ -4237,6 +4350,11 @@ void GDScriptAnalyzer::reduce_identifier_from_base(GDScriptParser::IdentifierNod
 				case GDScriptParser::ClassNode::Member::CLASS: {
 					reduce_identifier_from_base_set_class(p_identifier, member.get_datatype());
 					p_identifier->source = GDScriptParser::IdentifierNode::MEMBER_CLASS;
+#ifdef TOOLS_ENABLED
+					if (script_class->get_member(name).m_class->doc_data.is_deprecated) {
+						parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "class", name);
+					}
+#endif
 					return;
 				}
 
@@ -4326,6 +4444,19 @@ void GDScriptAnalyzer::reduce_identifier_from_base(GDScriptParser::IdentifierNod
 				p_identifier->set_datatype(type_from_property(getter->get_return_info(), false, !has_setter));
 				p_identifier->source = GDScriptParser::IdentifierNode::INHERITED_VARIABLE;
 			}
+#ifdef TOOLS_ENABLED
+			DocTools *dd = EditorHelp::get_doc_data();
+			if (dd && dd->class_list.has(native)) {
+				for (const DocData::PropertyDoc &doc : dd->class_list[native].properties) {
+					if (doc.name == name) {
+						if (doc.is_deprecated) {
+							parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "property", name);
+						}
+						break;
+					}
+				}
+			}
+#endif
 			return;
 		}
 		if (ClassDB::get_method_info(native, name, &method_info)) {
@@ -4338,11 +4469,33 @@ void GDScriptAnalyzer::reduce_identifier_from_base(GDScriptParser::IdentifierNod
 			// Signal is a type too.
 			p_identifier->set_datatype(make_signal_type(method_info));
 			p_identifier->source = GDScriptParser::IdentifierNode::INHERITED_VARIABLE;
+#ifdef TOOLS_ENABLED
+			DocTools *dd = EditorHelp::get_doc_data();
+			if (dd && dd->class_list.has(native)) {
+				for (const DocData::MethodDoc &doc : dd->class_list[native].signals) {
+					if (doc.name == name) {
+						if (doc.is_deprecated) {
+							parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "signal", name);
+						}
+						break;
+					}
+				}
+			}
+#endif
 			return;
 		}
 		if (ClassDB::has_enum(native, name)) {
 			p_identifier->set_datatype(make_native_enum_type(name, native));
 			p_identifier->source = GDScriptParser::IdentifierNode::MEMBER_CONSTANT;
+#ifdef TOOLS_ENABLED
+			DocTools *dd = EditorHelp::get_doc_data();
+			if (dd && dd->class_list.has(native) && dd->class_list[native].enums.has(name)) {
+				DocData::EnumDoc doc = dd->class_list[native].enums[name];
+				if (doc.is_deprecated) {
+					parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "enum", name);
+				}
+			}
+#endif
 			return;
 		}
 		bool valid = false;
@@ -4353,6 +4506,20 @@ void GDScriptAnalyzer::reduce_identifier_from_base(GDScriptParser::IdentifierNod
 			p_identifier->reduced_value = int_constant;
 			p_identifier->source = GDScriptParser::IdentifierNode::MEMBER_CONSTANT;
 
+#ifdef TOOLS_ENABLED
+			DocTools *dd = EditorHelp::get_doc_data();
+			if (dd && dd->class_list.has(native)) {
+				for (const DocData::ConstantDoc &doc : dd->class_list[native].constants) {
+					if (doc.name == name) {
+						if (doc.is_deprecated) {
+							parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "constant", name);
+						}
+						break;
+					}
+				}
+			}
+#endif
+
 			// Check whether this constant, which exists, belongs to an enum
 			StringName enum_name = ClassDB::get_integer_constant_enum(native, name);
 			if (enum_name != StringName()) {
@@ -4405,6 +4572,12 @@ void GDScriptAnalyzer::reduce_identifier(GDScriptParser::IdentifierNode *p_ident
 			// TODO: Constant should have a value on the node itself.
 			p_identifier->reduced_value = p_identifier->constant_source->initializer->reduced_value;
 			found_source = true;
+
+#ifdef TOOLS_ENABLED
+			if (p_identifier->constant_source->doc_data.is_deprecated) {
+				parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "constant", p_identifier->name);
+			}
+#endif
 			break;
 		case GDScriptParser::IdentifierNode::MEMBER_SIGNAL:
 			p_identifier->signal_source->usages++;
@@ -4424,7 +4597,12 @@ void GDScriptAnalyzer::reduce_identifier(GDScriptParser::IdentifierNode *p_ident
 			if (p_identifier->variable_source && p_identifier->variable_source->assignments == 0 && !(p_identifier->get_datatype().is_hard_type() && p_identifier->get_datatype().kind == GDScriptParser::DataType::BUILTIN)) {
 				parser->push_warning(p_identifier, GDScriptWarning::UNASSIGNED_VARIABLE, p_identifier->name);
 			}
-#endif // DEBUG_ENABLED
+#endif
+#ifdef TOOLS_ENABLED
+			if (p_identifier->variable_source->doc_data.is_deprecated) {
+				parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "property or variable", p_identifier->name);
+			}
+#endif
 			break;
 		case GDScriptParser::IdentifierNode::LOCAL_ITERATOR:
 			p_identifier->set_datatype(p_identifier->bind_source->get_datatype());
@@ -4543,13 +4721,29 @@ void GDScriptAnalyzer::reduce_identifier(GDScriptParser::IdentifierNode *p_ident
 	}
 
 	if (class_exists(name)) {
+#ifdef TOOLS_ENABLED
+		DocTools *dd = EditorHelp::get_doc_data();
+		if (dd && dd->class_list.has(name)) {
+			if (dd->class_list[name].is_deprecated) {
+				parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "class", name);
+			}
+		}
+#endif
 		p_identifier->source = GDScriptParser::IdentifierNode::NATIVE_CLASS;
 		p_identifier->set_datatype(make_native_meta_type(name));
 		return;
 	}
 
 	if (ScriptServer::is_global_class(name)) {
 		p_identifier->set_datatype(make_global_class_meta_type(name, p_identifier));
+#ifdef TOOLS_ENABLED
+		DocTools *dd = EditorHelp::get_doc_data();
+		if (dd && dd->class_list.has(name)) {
+			if (dd->class_list[name].is_deprecated) {
+				parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "class", name);
+			}
+		}
+#endif
 		return;
 	}
 
@@ -4590,6 +4784,14 @@ void GDScriptAnalyzer::reduce_identifier(GDScriptParser::IdentifierNode *p_ident
 					}
 				}
 			}
+#ifdef TOOLS_ENABLED
+			DocTools *dd = EditorHelp::get_doc_data();
+			if (dd && dd->class_list.has(name)) {
+				if (dd->class_list[name].is_deprecated) {
+					parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "class", name);
+				}
+			}
+#endif
 			result.is_constant = true;
 			p_identifier->set_datatype(result);
 			return;
@@ -4607,6 +4809,17 @@ void GDScriptAnalyzer::reduce_identifier(GDScriptParser::IdentifierNode *p_ident
 		}
 		p_identifier->is_constant = true;
 		p_identifier->reduced_value = value;
+
+#ifdef TOOLS_ENABLED
+		DocTools *dd = EditorHelp::get_doc_data();
+		if (dd && dd->class_list.has("@GlobalScope")) {
+			for (const DocData::ConstantDoc &cd : dd->class_list["@GlobalScope"].constants) {
+				if (cd.name == name && cd.is_deprecated) {
+					parser->push_warning(p_identifier, GDScriptWarning::DEPRECATED_IDENTIFIER, "constant", name);
+				}
+			}
+		}
+#endif
 		return;
 	}
 
@@ -5858,6 +6071,12 @@ bool GDScriptAnalyzer::get_function_signature(GDScriptParser::Node *p_source, bo
 		r_return_type.is_meta_type = false;
 		r_return_type.is_coroutine = found_function->is_coroutine;
 
+		// For user-defined methods.
+#ifdef TOOLS_ENABLED
+		if (found_function->doc_data.is_deprecated) {
+			parser->push_warning(p_source, GDScriptWarning::DEPRECATED_IDENTIFIER, "function", found_function->identifier->name);
+		}
+#endif
 		return true;
 	}
 
@@ -5901,7 +6120,20 @@ bool GDScriptAnalyzer::get_function_signature(GDScriptParser::Node *p_source, bo
 		if (native_method && r_native_class) {
 			*r_native_class = native_method->get_instance_class();
 		}
-#endif // DEBUG_ENABLED
+#endif
+#ifdef TOOLS_ENABLED
+		DocTools *dd = EditorHelp::get_doc_data();
+		if (dd) {
+			const Vector<DocData::MethodDoc> &method_list = dd->class_list[base_native].methods;
+			for (const DocData::MethodDoc &doc : method_list) {
+				if (doc.name == function_name && doc.is_deprecated) {
+					parser->push_warning(p_source, GDScriptWarning::DEPRECATED_IDENTIFIER, "function", function_name);
+					break;
+				}
+			}
+		}
+
+#endif
 		return valid;
 	}