please allow Markdown URL links in JEP 467 `@see`

[Garret Wilson]

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