The Standard Doclet supports custom block tags and the -tag option to add block-level notes to API elements. However, block tag content is displayed in a dedicated section after the main description of an API element, and the uniform layout of block tag content as a definition list makes it difficult to apply special formatting to individual block tags.

JavaDoc should support an inline {@note} tag to enable block-level notes within the main description of API elements. The tag should support a number of types of notes out of the box, such as info- and warning-styled notes. It should also allow the creation of custom note types. The mechanism to implement custom note types is to be determined, but will likely require new API support in the jdk.javadoc.doclet package.