I've been excitedly waiting for years to finally be able to use Markdown
in Javadocs.
Using Java 25 with the new [JEP 467: Markdown Documentation
Comments](https://openjdk.org/jeps/467), I tried to add the following:
```java
/// @see [Example Site](https://example.com/)
```
Javadoc (invoked by Maven) complained "error: unexpected content", with
a `^` under the ending `)`.
If you look at the [JEP 467](https://openjdk.org/jeps/467) proposal, it
says:
> You can use all other forms of Markdown links, including links to
URLs ….
> …
> The inline and block tags are parsed in the same way as for
traditional documentation comments, except that tag content is also
parsed as Markdown.
I raised this issue on Stack Overflow: [Java 25 Javadoc not allowing
Markdown URL link syntax in
`@see`](https://stackoverflow.com/q/79794040). Someone pointed out that
the JavaDoc specification is really at
https://docs.oracle.com/en/java/javase/25/docs/specs/javadoc/doc-comment-spec.html
. Unfortunately I see that the text about using Markdown links has been
removed.
This is a significant oversight and impediment. Why would would we want
to write Javadoc Markdown everywhere, except treat the `@see` tag specially?
My objective is not to find another way to link to classes or methods. I
truly want to link to a URL. Many things we write are inspired,
influenced, or guided by blog articles or even Stack Overflow. So to
make things meta, if I were writing a Java implementation of Javadoc
parsing I might just reference my own Stack Overflow question:
```java
/// Parses Javadoc Markdown comments and returns a Markdown node tree.
/// @implNote Supports Markdown for the `@see` tag.
/// @see [Java 25 Javadoc not allowing Markdown URL link syntax in
`@see`](https://stackoverflow.com/q/79794040)
```
But that's not allowed. Even worse, it's not even a warning, it's an error!
This presents a huge problem with code generation with LLMs. If I ask an
LLM to generate some documentation for a class, I have to find a way to
explain to it to generate the API documentation using Markdown. Oh, but
wait, LLM, if it's a `@see`, then you must use old-fashioned `<a
href="blah">blah blah</a>`. Oh, but if it's not a URL, but a link to a
class, then you can use Markdown. So the LLM tries to comply , and
instead writes "See also …", but then it uses an old style HTML link, so
I have to tell it that if it uses `See` and not `@see` then it can use a
Markdown URL link.
Do you think the LLM keeps all this straight? Of course not. I don't
blame it. I can't keep it straight. It's one of those, "why, why, why"
moments.
Sorry, went off a bit there. :) I spent a long time just now trying to
convince an LLM of these arbitrary rules when I can't keep them straight
myself.
I respectfully submit that this incongruence be fixed so we can all move
forward toward a consistent, happy, Markdown Javadoc work. Please allow
Markdown URL links in `@see` as soon as possible.
Garret
