RFR: JDK-8298405: Support Markdown in Documentation Comments [v43]

[Hannes Wallnöfer]

On Fri, 23 Feb 2024 22:27:43 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Refactor most of TestMarkdown.java into separate tests, grouped by functionality

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1601:

> 1599:                         : eKind != ElementKind.OTHER ? 1   // module, package, class, interface
> 1600:                         : 0; // doc file
> 1601:                 return "h" + Math.min(heading.getLevel() + offset, 6);

I really like that we adapt the heading level to the current context, but I notice that the code kind of expects `h1` headings to be used everywhere, and "punishes" use of contextually correct headings by generating smaller headings. Maybe it would be more educational to only adjust the level if it needs adjusting?

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1506190847