There are many outdated APIs, such as java.util.Vector, java.util.Stack, java.util.StringTokenizer, java.util.LinkedList, that sometimes appear in newly written code. These classes have specifications that ask to use replacements, but those are unremarkable and easily ignored. Meanwhile, deprecation is overkill as usage of these APIs should not generate new compiler warnings in legacy code.

It would be great if javadoc had a consistent and specified way of suggesting newer APIs that displays such suggestions in a straightforward way, similar to preview or deprecation warning boxes.

A `@SupersededBy` annotation could be used by IDEs to suggest the replacement API.