Feature Request: Allow specifying a replacement type in @Deprecated annotation

[stan-at-work]

Problem

Currently, when marking something as @Deprecated, we have to manually specify the recommended replacement in the message string:

@Deprecated("Don't use this anymore, use CoreScannerState<T>")

This requires manual parsing of the message by the developer and does not provide a structured way for tooling to suggest replacements.

Proposed Solution

Introduce a replacement parameter in the @Deprecated annotation that explicitly defines the alternative type or member:

@Deprecated("Don't use this anymore", replacement: CoreScannerState<T>)

Benefits:

• The IDE can automatically extract and display the replacement.
• Tooling can provide direct refactoring suggestions.
• The message remains clear while keeping metadata structured.

Current Behavior

When hovering over a deprecated member, the IDE tooltip says:

"... Try replacing the use of the deprecated member with the replacement."

However, "the replacement" is not configurable, and the developer must manually read and interpret the message.

Expected Behavior

By allowing a replacement argument, the IDE and tools can explicitly guide developers on what to use instead.

[FMorschel]

This reminds me of #60244.

CC @bwilkerson

[lrhn]

You can't always just replace with a simple thing.
Sometimes you need to import a different library and use the same name.
Sometimes you need to change the order of parameters, or add or remove ones.
Sometimes you change from a static method to an instance method of some (static-accessible) value.

The example here, replacement: CoreScannerState<T>, won't compile because T is not in scope.
I find it more likely that a string representation, or some more complicated "replacement" construct will work, but then you could probably just write a data-based fix for it.
(Some help writing that fix would be nice, though, say "I see that you've written 'use FooBar instead' in the Deprecated message. Should I create a data-based fix for that? Sincerely, Clippy." or whatever we can do today.)

[bwilkerson]

As Lasse pointed out, the number of kinds of metadata users would need to be able to express is quite large and would be hard to fit into an annotation. In addition, the deprecated annotations are expected to be removed at some point, at which time the IDE looses the ability to use that metadata.

Because of these problems we decided to support a mechanism we refer to as data-driven fixes. This allows for the same kind of metadata you're asking for and more, but the metadata is located in a YAML file in the lib directory. This support has been successfully used by the Flutter team and by the maintainers of the Dart SDK for several years.

There is some reference-style documentation for it, but there isn't yet any documentation explaining how to write such a file. Many common kinds of refactorings can be represented, but there are refactorings that there currently isn't any way to express. It will certainly handle simple renames like the one in the original posting, though, so I'd encourage you to give it a try.

Because we already have a solution for this, I'm going to close this issue.