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

[Jonathan Gibbons]

On Wed, 31 Jan 2024 22:10:03 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 543:
>> 
>>> 541:                 @Override
>>> 542:                 public LinkReferenceDefinition getLinkReferenceDefinition(String label) {
>>> 543:                     var l = label.replace("\\[\\]", "[]");
>> 
>> That `String.replace` looks suspicious. FWIW, when I removed that `replace`, no tests failed.
>
> My recollection is that you have to escape square brackets in a reference label.  I will investigate, and if necessary, add a test case.

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.

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

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