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

[Hannes Wallnöfer]

On Fri, 23 Feb 2024 22:27:43 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:
> 
>   Refactor most of TestMarkdown.java into separate tests, grouped by functionality

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1380:

> 1378: 
> 1379:         var useMarkdown = trees.stream().anyMatch(t -> t.getKind() == Kind.MARKDOWN);
> 1380:         var markdownHandler = useMarkdown ? new MarkdownHandler(element) : null;

The `MarkdownHandler` and `HeadingNodeRenderer` classes must become aware of the current `TagletWriter.Context`.  That's because headings and other block tags should only be generated if `TagletWriter.Context.isFirstSentence` is `false`.

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

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