Add @deprecated annotation

[JeremyStarTM]

Describe the project you are working on

A framework written in GDScript

Describe the problem or limitation you are having in your project

I want to deprecate a function

Describe the feature / enhancement and how it helps to overcome the problem or limitation

A @deprecated annotation that requires a custom message and a bool if the func/var will be removed in a future version

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

Example with custom message, will not be removed in future version

@deprecated("Has been moved to SomeObject.some_variable, will be kept for compatibility",false)
var some_variable: String = "Some cool variable"

@deprecated("May be inaccurate, use do_that_thing() instead",false)
func do_something() -> void:

Example with a custom message, will be removed in a future version

@deprecated("Has been replaced with SomeGlobalScript.get_some_stuff() and will be removed in the next major release",true)
var some_important_stuff: String = "Something very useful"

@deprecated("Is known to cause major issues and will be removed in the next release",true)
func will_cause_issues() -> void:

If this enhancement will not be used often, can it be worked around with a few lines of script?

A simple function like this could do the job:

func deprecate_message(script:String,function_variable:String,message:String,to_be_removed:bool) -> void:
 if to_be_removed:
  assert(false,"The function/variable \"" + function_variable + "\" in script \"" + script + "\" will be removed in a future version. Message: " + message)
 else:
  assert(false,"The function/variable \"" + function_variable + "\" in script \"" + script + "\" has been deprecated. Message: " + message)

Is there a reason why this should be core and not an add-on in the asset library?

I don't think that a addon can add a custom annotation

Why should this proposal be implemented into the engine?

1. It would benefit modders/modloaders
2. It would help addon developers
3. Saving headaches if a addon's function that your project is relying on and is used heavily in your project is suddenly removed and requires major code refactors or even a rewrite to fix, where this annotation would allow for a smooth(er) transition.

[AThousandShips]

Already implemented in:

• GDScript: Add @deprecated and @experimental doc comment tags godot#78941

Though without adding a reason

[JeremyStarTM]

The issue #78941 is about the documentation, not about the engine. Or am I wrong somehow?

[dalexeev]

• See also Add @deprecated annotation to GDScript #6559.

This would be useful not only for scripts, but also for built-in classes. We probably need a system to get the info from ClassDB or something else (since Variant types and scripts are not registered in ClassDB).

However, we can make GDScript get the info from DocData and generated warnings. Not sure if this is correct.

[JeremyStarTM]

Added a little info that this would be useful for modloaders/modders and addon developers. Added two examples for variables too.

[dalexeev]

It might look like this:

## @deprecated: Has been moved to [member SomeObject.some_variable], will be kept for compatibility.
var some_variable: String = "Some cool variable"

## @deprecated: May be inaccurate, use [method do_that_thing] instead.
func do_something() -> void:

There are no messages because core doesn't support it (is_deprecated and is_experimental are booleans, not strings).

[JeremyStarTM]

Why not add support for it then? Although it would be too much for such a simple feature addition. And if developers are smart enough to search for things, they should be smart enough too look into the documentation and see it's deprecated and why.