Java 25 Javadoc not allowing Markdown URL link syntax in `@see`

JEPs aren't actually specs. You're looking for the JavaDoc Documentation for the Standard Doclet (JDK25).

From the markdown section of that spec:

Both inline tags and block tags may be used in Markdown documentation comments, although neither may be used within the literal text of code spans and fenced or indented code blocks.

For those tags that may contain text with markup, in a Markdown documentation comment that markup will also be in Markdown format.

Emphasis mine.

@see is not a tag that may contain text with markup. At least, I don't think so; this spec is not written nearly as exactingly precise as what we're used to with e.g. the Java Language Spec, and term "a tag that may contain text with markup" is not actually defined. The docs for the @see tag seem pretty clear though: It offers 3 different options and the list ends there. There's room for markup within the confines of one of those 3 choices, but the @see tag itself does not allow it (it allows only 3 things, and within those 3 things, those might allow it).

Solution A - accept it

I think your best option is to accept it and not try to get OpenJDK to 'fix' it. @see is already quite markdownesque in what it allows. For example, this is and has always been legal:

/**
 * @see SomeClass#someMethod The wrapped method
 */

Which results in the text of the link being 'The wrapped method', that then links to someMethod's javadoc.

What you presumably want is to write:

/// @see [The wrapped method][SomeClass#someMethod]

And there's some value in being able to keep things consistent, and to be able to just text-edit your source file and easily turn a @see into an inline link and vice versa, which you can't do with 'old style @see'. However, if your aim is to make the docs readable in raw text form, then the old @see is, if anything, superior; the brackets don't add anything given that @see already implies we're writing links.

Solution B - inline it

You can always just do this:

instead of:

/// My fun method
///
/// @see SomeClass#someMethod The wrapped method
public void whatever() { ... }

write:

/// My fun method
///
/// see: [The wrapped method][SomeClass#someMethod]
public void whatever() { ... }

It's very slightly annoying that the semantic structure of your javadoc is modified by this, but not pertinently so: The semantic difference between a link mentioned inline vs one mentioned in an @see is virtually invisible. I believe the default doclet sticks the @see stuff at the very end, whereas with this, e.g. params, return description, and exception descriptions would all be below your pseudo-inlined link.

If that's a real problem...

Solution C - the OpenJDK mailing lists

Given that it isn't a bug, and OpenJDK's bug tracker is not for feature requests (and not open to the public), it's not the right venue to raise the topic. Instead, the openjdk mailing lists are. They are public.

The one that is probably the most relevant is javadoc-dev.