Java 23 Markdown comments - external links

Question

Java 23 now allows Markdown Documentation Comments

I am experimenting with this feature right now in latest IntelliJ IDEA 2024.2.2 (community) and with GraalVM for JDK 23 as Java runtime. It seems the IDE cannot handle external links in traditional markdown syntax:

/// This is a **Markdown** comment
/// @see [Markdown Documentation Comments - in MD](https://openjdk.org/jeps/467)
/// @see <a href="https://openjdk.org/jeps/467">Markdown Documentation Comments - in HTML</a>

The HTML link renders fine, but markdown is broken:

Also, the latest version of Apache Maven Javadoc Plugin (3.10.0) fails to render such link. It skips it completely:

Is this a bug yet to be fixed or did I overlooked something in the docs that prevents me from writing external links like that? In the JEP description and on Oracle JavaDoc guide I found not a word about treating external links.

Bourse

The @see tag is a bit strange, in that it has a number of pretty specific formats. The <a href form, for example, isn't arbitrary HTML but rather a specific variant of the @see format. I am a bit surprised the markdown doesn't render correctly... but not shocked. Does it work if you surround the string with quotes? "[Markdown Documentation .../467)"? That's one of the listed formats. – Sinful

A-ha! It still doesn't work with surrounding in quotes. But, it DOES work, if I omit the @see tag – Bourse

Where is this 'rendering'? In the 'javadoc' view in intellij? What I'm missing in this question is a clear indication of what actual code is failing to properly process the comment. "The apache maven javadoc plugin vwhatever" is not a good answer to this question: That plugin doesn't process javadoc in any way. It merely passes your source files to the javadoc tool that is part of your JDK distro. That tool processes your markdown comments, and there is no link between the plugin's version and OpenJDK version. – Yulandayule

It seems that the first word after @see ([Markdown in your case) is interpreted by Javadoc and only the rest (Documentation Comments - in MD](https://openjdk.org/jeps/467)) is processed as Markdown. Does @see <a href=""></a> [Markdown ... /467) work? – Rivalry

@HeikoTheißen no, this doesnt work either. HTML anchor renders, but markdown remains as it is (not processed) – Bourse

For cutting edge features, I’d be using the latest early-access version. blog.jetbrains.com/idea/2024/09/intellij-idea-2024-3-eap-2 – Psychodynamics

Given the JEP explicitly says "Instances of block tags, such as \@implSpec, \@return, and \@see, are generally unaffected except that the content of these tags is now also in Markdown", I'd say it is a bug in the javadoc tool. AFAIK, the Maven Javadoc Plugin does nothing other than calling the javadoc tool (through code rather than commandline, IIRC) of your current JDK. – Trice