8313931: Javadoc: links to type parameters actually generate links to classes

Reviewed-by: jjg

Author: hns

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriter.java

@@ -37,6 +37,7 @@
 import javax.lang.model.element.Name;
 import javax.lang.model.element.PackageElement;
 import javax.lang.model.element.TypeElement;
+import javax.lang.model.element.TypeParameterElement;
 import javax.lang.model.element.VariableElement;
 import javax.lang.model.type.TypeMirror;
 import javax.lang.model.util.SimpleElementVisitor8;
@@ -155,7 +156,7 @@ protected void buildClassTree(Content classContent) {
      * @param target the content to which the documentation will be added
      */
     protected void buildClassInfo(Content target) {
-        Content c = HtmlTree.DIV(HtmlStyles.horizontalScroll);
+        var c = new ContentBuilder();
         buildParamInfo(c);
         buildSuperInterfacesInfo(c);
         buildImplementedInterfacesInfo(c);
@@ -164,11 +165,13 @@ protected void buildClassInfo(Content target) {
         buildInterfaceUsageInfo(c);
         buildNestedClassInfo(c);
         buildFunctionalInterfaceInfo(c);
-        buildClassSignature(c);
-        buildDeprecationInfo(c);
-        buildClassDescription(c);
-        buildClassTagInfo(c);
-
+        c.add(new HtmlTree(HtmlTag.HR));
+        var div = HtmlTree.DIV(HtmlStyles.horizontalScroll);
+        buildClassSignature(div);
+        buildDeprecationInfo(div);
+        buildClassDescription(div);
+        buildClassTagInfo(div);
+        c.add(div);
         target.add(getClassInfo(c));
     }
 
@@ -432,19 +435,45 @@ private void setRecordDocumentation(TypeElement elem) {
     protected Content getHeader(String header) {
         HtmlTree body = getBody(getWindowTitle(utils.getSimpleName(typeElement)));
         var div = HtmlTree.DIV(HtmlStyles.header);
-        HtmlLinkInfo linkInfo = new HtmlLinkInfo(configuration,
-                HtmlLinkInfo.Kind.SHOW_TYPE_PARAMS_AND_BOUNDS, typeElement)
-                .linkToSelf(false);  // Let's not link to ourselves in the header
         var heading = HtmlTree.HEADING_TITLE(Headings.PAGE_TITLE_HEADING,
                 HtmlStyles.title, Text.of(header));
-        heading.add(getTypeParameterLinks(linkInfo));
+        heading.add(getTypeParameters());
         div.add(heading);
         bodyContents.setHeader(getHeader(PageMode.CLASS, typeElement))
                 .addMainContent(MarkerComments.START_OF_CLASS_DATA)
                 .addMainContent(div);
         return body;
     }
 
+    // Renders type parameters for the class heading, creating id attributes
+    // if @param block tags are missing in doc comment.
+    private Content getTypeParameters() {
+        var content = new ContentBuilder();
+        var typeParams = typeElement.getTypeParameters();
+        if (!typeParams.isEmpty()) {
+            // Generate id attributes if @param tags are missing for type parameters.
+            // Note that this does not handle the case where some but not all @param tags are missing.
+            var needsId = !utils.hasBlockTag(typeElement, DocTree.Kind.PARAM);
+            var linkInfo = new HtmlLinkInfo(configuration,
+                    HtmlLinkInfo.Kind.SHOW_TYPE_PARAMS_AND_BOUNDS, typeElement)
+                    .linkToSelf(false);  // Let's not link to ourselves in the header
+            content.add("<");
+            var first = true;
+            for (TypeParameterElement t : typeParams) {
+                if (!first) {
+                    content.add(",").add(new HtmlTree(HtmlTag.WBR));
+                }
+                var typeParamLink = getLink(linkInfo.forType(t.asType()));
+                content.add(needsId
+                        ? HtmlTree.SPAN_ID(htmlIds.forTypeParam(t.getSimpleName().toString(), typeElement), typeParamLink)
+                        : typeParamLink);
+                first = false;
+            }
+            content.add(">");
+        }
+        return content;
+    }
+
     protected Content getClassContentHeader() {
         return getContentHeader();
     }
@@ -473,7 +502,6 @@ public TypeElement getCurrentPageElement() {
     }
 
     protected void addClassSignature(Content classInfo) {
-        classInfo.add(new HtmlTree(HtmlTag.HR));
         classInfo.add(new Signatures.TypeSignature(typeElement, this)
                 .toContent());
     }

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java

@@ -462,6 +462,22 @@ public static HtmlId forText(String text, Map<String, Integer> counts) {
         return HtmlId.of(count == 0 ? base : base + "-" + count);
     }
 
+    /**
+     * Returns an id for text documenting a type parameter of a class or method.
+     *
+     * @param paramName the name of the type parameter
+     * @param owner the enclosing element
+     *
+     * @return the id
+     */
+    public HtmlId forTypeParam(String paramName, Element owner) {
+        if (utils.isExecutableElement(owner)) {
+            return HtmlId.of(forMember((ExecutableElement) owner).getFirst().name()
+                    + "-type-param-" + paramName);
+        }
+        return HtmlId.of("type-param-" + paramName);
+    }
+
     /**
      * Returns an id for one of the kinds of section in the pages for item group summaries.
      *

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlLinkFactory.java

@@ -162,9 +162,11 @@ public Content visitTypeVariable(TypeVariable type, HtmlLinkInfo linkInfo) {
                     Element owner = typevariable.asElement().getEnclosingElement();
                     if (linkInfo.linkTypeParameters() && utils.isTypeElement(owner)) {
                         linkInfo.setTypeElement((TypeElement) owner);
-                        Content label = newContent();
-                        label.add(utils.getTypeName(type, false));
-                        linkInfo.label(label).skipPreview(true);
+                        if (linkInfo.getLabel() == null || linkInfo.getLabel().isEmpty()) {
+                            Content label = newContent();
+                            label.add(utils.getTypeName(type, false));
+                            linkInfo.label(label).skipPreview(true);
+                        }
                         link.add(getClassLink(linkInfo));
                     } else {
                         // No need to link method type parameters.
@@ -242,6 +244,11 @@ protected Content getClassLink(HtmlLinkInfo linkInfo) {
             boolean isTypeLink = linkInfo.getType() != null &&
                      utils.isTypeVariable(utils.getComponentType(linkInfo.getType()));
             title = getClassToolTip(typeElement, isTypeLink);
+            if (isTypeLink) {
+                linkInfo.fragment(m_writer.configuration.htmlIds.forTypeParam(
+                        utils.getTypeName(utils.getComponentType(linkInfo.getType()), false),
+                        typeElement).name());
+            }
         }
         Content label = linkInfo.getClassLinkLabel(configuration);
         if (linkInfo.getContext() == HtmlLinkInfo.Kind.SHOW_TYPE_PARAMS_IN_LABEL) {

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/script.js.template

@@ -232,6 +232,20 @@ document.addEventListener("readystatechange", (e) => {
 });
 document.addEventListener("DOMContentLoaded", function(e) {
     setTopMargin();
+    // Reset animation for type parameter target highlight
+    document.querySelectorAll("a").forEach((link) => {
+        link.addEventListener("click", (e) => {
+            const href = e.currentTarget.getAttribute("href");
+            if (href && href.startsWith("#") && href.indexOf("type-param-") > -1) {
+                const target = document.getElementById(decodeURI(href.substring(1)));
+                if (target) {
+                    target.style.animation = "none";
+                    void target.offsetHeight;
+                    target.style.removeProperty("animation");
+                }
+            }
+        })
+    });
     // Make sure current element is visible in breadcrumb navigation on small displays
     const subnav = document.querySelector("ol.sub-nav-list");
     if (subnav && subnav.lastElementChild) {
@@ -286,7 +300,7 @@ document.addEventListener("DOMContentLoaded", function(e) {
     });
     var expanded = false;
     var windowWidth;
-    function collapse() {
+    function collapse(e) {
         if (expanded) {
             mainnav.removeAttribute("style");
             if (toc) {
@@ -336,7 +350,7 @@ document.addEventListener("DOMContentLoaded", function(e) {
     document.querySelectorAll("h1, h2, h3, h4, h5, h6")
         .forEach((hdr, idx) => {
             // Create anchor links for headers with an associated id attribute
-            var id = hdr.getAttribute("id") || hdr.parentElement.getAttribute("id")
+            var id = hdr.parentElement.getAttribute("id") || hdr.getAttribute("id")
                 || (hdr.querySelector("a") && hdr.querySelector("a").getAttribute("id"));
             if (id) {
                 var template = document.createElement('template');

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/stylesheet.css

@@ -63,7 +63,7 @@
     --search-input-text-color: #000000;
     --search-input-placeholder-color: #909090;
     /* Highlight color for active search tag target */
-    --search-tag-highlight-color: #ffff00;
+    --search-tag-highlight-color: #ffff66;
     /* Adjustments for icon and active background colors of copy-to-clipboard buttons */
     --copy-icon-brightness: 100%;
     --copy-button-background-color-active: rgba(168, 168, 176, 0.3);
@@ -307,7 +307,7 @@ ol.sub-nav-list a.current-selection {
  */
 .title {
     color:var(--title-color);
-    margin:10px 0;
+    margin:10px 0 12px 0;
 }
 .sub-title {
     margin:5px 0 0 0;
@@ -988,6 +988,22 @@ input::placeholder {
 .search-tag-result:target {
     background-color:var(--search-tag-highlight-color);
 }
+dd > span:target,
+h1 > span:target {
+    animation: 2.4s ease-out highlight;
+}
+section.class-description dd > span:target,
+section.class-description h1 > span:target {
+    scroll-margin-top: 20em;
+}
+@keyframes highlight {
+    from {
+        background-color: var(--search-tag-highlight-color);
+    }
+    60% {
+        background-color: var(--search-tag-highlight-color);
+    }
+}
 details.page-search-details {
     display: inline-block;
 }
@@ -1040,7 +1056,7 @@ span#page-search-link {
     z-index: 5;
 }
 .inherited-list {
-    margin: 10px 0 10px 0;
+    margin: 10px 0;
 }
 .horizontal-scroll {
     overflow: auto hidden;

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/LinkTaglet.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -176,7 +176,7 @@ Content linkSeeReferenceOutput(Element holder,
                 return htmlWriter.getPackageLink(refPackage, labelContent, refFragment);
             } else {
                 // @see is not referencing an included class, module or package. Check for cross-links.
-                String refModuleName =  ch.getReferencedModuleName(refSignature);
+                String refModuleName = ch.getReferencedModuleName(refSignature);
                 DocLink elementCrossLink = (refPackage != null) ? htmlWriter.getCrossPackageLink(refPackage) :
                         (config.extern.isModule(refModuleName))
                                 ? htmlWriter.getCrossModuleLink(utils.elementUtils.getModuleElement(refModuleName))
@@ -190,12 +190,28 @@ Content linkSeeReferenceOutput(Element holder,
                     if (!config.isDocLintReferenceGroupEnabled()) {
                         reportWarning.accept(
                                 "doclet.link.see.reference_not_found",
-                                new Object[] { refSignature});
+                                new Object[] {refSignature});
                     }
                     return htmlWriter.invalidTagOutput(resources.getText("doclet.link.see.reference_invalid"),
-                            Optional.of(labelContent.isEmpty() ? text: labelContent));
+                            Optional.of(labelContent.isEmpty() ? text : labelContent));
                 }
             }
+        } else if (utils.isTypeParameterElement(ref)) {
+            // This is a type parameter of a generic class, method or constructor
+            if (labelContent.isEmpty()) {
+                labelContent = plainOrCode(isPlain, Text.of(utils.getSimpleName(ref)));
+            }
+            if (refMem == null) {
+                return htmlWriter.getLink(
+                        new HtmlLinkInfo(config, HtmlLinkInfo.Kind.LINK_TYPE_PARAMS, ref.asType())
+                                .label(labelContent));
+            } else {
+                // HtmlLinkFactory does not render type parameters of generic methods as links, so instead of
+                // teaching it how to do it (making the code even more complex) just create the link directly.
+                return htmlWriter.getLink(new HtmlLinkInfo(config, HtmlLinkInfo.Kind.PLAIN, refClass)
+                        .fragment(config.htmlIds.forTypeParam(ref.getSimpleName().toString(), refMem).name())
+                        .label((labelContent)));
+            }
         } else if (refFragment == null) {
             // Must be a class reference since refClass is not null and refFragment is null.
             if (labelContent.isEmpty() && refTree != null) {

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/ParamTaglet.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -278,7 +278,9 @@ private Content paramTagOutput(Element element, ParamTree paramTag, String param
         body.add(" - ");
         List<? extends DocTree> description = ch.getDescription(paramTag);
         body.add(htmlWriter.commentTagsToContent(element, description, context.within(paramTag)));
-        return HtmlTree.DD(body);
+        return HtmlTree.DD(paramTag.isTypeParameter()
+                ? HtmlTree.SPAN_ID(config.htmlIds.forTypeParam(paramName, element), body)
+                : body);
     }
 
     private record Documentation(ParamTree paramTree, ExecutableElement method) { }

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/CommentHelper.java

@@ -188,6 +188,12 @@ public Element getReferencedMember(Element e) {
         Utils utils = configuration.utils;
         if (e == null) {
             return null;
+        } else if (utils.isTypeParameterElement(e)) {
+            // Return the enclosing member for type parameters of generic methods or constructors.
+            Element encl = e.getEnclosingElement();
+            if (utils.isExecutableElement(encl)) {
+                return encl;
+            }
         }
         return (utils.isExecutableElement(e) || utils.isVariableElement(e)) ? e : null;
     }

test/langtools/jdk/javadoc/doclet/testDeprecatedDocs/TestDeprecatedDocs.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -102,7 +102,6 @@ public void test() {
 
         checkOutput("pkg/TestAnnotationType.html", true,
                 """
-                    <hr>
                     <div class="type-signature"><span class="annotations">@Deprecated(forRemoval=true)
                     @Documented
                     </span><span class="modifiers">public @interface </span><span class="element-name type-n\
@@ -135,7 +134,6 @@ public void test() {
 
         checkOutput("pkg/TestClass.html", true,
                 """
-                    <hr>
                     <div class="type-signature"><span class="annotations">@Deprecated(forRemoval=true)
                     </span><span class="modifiers">public class </span><span class="element-name type-name-label">TestClass</span>
                     <span class="extends-implements">extends java.lang.Object</span></div>
@@ -212,7 +210,6 @@ public void test() {
 
         checkOutput("pkg/TestEnum.html", true,
                 """
-                    <hr>
                     <div class="type-signature"><span class="annotations">@Deprecated(forRemoval=true)
                     </span><span class="modifiers">public enum </span><span class="element-name type-name-label">TestEnum</span>
                     <span class="extends-implements">extends java.lang.Enum&lt;<a href="TestEnum.htm\
@@ -233,7 +230,6 @@ public void test() {
 
         checkOutput("pkg/TestError.html", true,
                 """
-                    <hr>
                     <div class="type-signature"><span class="annotations">@Deprecated(forRemoval=true)
                     </span><span class="modifiers">public class </span><span class="element-name type-name-label">TestError</span>
                     <span class="extends-implements">extends java.lang.Error</span></div>
@@ -244,7 +240,6 @@ public void test() {
 
         checkOutput("pkg/TestException.html", true,
                 """
-                    <hr>
                     <div class="type-signature"><span class="annotations">@Deprecated(forRemoval=true)
                     </span><span class="modifiers">public class </span><span class="element-name type-name-label">TestException</span>
                     <span class="extends-implements">extends java.lang.Exception</span></div>
@@ -255,7 +250,6 @@ public void test() {
 
         checkOutput("pkg/TestInterface.html", true,
                 """
-                    <hr>
                     <div class="type-signature"><span class="annotations">@Deprecated(forRemoval=true)
                     </span><span class="modifiers">public class </span><span class="element-name type-name-label">TestInterface</span>
                     <span class="extends-implements">extends java.lang.Object</span></div>

test/langtools/jdk/javadoc/doclet/testDirectedInheritance/TestDirectedInheritance.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -154,8 +154,8 @@ public interface E1 extends I1, I2 {
                 <div class="block">I2: main description</div>
                 """, """
                 <dt>Type Parameters:</dt>
-                <dd><code>E</code> - I2: first type parameter</dd>
-                <dd><code>F</code> - I2: second type parameter</dd>
+                <dd><span id="m(E)-type-param-E"><code>E</code> - I2: first type parameter</span></dd>
+                <dd><span id="m(E)-type-param-F"><code>F</code> - I2: second type parameter</span></dd>
                 <dt>Parameters:</dt>
                 <dd><code>eObj</code> - I2: parameter</dd>
                 <dt>Returns:</dt>

test/langtools/jdk/javadoc/doclet/testErasure/TestErasure.java

@@ -199,7 +199,7 @@ class X { }
                 <div class="col-first even-row-color"><code>&nbsp;</code></div>
                 <div class="col-constructor-name even-row-color"><code>\
                 <a href="#%3Cinit%3E(T)" class="member-name-link">Foo</a>\
-                <wbr>(<a href="Foo.html" title="type parameter in Foo">T</a>&nbsp;arg)</code></div>
+                <wbr>(<a href="#type-param-T" title="type parameter in Foo">T</a>&nbsp;arg)</code></div>
                 <div class="col-last even-row-color">&nbsp;</div>
                 <div class="col-first odd-row-color"><code>&nbsp;&lt;T extends X&gt;<br></code></div>
                 <div class="col-constructor-name odd-row-color"><code>\
@@ -227,10 +227,10 @@ class X { }
         // methods
         checkOutput("Foo.html", true, """
                 <div class="col-first even-row-color method-summary-table method-summary-table-tab2 \
-                method-summary-table-tab3"><code>abstract <a href="Foo.html" title="type parameter in Foo">T</a></code></div>
+                method-summary-table-tab3"><code>abstract <a href="#type-param-T" title="type parameter in Foo">T</a></code></div>
                 <div class="col-second even-row-color method-summary-table method-summary-table-tab2 \
                 method-summary-table-tab3"><code><a href="#m(T)" class="member-name-link">m</a>\
-                <wbr>(<a href="Foo.html" title="type parameter in Foo">T</a>&nbsp;arg)</code></div>
+                <wbr>(<a href="#type-param-T" title="type parameter in Foo">T</a>&nbsp;arg)</code></div>
                 <div class="col-last even-row-color method-summary-table method-summary-table-tab2 \
                 method-summary-table-tab3">&nbsp;</div>
                 <div class="col-first odd-row-color method-summary-table method-summary-table-tab2 \
@@ -385,4 +385,4 @@ class Y { }
                 <div class="col-second odd-row-color constructor constructor-tab1">Test Feature</div>
                 <div class="col-last odd-row-color constructor constructor-tab1"></div>""");
     }
-}
+}

test/langtools/jdk/javadoc/doclet/testGenericMethodLinkTaglet/TestGenericMethodLinkTaglet.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -23,7 +23,7 @@
 
 /*
  * @test
- * @bug      8188248
+ * @bug      8188248 8313931
  * @summary  NullPointerException on generic methods
  * @library  /tools/lib ../../lib
  * @modules jdk.javadoc/jdk.javadoc.internal.tool
@@ -67,7 +67,7 @@ public void test(Path base) throws Exception {
 
         checkOutput("pkg/A.html", true,
                 """
-                    <a href="A.html" title="class in pkg"><code>A</code></a>""");
+                    param <a href="#m1(T)-type-param-T"><code>T</code></a>""");
     }
 
     void createTestClass(Path srcDir) throws Exception {

test/langtools/jdk/javadoc/doclet/testHref/TestHref.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -75,7 +75,8 @@ public void test() {
 
         checkOutput("pkg/C4.html", true,
                 //Header does not link to the page itself.
-                "Class C4&lt;E extends C4&lt;E&gt;&gt;</h1>",
+                """
+                    Class C4&lt;<span id="type-param-E">E extends C4&lt;E&gt;</span>&gt;</h1>""",
                 //Signature does not link to the page itself.
                 """
                     <span class="modifiers">public abstract class </span><span class="element-name type-name\

test/langtools/jdk/javadoc/doclet/testInterface/TestInterface.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -99,12 +99,12 @@ public void test() {
                     <dt>Specified by:</dt>
                     <dd><code><a href="Interface.html#method()">method</a></code>&nbsp;in interface&\
                     nbsp;<code><a href="Interface.html" title="interface in pkg">Interface</a>&lt;<a\
-                     href="Child.html" title="type parameter in Child">CE</a>&gt;</code></dd>""",
+                     href="#type-param-CE" title="type parameter in Child">CE</a>&gt;</code></dd>""",
                 //Make sure "Overrides" has substituted type parameters.
                 """
                     <dt>Overrides:</dt>
                     <dd><code><a href="Parent.html#method()">method</a></code>&nbsp;in class&nbsp;<c\
-                    ode><a href="Parent.html" title="class in pkg">Parent</a>&lt;<a href="Child.html\
+                    ode><a href="Parent.html" title="class in pkg">Parent</a>&lt;<a href="#type-param-CE\
                     " title="type parameter in Child">CE</a>&gt;</code></dd>""");
 
         checkOutput("pkg/Parent.html", true,
@@ -190,7 +190,7 @@ public void test1() {
                 <dt>Overrides:</dt>
                 <dd><code><a href="GrandParent.html#method1()">method1</a></code>&nbsp;in class&\
                 nbsp;<code><a href="GrandParent.html" title="class in pkg1">GrandParent</a>&lt;<\
-                a href="Child.html" title="type parameter in Child">CE</a>&gt;</code>""");
+                a href="#type-param-CE" title="type parameter in Child">CE</a>&gt;</code>""");
     }
 
     @Test
@@ -209,17 +209,17 @@ public void test2() {
                 erface in pkg2">Spliterator</a></h3>
                 <code><a href="Spliterator.OfDouble.html" title="interface in pkg2">Spliterator.\
                 OfDouble</a>, <a href="Spliterator.OfInt.html" title="interface in pkg2">Spliter\
-                ator.OfInt</a>&lt;<a href="Spliterator.OfInt.html" title="type parameter in Spli\
+                ator.OfInt</a>&lt;<a href="Spliterator.OfInt.html#type-param-Integer" title="type parameter in Spli\
                 terator.OfInt">Integer</a>&gt;, <a href="Spliterator.OfPrimitive.html" title="in\
                 terface in pkg2">Spliterator.OfPrimitive</a>&lt;<a href="Spliterator.OfPrimitive\
-                .html" title="type parameter in Spliterator.OfPrimitive">T</a>,<wbr><a href="Spl\
-                iterator.OfPrimitive.html" title="type parameter in Spliterator.OfPrimitive">T_C\
-                ONS</a>,<wbr><a href="Spliterator.OfPrimitive.html" title="type parameter in Spl\
+                .html#type-param-T" title="type parameter in Spliterator.OfPrimitive">T</a>,<wbr><a href="Spl\
+                iterator.OfPrimitive.html#type-param-T_CONS" title="type parameter in Spliterator.OfPrimitive">T_C\
+                ONS</a>,<wbr><a href="Spliterator.OfPrimitive.html#type-param-T_SPLITR" title="type parameter in Spl\
                 iterator.OfPrimitive">T_SPLITR</a> extends <a href="Spliterator.OfPrimitive.html\
                 " title="interface in pkg2">Spliterator.OfPrimitive</a>&lt;<a href="Spliterator.\
-                OfPrimitive.html" title="type parameter in Spliterator.OfPrimitive">T</a>,<wbr><\
-                a href="Spliterator.OfPrimitive.html" title="type parameter in Spliterator.OfPri\
-                mitive">T_CONS</a>,<wbr><a href="Spliterator.OfPrimitive.html" title="type param\
+                OfPrimitive.html#type-param-T" title="type parameter in Spliterator.OfPrimitive">T</a>,<wbr><\
+                a href="Spliterator.OfPrimitive.html#type-param-T_CONS" title="type parameter in Spliterator.OfPri\
+                mitive">T_CONS</a>,<wbr><a href="Spliterator.OfPrimitive.html#type-param-T_SPLITR" title="type param\
                 eter in Spliterator.OfPrimitive">T_SPLITR</a>&gt;&gt;</code>""");
         checkOutput("pkg2/Spliterator.html", true,
             """
@@ -236,21 +236,21 @@ public void test2() {
                 <div class="col-first odd-row-color"><code>static interface&nbsp;</code></div>
                 <div class="col-second odd-row-color"><code><a href="Spliterator.OfInt.html" cla\
                 ss="type-name-link" title="interface in pkg2">Spliterator.OfInt</a>&lt;<a href="\
-                Spliterator.OfInt.html" title="type parameter in Spliterator.OfInt">Integer</a>&\
+                Spliterator.OfInt.html#type-param-Integer" title="type parameter in Spliterator.OfInt">Integer</a>&\
                 gt;</code></div>
                 <div class="col-last odd-row-color">&nbsp;</div>
                 <div class="col-first even-row-color"><code>static interface&nbsp;</code></div>
                 <div class="col-second even-row-color"><code><a href="Spliterator.OfPrimitive.ht\
                 ml" class="type-name-link" title="interface in pkg2">Spliterator.OfPrimitive</a>\
-                &lt;<a href="Spliterator.OfPrimitive.html" title="type parameter in Spliterator.\
-                OfPrimitive">T</a>,<wbr><a href="Spliterator.OfPrimitive.html" title="type param\
+                &lt;<a href="Spliterator.OfPrimitive.html#type-param-T" title="type parameter in Spliterator.\
+                OfPrimitive">T</a>,<wbr><a href="Spliterator.OfPrimitive.html#type-param-T_CONS" title="type param\
                 eter in Spliterator.OfPrimitive">T_CONS</a>,<wbr><a href="Spliterator.OfPrimitiv\
-                e.html" title="type parameter in Spliterator.OfPrimitive">T_SPLITR</a> extends <\
+                e.html#type-param-T_SPLITR" title="type parameter in Spliterator.OfPrimitive">T_SPLITR</a> extends <\
                 a href="Spliterator.OfPrimitive.html" title="interface in pkg2">Spliterator.OfPr\
-                imitive</a>&lt;<a href="Spliterator.OfPrimitive.html" title="type parameter in S\
-                pliterator.OfPrimitive">T</a>,<wbr><a href="Spliterator.OfPrimitive.html" title=\
+                imitive</a>&lt;<a href="Spliterator.OfPrimitive.html#type-param-T" title="type parameter in S\
+                pliterator.OfPrimitive">T</a>,<wbr><a href="Spliterator.OfPrimitive.html#type-param-T_CONS" title=\
                 "type parameter in Spliterator.OfPrimitive">T_CONS</a>,<wbr><a href="Spliterator\
-                .OfPrimitive.html" title="type parameter in Spliterator.OfPrimitive">T_SPLITR</a\
+                .OfPrimitive.html#type-param-T_SPLITR" title="type parameter in Spliterator.OfPrimitive">T_SPLITR</a\
                 >&gt;&gt;</code></div>
                 <div class="col-last even-row-color">&nbsp;</div>
                 </div>""");

test/langtools/jdk/javadoc/doclet/testLinkTaglet/TestLinkTagletTypeParam.java

@@ -0,0 +1,124 @@
+/*
+ * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * @test
+ * @bug      8313931
+ * @summary  Javadoc: links to type parameters actually generate links to classes
+ * @library  /tools/lib ../../lib
+ * @modules  jdk.javadoc/jdk.javadoc.internal.tool
+ * @build    toolbox.ToolBox javadoc.tester.*
+ * @run main TestLinkTagletTypeParam
+ */
+
+import javadoc.tester.JavadocTester;
+import toolbox.ToolBox;
+
+import java.io.IOException;
+import java.nio.file.Path;
+
+public class TestLinkTagletTypeParam extends JavadocTester {
+
+    public static void main(String... args) throws Exception {
+        var tester = new TestLinkTagletTypeParam();
+        tester.runTests();
+    }
+
+    ToolBox tb = new ToolBox();
+
+    @JavadocTester.Test
+    public void testClassTypeParameterLink(Path base) throws IOException {
+        Path src = base.resolve("src");
+
+        tb.writeJavaFiles(src,
+                """
+                    /**
+                     * Link to {@link F}.
+                     *
+                     * @param <F> the first type param
+                     * @param <APND> an Appendable
+                     *
+                     * @see APND the second type parameter
+                     */
+                    public class Test<F, APND extends Appendable> {
+                        private Test() {}
+                    }
+                    """);
+
+        javadoc("-Xdoclint:none",
+                "-d", base.resolve("api").toString(),
+                "-sourcepath", src.toString(),
+                src.resolve("Test.java").toString());
+        checkExit(JavadocTester.Exit.OK);
+
+        checkOrder("Test.html",
+                """
+                    <dt>Type Parameters:</dt>
+                    <dd><span id="type-param-F"><code>F</code> - the first type param</span></dd>
+                    <dd><span id="type-param-APND"><code>APND</code> - an Appendable</span></dd>""",
+                """
+                    Link to <a href="#type-param-F" title="type parameter in Test"><code>F</code></a>.""",
+                """
+                    <dt>See Also:</dt>
+                    <dd>
+                    <ul class="tag-list">
+                    <li><a href="#type-param-APND" title="type parameter in Test">the second type parameter</a></li>
+                    </ul>""");
+    }
+
+    @JavadocTester.Test
+    public void testMethodTypeParameterLink(Path base) throws IOException {
+        Path src = base.resolve("src");
+
+        tb.writeJavaFiles(src,
+               """
+                    /**
+                     * Class comment.
+                     */
+                    public class Test {
+                        /**
+                         * Link to {@link T} and {@linkplain T link with label}.
+                         *
+                         * @param <T> the T
+                         * @param appendable the appendable
+                         */
+                        public <T extends Appendable> T append(final T appendable) {
+                            return appendable;
+                        }
+                    }
+                    """);
+
+        javadoc("-Xdoclint:reference",
+                "-d", base.resolve("api").toString(),
+                "-sourcepath", src.toString(),
+                src.resolve("Test.java").toString());
+
+        checkOutput(JavadocTester.Output.OUT, true,
+                "");
+
+        checkOutput("Test.html", true,
+                """
+                    Link to <a href="#append(T)-type-param-T"><code>T</code></a> and <a href="#appe\
+                    nd(T)-type-param-T">link with label</a>.""");
+    }
+}

test/langtools/jdk/javadoc/doclet/testMemberInheritance/TestMemberInheritance.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2002, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -120,8 +120,8 @@ interface in pkg">BaseInterface</a></code></dd>
         checkOutput("pkg2/DocumentedNonGenericChild.html", true,
                 """
                     <section class="class-description" id="class-description">
-                    <div class="horizontal-scroll">
                     <hr>
+                    <div class="horizontal-scroll">
                     <div class="type-signature"><span class="modifiers">public abstract class </span\
                     ><span class="element-name type-name-label">DocumentedNonGenericChild</span>
                     <span class="extends-implements">extends java.lang.Object</span></div>

test/langtools/jdk/javadoc/doclet/testModules/TestModules.java

@@ -1360,8 +1360,8 @@ void checkLinkSource(boolean includePrivate) {
         checkOutput("moduleA/testpkgmdlA/TestClassInModuleA.html", true,
                 """
                     <section class="class-description" id="class-description">
-                    <div class="horizontal-scroll">
                     <hr>
+                    <div class="horizontal-scroll">
                     <div class="type-signature"><span class="modifiers">public class </span><span cl\
                     ass="element-name"><a href="../../src-html/moduleA/testpkgmdlA/TestClassInModule\
                     A.html#line-25">TestClassInModuleA</a></span>

test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -117,7 +117,7 @@ void checkTypeParameters() {
                 // Check class type parameters section.
                 """
                     <dt>Type Parameters:</dt>
-                    <dd><code>E</code> - the type parameter for this class.""",
+                    <dd><span id="type-param-E"><code>E</code> - the type parameter for this class.</span></dd>""",
                 // Type parameters in @see/@link
                 """
                     <dl class="notes">
@@ -130,12 +130,14 @@ void checkTypeParameters() {
                     </dl>""",
                 // Method that uses class type parameter.
                 """
-                    (<a href="TypeParameters.html" title="type parameter in TypeParameters">E</a>&nbsp;param)""",
+                    (<a href="#type-param-E" title="type parameter in TypeParameters">E</a>&nbsp;param)""",
                 // Method type parameter section.
                 """
                     <dt>Type Parameters:</dt>
-                    <dd><code>T</code> - This is the first type parameter.</dd>
-                    <dd><code>V</code> - This is the second type parameter.""",
+                    <dd><span id="methodThatHasTypeParameters(T,V)-type-param-T"><code>T</code> - Th\
+                    is is the first type parameter.</span></dd>
+                    <dd><span id="methodThatHasTypeParameters(T,V)-type-param-V"><code>V</code> - Th\
+                    is is the second type parameter.</span></dd>""",
                 // Signature of method with type parameters
                 """
                     <div class="member-signature"><span class="modifiers">public</span>&nbsp;<span c\
@@ -147,18 +149,18 @@ void checkTypeParameters() {
                 // Method that returns TypeParameters
                 """
                     <div class="col-first even-row-color method-summary-table method-summary-table-t\
-                    ab2 method-summary-table-tab4"><code><a href="TypeParameters.html" title="type p\
+                    ab2 method-summary-table-tab4"><code><a href="#type-param-E" title="type p\
                     arameter in TypeParameters">E</a>[]</code></div>
                     <div class="col-second even-row-color method-summary-table method-summary-table-\
                     tab2 method-summary-table-tab4"><code><a href="#methodThatReturnsTypeParameterA(\
                     E%5B%5D)" class="member-name-link">methodThatReturnsTypeParameterA</a><wbr>(<a h\
-                    ref="TypeParameters.html" title="type parameter in TypeParameters">E</a>[]&nbsp;\
+                    ref="#type-param-E" title="type parameter in TypeParameters">E</a>[]&nbsp;\
                     e)</code>""",
                 """
                     <div class="member-signature"><span class="modifiers">public</span>&nbsp;<span c\
-                    lass="return-type"><a href="TypeParameters.html" title="type parameter in TypePa\
+                    lass="return-type"><a href="#type-param-E" title="type parameter in TypePa\
                     rameters">E</a>[]</span>&nbsp;<span class="element-name">methodThatReturnsTypePa\
-                    rameterA</span><wbr><span class="parameters">(<a href="TypeParameters.html" titl\
+                    rameterA</span><wbr><span class="parameters">(<a href="#type-param-E" titl\
                     e="type parameter in TypeParameters">E</a>[]&nbsp;e)</span></div>
                     """,
                 """
@@ -176,7 +178,7 @@ void checkTypeParameters() {
                 """
                     <div class="col-first odd-row-color method-summary-table method-summary-table-ta\
                     b2 method-summary-table-tab4"><code>&lt;X extends java.lang.Throwable&gt;<br><a \
-                    href="TypeParameters.html" title="type parameter in TypeParameters">E</a></code>\
+                    href="#type-param-E" title="type parameter in TypeParameters">E</a></code>\
                     </div>
                     <div class="col-second odd-row-color method-summary-table method-summary-t\
                     able-tab2 method-summary-table-tab4"><code><a href="#orElseThrow(java.util.funct\

test/langtools/jdk/javadoc/doclet/testParamTaglet/TestParamTaglet.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -79,7 +79,7 @@ public void test() {
                     </dl>""",
                 """
                     <dt>Type Parameters:</dt>
-                    <dd><code>T2</code> - type 2</dd>
+                    <dd><span id="genericMethod(T1,T2,T3)-type-param-T2"><code>T2</code> - type 2</span></dd>
                     <dt>Parameters:</dt>
                     <dd><code>t1</code> - param 1</dd>
                     <dd><code>t3</code> - param 3</dd>
@@ -92,7 +92,7 @@ public void test() {
         checkOutput("pkg/C.Nested.html", true,
                 """
                     <dt>Type Parameters:</dt>
-                    <dd><code>T1</code> - type 1</dd>
+                    <dd><span id="type-param-T1"><code>T1</code> - type 1</span></dd>
                     </dl>""");
     }
 }

test/langtools/jdk/javadoc/doclet/testProperty/TestProperty.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -110,7 +110,7 @@ class in pkg">ObjectProperty</a><wbr>&lt;<a href="MyObj.html" title="class in pk
                 """
                     <div class="member-signature"><span class="modifiers">public final</span>&nbsp;<\
                     span class="return-type"><a href="ObjectProperty.html" title="class in pkg">Obje\
-                    ctProperty</a>&lt;java.util.List&lt;<a href="MyClassT.html" title="type paramete\
+                    ctProperty</a>&lt;java.util.List&lt;<a href="#type-param-T" title="type paramete\
                     r in MyClassT">T</a>&gt;&gt;</span>&nbsp;<span class="element-name">listProperty</span><\
                     /div>
                     <div class="block">This is an Object property where the Object is a single <code>List&lt;T&gt;</code>.</div>

test/langtools/jdk/javadoc/doclet/testRecordTypes/TestRecordTypes.java

@@ -175,7 +175,7 @@ public record R<T>(int r1) { }""");
                 """
                     <dl class="notes">
                     <dt>Type Parameters:</dt>
-                    <dd><code>T</code> - This is a type parameter.</dd>
+                    <dd><span id="type-param-T"><code>T</code> - This is a type parameter.</span></dd>
                     <dt>Record Components:</dt>
                     <dd><code><span id="param-r1">r1</span></code> - This is a component.</dd>
                     </dl>""",

test/langtools/jdk/javadoc/doclet/testSerializedForm/TestSerializedForm.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -219,6 +219,7 @@ public void test2() {
                 """
                     <a href="pkg2/Fields.html" title="class in pkg2">Fields</a>[] singleArray""",
                 """
-                    java.lang.Class&lt;<a href="pkg2/Fields.html" title="type parameter in Fields">E</a>&gt; someClass""");
+                    java.lang.Class&lt;<a href="pkg2/Fields.html#type-param-E" title="type paramete\
+                    r in Fields">E</a>&gt; someClass""");
     }
 }

test/langtools/jdk/javadoc/doclet/testThrows/TestThrows.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2002, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -83,7 +83,7 @@ public interface C {
                  """
                      <dl class="notes">
                      <dt>Type Parameters:</dt>
-                     <dd><code>T</code> - the throwable</dd>
+                     <dd><span id="m()-type-param-T"><code>T</code> - the throwable</span></dd>
                      <dt>Throws:</dt>
                      <dd><code>T</code> - if a specific error occurs</dd>
                      <dd><code>java.lang.Exception</code> - if an exception occurs</dd>

test/langtools/jdk/javadoc/doclet/testTypeParams/TestTypeParameters.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -23,7 +23,7 @@
 
 /*
  * @test
- * @bug      4927167 4974929 6381729 7010344 8025633 8081854 8182765 8187288 8261976
+ * @bug      4927167 4974929 6381729 7010344 8025633 8081854 8182765 8187288 8261976 8313931
  * @summary  When the type parameters are more than 10 characters in length,
  *           make sure there is a line break between type params and return type
  *           in member summary. Also, test for type parameter links in package-summary and
@@ -110,10 +110,22 @@ public void test3() {
                     <div class="col-first even-row-color"><code>&nbsp;&lt;T extends java.lang.Runnable&gt;<br></code></div>
                     <div class="col-constructor-name even-row-color"><code>\
                     <a href="#%3Cinit%3E()" class="member-name-link">CtorTypeParam</a>()</code></div>
-                    <div class="col-last even-row-color">&nbsp;</div>""",
+                    <div class="col-last even-row-color">
+                    <div class="block">Generic constructor.</div>""",
                 """
                     <div class="member-signature"><span class="modifiers">public</span>\
                     &nbsp;<span class="type-parameters">&lt;T extends java.lang.Runnable&gt;</span>\
-                    &nbsp;<span class="element-name">CtorTypeParam</span>()</div>""");
+                    &nbsp;<span class="element-name">CtorTypeParam</span>()</div>""",
+                """
+                    <a href="#%3Cinit%3E()-type-param-T"><code>T</code></a>""",
+                """
+                    <dt>Type Parameters:</dt>
+                    <dd><span id="&lt;init&gt;()-type-param-T"><code>T</code> - the type parameter</span></dd>""",
+                """
+                    <dt>See Also:</dt>
+                    <dd>
+                    <ul class="tag-list">
+                    <li><a href="#%3Cinit%3E()-type-param-T">link to type parameter</a></li>
+                    </ul>""");
     }
 }

test/langtools/jdk/javadoc/doclet/testTypeParams/pkg/CtorTypeParam.java

@@ -24,6 +24,12 @@
 package pkg;
 
 public class CtorTypeParam {
+    /**
+     * Generic constructor. {@link T}
+     *
+     * @param <T> the type parameter
+     * @see T link to type parameter
+     */
     public <T extends Runnable> CtorTypeParam() {
     }
 }

test/langtools/jdk/javadoc/doclet/testUnicode/TestUnicode.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -101,7 +101,7 @@ public class Code<##> {
                 """
                     <dl class="notes">
                     <dt>Type Parameters:</dt>
-                    <dd><code>##</code> - the ##</dd>
+                    <dd><span id="type-param-##"><code>##</code> - the ##</span></dd>
                     </dl>
                     """.replaceAll("##", chineseElephant),
                 """