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

[Hannes Wallnöfer]

On Wed, 28 Feb 2024 17:12:04 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> 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".
> 
> I also think it is better to have a simple rule than an "adaptive" rule.  If you start doing a more complex rule, you have to consider the effect on subheadings as well.

I suspected it was about the limited range of Setext headings. Yesterday my proposal was intentionally vague, but thinking about this again I think we should actually do the simplest and least intrusive thing possible:

    // minLevel is 4 for members, 2 for page-level elements, 1 for doc files
    "h" + Math.max(heading.getLevel(), minLevel);

This arguably generates the correct heading for most simple use cases. What it doesn't do is to translate whole hierarchies of headings, but I would argue that few people people need this and those who do should figure out the rules and use the correct ATX headings.

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

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