Hannes, team, Generally, the feature looks great, and continues the trend of the past many years to improve markup support for API authors. I like the use of attributes, to make the new tags more versatile, and I like the use of bimodal tags that can be used inline or as block tags. I like that it provides focused replacement for common HTML idioms in API documentation, and presumably works in both traditional- and Markdown-style doc comments.
On ids, you say that one will be generated if one is not provided. You could give more details about that, providing guidelines as to how stable the generated id will be. You might consider optionally generating warnings when a link URL refers to an automatically generated ID, although it would be one of those unfair warnings given at the use site, not the declaration site! I like the provision of kinds, and the hint that the visual severity of a note can be controlled by the end user (author) in CSS. I was going to ask about the use of icons and emojis, but I guess they can also be added automatically and consistently using CSS. It might be worth adding a note to that effect (sic.) Speaking to the abstract world in general, "it would be nice" to have some sort of guide for using stylesheets in JavaDoc. In times past, one could imagine this being a blog entry of some sort. These days, there is the JavaDoc Guide (https://docs.oracle.com/en/java/javase/26/javadoc/index.html) which I note does have a good section on the use of CSS themes. Maybe there could be some sort of related page for "more neat things you can do with JavaDoc stylesheets". -- Jon On Thu, Aug 27, 2026, at 7:56 AM, Hannes Wallnoefer wrote: > Hi everyone, > > > > We've been working on a new JavaDoc feature and would love to get some > feedback from the community. > > > > The feature adds a new standard @note tag for adding rich notes to API > documentation and expands the capabilities of custom tags generated by the > existing -tag option. Notes can be used as both inline and block tags, and > they support attributes to customize their appearance. > > > > All the details are described in JEP JDK-8363700: Rich Notes in Java API > Documentation[1]. > > > > [1]: https://bugs.openjdk.org/browse/JDK-8363700 > > > > A fairly mature implementation is available in a GitHub pull request[2]. > > > > [2]: https://github.com/openjdk/jdk/pull/28358 > > > > There’s also another pull request exploring the use of the new feature in the > JDK[3]. A good way to get an understanding of the feature (after reading the > JEP of course) is to look at the changes in this PR and then view the output > in the uploaded API docs. > > > > [3]: https://github.com/openjdk/jdk/pull/31023 > > > > We are interested in hearing from you whether the feature, as planned, meets > your needs for documenting Java code, and of course whether you think there’s > anything we’ve missed or could improve. > > > > Please reply to this thread with your thoughts. We look forward to your > feedback. > > > > Hannes > >
