JDK 28 proposes a JavaDoc tag for notes and warnings
Victoria Shinder2 min readThe OpenJDK Quality Group has sent a heads-up to the projects in its Quality Outreach programme: JDK 28 proposes a new JavaDoc tag, @note, for marking tips and warnings inside API documentation. The write-up is by Billy Korando, dated 23 September 2026, at https://inside.java/2026/09/23/quality-heads-up/.
The tag works inline or as a block. The body renders as a text block under a heading that defaults to Note:, with a vertical bar down the left for the inline form. The generated HTML carries the CSS class block-note or inline-note, so a project can style it.
Attributes go in parentheses before the body, as name=value pairs. The Standard Doclet recognises header, which changes the heading, kind, which is emitted as a further CSS class, and id. A note written with a header of Caution: renders under that word instead of under Note:.
And javadoc -tag is being extended to alias the new tag, which is how a project defines its own: an alias declared as warning:A:Warning: makes {@warning ...} behave as a @note with its own heading.
What it means
This is markup catching up with something every large codebase already does by hand. Warnings about a method's edge cases are written today as an ordinary paragraph, or in bold, or with a convention the team invented, and a tool reading the documentation cannot tell them apart from prose. A tag gives the warning a name in the generated HTML, which is the first step to anything mechanical: extracting them, linting for them, rendering them consistently across a multi-repository documentation set.
The kind attribute is the part worth watching, because it turns into a CSS class, and a CSS class is where a convention becomes a contract. A team that settles on a kind of thread-safety gets something a script can find; a team that keeps writing bold paragraphs does not.
⚠️ This is a proposal under Quality Outreach, not a shipped feature: the programme exists so that FOSS projects test against early builds and report back before a release is fixed. The issue JDK-8363700 and the javadoc-dev mailing list are named in the post as the route for feedback.