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. Authors must cram important guidance inside regular paragraphs that are easy to miss because they blend into the surrounding text and are often scattered and easily overlooked.

There is no easy mechanism for tools such as IDEs to easily distinguish them from regular documentation.

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

See attachment info-diff0.txt.