RFR: JDK-8298405: Implement JEP 467: Markdown Documentation Comments [v43]

[Jonathan Gibbons]

On Thu, 29 Feb 2024 11:39:41 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

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

Generally, I disagree with the policy here.
 
In particular, this suggestion "squashes"/"merges" heading levels at the more significant end of the range (i.e. h1, h2) and not at the least significant end of the range (i.e. h5, h6).  And, while we do specify the required heading levels in "traditional" doc comments, that seems less than optimal. (I note in times past we had to _modify_ the headings in doc comments as a result of the policy).  

Given all that, it seems better/simpler to specify that an author should start the headings in any comment at level 1 and have the tool adjust the level as needed.

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

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