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

[Jonathan Gibbons]

On Wed, 15 Nov 2023 00:58:51 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

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

Update: 
Markdown in tags defined by the user on the command-line works pretty much as expected: not great, but not bad.

Headings in user-defined tags work, but are semantically questionable, since the tags are generated inside a definition list (which itself is maybe questionable, these days.). There is (currently) no special accommodation for the "virtual heading" in the presentation of the block tag.

Headings, sections, HTML 5, Markdown and taglets are a complicated mess, and probably better discussed and tracked in JBS.

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

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