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

[Hannes Wallnoefer]

Hi Garret,

I understand how one might expect that Markdown links should work in @see tags of Markdown comments.

The thing is that @see does not accept arbitrary rich content like some other tags do, so it is not processed as Markdown. Rather, it supports three specific forms that serve different purposes:: https://docs.oracle.com/en/java/javase/25/docs/specs/javadoc/doc-comment-spec.html#see

So basically we’d have to add a fourth form to support Markdown links. While this is not out of the question, it’s not a trivial task either. There’s a number of issues that have to be addressed, such as whether this should only work in Markdown comments or also traditional doc comments, whether it supports only URLs or also API references, and probably a few more.

A first step to evaluate these questions might be to file an enhancement issue at https://bugs.openjdk.org/.

Hannes


On 07.11.2025, at 01:04, Garret Wilson <garret at globalmentor.com> wrote:

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


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/javadoc-dev/attachments/20251107/58002716/attachment-0001.htm>