On Wed, 31 Jan 2024 23:09:57 GMT, Jonathan Gibbons <j...@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