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

[Pavel Rappo]

On Thu, 15 Feb 2024 19:20:23 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1401:
>> 
>>> 1399:      */
>>> 1400:     enum LineKind {
>>> 1401:         BLANK(Pattern.compile("[ \t]*")),
>> 
>> `BLANK` is a pseudo kind, because it is set manually, but never returned from `peekLine()`. I wonder if we can change it somehow.
>
> Even if it is set manually, it is still appropriate to have it as a member in the `LineKind` enum class.

Not that it invalidates your reply; clarification: I meant `peekLineKind()`, not `peekLine()`.

>> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1433:
>> 
>>> 1431:          * @see <a href="https://spec.commonmark.org/0.30/#list-items">List items</a>
>>> 1432:          */
>>> 1433:         BULLETED_LIST_ITEM(Pattern.compile("[-+*] .*")),
>> 
>> This comment is about `BULLETED_LIST_ITEM` and `ORDERED_LIST_ITEM` constants. I know that we don't need to be very precise, but perhaps in this case we should. While the CommonMark spec is a vague on that, from my experiments with [dingus](https://spec.commonmark.org/dingus/), it appears that a list marker can be preceded and followed by some number of whitespace characters.
>
> whitespace is handled separately, on line 280 (`readIndent`) and285 (`: (indent <= 3) ? peekLineKind()`)

Correct, but I believe the ordered list marker should be like this:

    ORDERED_LIST_ITEM(Pattern.compile("[0-9]{1,9}[.)] .*"))
                                                     ^

Note extra whitespace character. I think we should really add this to our tests, since lists are foundational Markdown structures, probably right after italics and bold.

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

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