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

[Jonathan Gibbons]

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

>> 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!!!)

You might also need to use `` ` `` when there are two literal backticks in a sentence.

After the first backtick (`), another backtick (`) can be used to delimit a code span.

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

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