Summary

Introduce an @snippet tag for JavaDoc's Standard Doclet, to allow Javadoc to suggest replacement APIs.

Problem

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.

Currently, 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.

Solution

Introduce a new block tag @supreseded whose content will be used to indicate replacement APIs.

Specification

doc-comment-spec

### `superseded`

* `@superseded` <text>

This tag is used in conjunction with the @Superseded annotation to indicate replacement APIs.

The standard doclet moves the replacement APIs ahead of the main description (and ahead of any @deprecated text, if present),
placing it in italics and preceding it with a bold warning.

Introduced in JDK 25.