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

[Jonathan Gibbons]

On Thu, 15 Feb 2024 17:03:09 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 44 commits:
>> 
>>  - fill in `visitRawText` in `CommentHelper.getTags` visitor
>>  - fixes for the "New API" page
>>  - change "standard" to "traditional" when referring to a comment
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>>  - improve support for DocCommentParser.LineKind
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the
>>    commit.
>>  - update copyright year on test
>>  - refactor recent new test case in TestMarkdown.java
>>  - address review feedback
>>  - ... and 34 more: https://git.openjdk.org/jdk/compare/8765b176...2801c2e1
>
> 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.

> 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()`)

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

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