Summary

Support references to parameterized types in @see and {@link} documentation comment tags.

Problem

Despite parameterized types being in the language since JDK 5, they are still not supported in javadoc tags like @see and {@link}. This means that references either have to use raw types, or else authors try to emulate, with varying degrees of success, what javadoc might do if this feature were natively supported.

Solution

Allow parameterized types to appear where type names can currently appear in @see and {@link} tags.

All reference types appearing in such tags should be linked to the appropriate declaration, when available, using the standard doclet linking mechanisms (i.e to a declaration in the same doc bundle, or to declaration elsewhere, using the -link or -linkoffline options.)

The existing spec merely says that a reference is of the form

package.class#member

without giving any more fine-grained detail.

It will be clarified to say that parameterized types may be used in the class and member parts of the signature.

Specification

The diff to the Documentation Comment Specification for the Standard Doclet is attatched to this issue and displayed inline below:

diff -r e9e4b819eaa5 closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md
--- a/closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md    Thu Apr 23 05:01:04 2020 +0200
+++ b/closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md    Thu Apr 23 16:28:10 2020 +0200
@@ -307,7 +307,8 @@
 referenced, such as a package, class, interface, constructor, method or field
 name. Parts of the name can be omitted as appropriate. The class represents any
 top-level or nested class or interface. The member represents any constructor,
-method, or field (not a nested class or interface). If this name is in the
+method, or field (not a nested class or interface). Parameterized types may be
+used in the class and member parts of the name. If this name is in the
 documented classes, then the standard doclet creates a link to it.

 To create links to external referenced classes, use the `-link` option.