On Wed, 28 Feb 2024 17:12:04 GMT, Jonathan Gibbons <[email protected]> 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
