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

[Jonathan Gibbons]

On Thu, 15 Feb 2024 17:17:46 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 422:
> 
>> 420:                             defaultContentCharacter();
>> 421:                         }
>> 422:                     }
> 
> Is it to pass `` through to Markdown, to allow it to deal with Markdown escapes?

It is more about supporting the sequence `` ` `` so that the backtick is treated as a literal character and not the beginning of a code span.   This is the "backstop" preferred way to ensure that a single backtick is treated literally, without relying on detected that it is unbalanced when the end of the current block is reached.  The alternative workaround would be a single backtick enclosed in multiple backticks, such as this ``` `` ` `` ```. (I leave you to figure out what I actually typed there!!!)

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

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