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

[Pavel Rappo]

On Wed, 8 Nov 2023 22:17:21 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Customize support for Markdown headings

I see you've added a new feature and tests for it.

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?

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

PR Review: https://git.openjdk.org/jdk/pull/16388#pullrequestreview-1723026055
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1388270695