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

[Jonathan Gibbons]

On Wed, 31 Jan 2024 23:09:57 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Yes, you need to escape `[` and `]` within the label of any Markdown reference link, by preceding each with backslash.   (Remember, the label is the string used to find the URL for the link; not the displayed text of the link).
>> That's a CommonMark feature independent of this work.
>> 
>> While we could change that `replace` call into two separate ones, in reference signatures they always appear together as a pair, and can be replaced together.   We need to remove the escape characters in the generated URL so that the signature is a standard signature with unescaped `[]`
>> 
>> For fun/demo, try the following:
>> 
>> 
>> /// First sentence.
>> /// * Link 0 to [java.lang.Object]
>> /// * Link 1a to [Arrays-equals][java.util.Arrays#equals(Object[],Object[])]
>> /// * Link 1b to [Arrays-equals][java.util.Arrays#equals(Object[],Object[])]
>> /// * Link 2a to [java.util.Arrays#equals(Object[],Object[])]
>> /// * Link 2b to [java.util.Arrays#equals(Object[],Object[])]
>> public class C { }
>> 
>> 
>> Link 1a and 2a end up as unprocessed "literal" text (because the `[]` were not escaped.)  That is, they are not even recognized by the CommonMark parser as reference links.  Link 1b and 2b get processed as links, as expected.
>> 
>> FWIW, this issue with needing to escape `[]` pairs is specifically mentioned in the JEP as an inescapable (sic) limitation.
>
> I'll add a test case.

Done

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

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