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

[Jonathan Gibbons]

On Wed, 28 Feb 2024 15:54:38 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> 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?

Setext headings only come in "level 1" and "level 2" flavors.
And, at the time the renderer sees the AST, the difference between ATX and setext headings is erased. They're just "headings".

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

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