Summary

Introduce an @info tag for JavaDoc's Standard Doclet, to provide additional information about API usage, replacements, security concerns, guidance, and other important notes.

Problem

Existing javadoc mechanisms lack a standarized and flexible way to highlight important API details.

Outdated APIs have replacement suggestions in their javadoc, but these are often scattered and easily overlooked.

Solution

Introduce a new block tag @info whose content will be used to indicate replacement APIs. It can be used to suggest replacement APIs, highlight security concerns and other information to know before using an API.

The text for that will be more prominent in API docs, and to give something that tools (including IDEs) can use to provide advice.

Specification

doc-comment-spec.md

### `info`

* `@info` <text>

Highlights important details about an API. The standard doclet renders the information prominently.

Developers can use the tag to communicate security considerations, performance implications, recommended practices, usage warnings, and other important information.

Introduced in JDK 25.