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

[Jonathan Gibbons]

On Tue, 30 Jan 2024 23:42:40 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 487:
>> 
>>> 485:     }
>>> 486: 
>>> 487:     private static final String AUTOREF_PREFIX = "code:";
>> 
>> I wish the prefix were such that it could not be forged: for example, automatically assigned, unique within a document comment.
>
> I guess I don't see this as being as big a deal as you seem to think it is. What is it that you are so concerned about?
> 
> I also think it is a potential feature to document and use reference links with `code:` URLs, using the reference link syntax to avoid having long method signatures in narrative text.
> 
> For example, 
> 
>    One of the methods on [List] has [lots of args][List.of10].
>    
>    [List.of10]code:List.of(E,E,E,E,E,E,E,E,E,E)

I've changed the prefix to be dynamically generated. It's now called `autorefScheme` and is passed around as needed. It contains a hex hashcode, so is reasonably unguessable.

I'm still sort-of sad to lose the ability to use `code:` URLs directly, so I've left a comment in the code hinting that that is a possibility.

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

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