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.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 271:

> 269: //                        if (textStart == -1) {
> 270: //                            textStart = bp;
> 271: //                        }

What's up with that?

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1333:

> 1331:                     lineKind = (ch == '\n' || ch == '\r') ? LineKind.BLANK
> 1332:                             : (indent <= 3) ? peekLineKind()
> 1333:                             : LineKind.OTHER;

Nested ternary-s are hard to read. Nested if-s are bulky. Sigh.

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1377:

> 1375:          * @see <a href="https://spec.commonmark.org/0.30/#atx-headings">ATX Headings</a>
> 1376:          */
> 1377:         ATX_HEADER(Pattern.compile("#{1,6}( .*|$)")),

Actually, I wonder how accurate those regexes should match spec. Given the definition [^*] of an ATX header and the fact that we always match the complete (not find inside) a line, which by definition should not have line terminators, shouldn't it be like this?

    #{1,6}([ \t]+.*)?

[^*]: The opening sequence of # characters must be followed by spaces or tabs, or by the end of line.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1462039425
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1462213698
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1462148038