Hi Jon, Thanks for the feedback! Some answers below.
On 29.08.2026, at 21:19, Jonathan Gibbons <[email protected]> wrote: 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. Thanks, and agreed. Speaking of Markdown comments, there is one area where we discovered a problem with the current syntax, which is usage of square brackets `[]` for attributes. In a Markdown comment beginning with a link, the initial link would currently be mistaken for attributes. We are therefore considering to replace the square brackets for attributes with something else, such as ordinary parentheses. 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 agree we could add some guidance for use of default ids. Block level notes are usually quite stable, as the `<dt>` elements for specific block tags are basically singletons (only one element is created even with multiple notes). So we simply append the tag name to the id of the enclosing element separated by a hyphen. So for `@apiNote` of `Object.equals(Object)` the id is `equals(java.lang.Object)-apiNote`. https://cr.openjdk.org/~hannesw/javadoc-notes/api.07/java.base/java/lang/Object.html#equals(java.lang.Object) https://cr.openjdk.org/~hannesw/javadoc-notes/api.07/java.base/java/lang/Object.html#equals(java.lang.Object)-apiNote For inline notes, and the rare case where there are multiple block notes with the same tag, we create ids with an ordinal number for the note markup. https://cr.openjdk.org/~hannesw/javadoc-notes/api.07/java.base/java/lang/Character.html#isLowerCase(char) https://cr.openjdk.org/~hannesw/javadoc-notes/api.07/java.base/java/lang/Character.html#isLowerCase(char)-note1 So block note ids are usually more stable than instance note ids, and it might be a good idea to point that out in the JEP. 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.) We do have some icons in JavaDoc, but I like to keep their use to a minimum. In this case, adding icons would have made the feature more prone to bikeshedding than it already is. Also, we don’t have a graphic designer on the team. The JEP mentions that notes can be styled via CSS. I would argue that a savvy CSS user probably knows that it is possible to add icons via stylesheets. But it wouldn’t hurt to mention it as an example of customisation via CSS. 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". We have the programmer’s guide to JavaDoc CSS themes: https://docs.oracle.com/en/java/javase/21/javadoc/javadoc-css-themes.html This is a few years old. There are probably a few things that have changed or have been added, so it would be a good idea to go over it at some time. Thanks again for your feedback! Hannes -- 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
