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

[Jonathan Gibbons]

On Thu, 9 Nov 2023 16:39:58 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Customize support for Markdown headings
>
> test/langtools/jdk/javadoc/doclet/testMarkdown/TestMarkdown.java line 613:
> 
>> 611:                         /// Lorem ipsum.
>> 612:                         ///
>> 613:                         /// ## ATX-style subheading for executable
> 
> Can we use Markdown headings inside block tags, such as `@apiNote`?  If so, should they start from h5? If so, should we get a warning if they "overflow" h6?

Hmm.   teeny-tiny "yes", dominated by a big "BUT".

There is no easy simple direct support for Markdown in user-defined taglets, since there is no way to know the syntactic form of user-defined tags. We might be able to do something for user-defined tags given on the command line (with `-tag`) but in general we should be wary and think carefully about putting any headings inside any block tag, because block tags get converted to HTML definition lists.

---

Separately, generally speaking, the Markdown headings in any doc comment should start at level 1 and increase from there. An offset will be added during translation to give the correct heading level in the overall page. There is a guard in the code (but no warning as yet) if you "overflow" heading level 6.  For example, if you go overboard and use `#### my heading` in the comment for a method (where the offset for headings is 3), it will (currently) max out at level 6.  Generating warnings for questionable Markdown is somewhat against the spirit of Markdown. It would seem a bit weird to warn against an obscure case like overflowing headings when the general policy for real errors is no message and just show the literal text.

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

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