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

[Pavel Rappo]

On Fri, 19 Jan 2024 18:37:48 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 with a new target base due to a merge or a rebase. The pull request now contains eight commits:
> 
>  - Merge with upstream/master
>  - Merge with upstream/master
>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>  - Address review comments
>  - Fix whitespace
>  - Improve handling of embedded inline taglets
>  - Customize support for Markdown headings
>  - JDK-8298405: Support Markdown in Documentation Comments

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java line 329:

> 327:         if (doclint == null) {
> 328:             var trees = docEnv.getDocTrees();
> 329:             if (trees.getDocCommentTreeTransformer()== null) {

Suggestion:

            if (trees.getDocCommentTreeTransformer() == null) {

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/RawHtml.java line 145:

> 143:     }
> 144: 
> 145:     Pattern tag = Pattern.compile("<(?<tag>[A-Za-z0-9]+)(\\s|>)");

I'm not sure I grok this pattern; what's up with `\\s`?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/CommentUtils.java line 629:

> 627:     public DocCommentTree parse(URI uri, String text) {
> 628:         return trees.getDocCommentTree(new SimpleJavaFileObject(
> 629:                 uri, JavaFileObject.Kind.HTML) {

Was it a bug before?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Env.java line 139:

> 137:         this.types = types;
> 138: 
> 139:         if (this.trees.getDocCommentTreeTransformer()== null) {

Suggestion:

        if (this.trees.getDocCommentTreeTransformer() == null) {

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1467988621
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1467977203
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1467980609
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1467982493