Summary

Allow the @link, @linkplain and @see tags to refer to arbitrary page anchors in JavaDoc-generated documentation.

Problem

The @link, @linkplain and @see tags can currently only be used to refer to JavaDoc-generated documentation of language elements. It would be useful to allow these tags to refer to arbitrary URI fragments in the generated documentation.

Solution

Provide an alternative form for references in @link, @linkplain and @see to specify links to arbitrary anchors in JavaDoc-generated pages. The alternative form uses a double hash mark (##) to distinguish it from language element references.

Unlike for language element references, the reference label is mandatory for fragment references.

An alternative solution would have been to use a single hash mark (#) as separator token like we do for member references, and detect non-member references by the presence of special characters which are not allowed in member names, such as a dash (-). However, this solution is less explicit and therefore less recognizable, and it restricts the names of usable fragment identifiers.

Specification

The following diff describes the changes in the Documentation Comment Specification for the Standard Doclet:

--- a/closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md
+++ b/closed/src/jdk.javadoc/share/specs/javadoc/doc-comment-spec.md
@@ -175,6 +175,15 @@ package or class with the same name.
 _Note:_ you cannot refer to the declaration of a specific parameter or record
 component with this form.

+An alternative form is provided to generate references to arbitrary URI
+fragments in the generated documentation such as headings in documentation
+comments. This form uses a double hash mark (`##`) as separator:
+
+* _module_`/`_package_`.`_class_`##`_fragment_
+
+_fragment_ is interpreted as URI fragment within the page documenting the
+specified program element.
+
 Other tags, such as [`@param`](#param), [`@throws`](#throws), and
 [`@serialField`](#serialfield) may only provide support for the specific
 kinds of references that are relevant to each tag.
@@ -571,10 +580,11 @@ the `javadoc` command run.
 Use either of the other two `@see` tag forms to refer to the documentation of a
 name that does not belong to a referenced class.

-_label_ is optional text to be used as the link label. The label can
-contain whitespace characters. If no label is provided, a default is generated,
-based on the target of the reference. Use the label when you want the
-text to be different from the auto-generated text.
+_label_ is text to be used as the link label and is optional for references to
+program elements. If no label is provided for an element reference, a default
+is generated, based on the target of the reference. Use the label when you want
+the text to be different from the auto-generated text. For references to URI
+fragments a label must be provided. The label can contain whitespace characters.

 Introduced in JDK 1.0.