8289332: Auto-generate ids for user-defined headings

Reviewed-by: jjg

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

@@ -27,7 +27,6 @@
 
 import java.time.ZonedDateTime;
 import java.util.ArrayList;
-import java.util.Date;
 import java.util.EnumSet;
 import java.util.HashMap;
 import java.util.List;
@@ -44,7 +43,6 @@
 import javax.tools.JavaFileObject;
 import javax.tools.StandardJavaFileManager;
 
-import com.sun.source.util.DocTreePath;
 import jdk.javadoc.doclet.Doclet;
 import jdk.javadoc.doclet.DocletEnvironment;
 import jdk.javadoc.doclet.Reporter;

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

@@ -172,6 +172,8 @@ public class HtmlDocletWriter {
 
     protected final HtmlIds htmlIds;
 
+    private final Set<String> headingIds = new HashSet<>();
+
     /**
      * To check whether the repeated annotations is documented or not.
      */
@@ -1203,10 +1205,6 @@ private boolean inAnAtag() {
                     return (tag instanceof StartElementTree st) && equalsIgnoreCase(st.getName(), "a");
                 }
 
-                private boolean equalsIgnoreCase(Name name, String s) {
-                    return name != null && name.toString().equalsIgnoreCase(s);
-                }
-
                 @Override
                 public Boolean visitAttribute(AttributeTree node, Content content) {
                     if (!content.isEmpty()) {
@@ -1367,6 +1365,9 @@ public Boolean visitLiteral(LiteralTree node, Content content) {
                 @Override
                 public Boolean visitStartElement(StartElementTree node, Content content) {
                     Content attrs = new ContentBuilder();
+                    if (node.getName().toString().matches("(?i)h[1-6]") && !hasIdAttribute(node)) {
+                        generateHeadingId(node, trees, attrs);
+                    }
                     for (DocTree dt : node.getAttributes()) {
                         dt.accept(this, attrs);
                     }
@@ -1436,6 +1437,39 @@ protected Boolean defaultAction(DocTree node, Content content) {
         return result;
     }
 
+    private boolean equalsIgnoreCase(Name name, String s) {
+        return name != null && name.toString().equalsIgnoreCase(s);
+    }
+
+    private boolean hasIdAttribute(StartElementTree node) {
+        return node.getAttributes().stream().anyMatch(
+                dt -> dt instanceof AttributeTree at && equalsIgnoreCase(at.getName(), "id"));
+    }
+
+    private void generateHeadingId(StartElementTree node, List<? extends DocTree> trees, Content content) {
+        StringBuilder sb = new StringBuilder();
+        String tagName = node.getName().toString().toLowerCase(Locale.ROOT);
+        for (DocTree docTree : trees.subList(trees.indexOf(node) + 1, trees.size())) {
+            if (docTree instanceof TextTree text) {
+                sb.append(text.getBody());
+            } else if (docTree instanceof LiteralTree literal) {
+                sb.append(literal.getBody().getBody());
+            } else if (docTree instanceof LinkTree link) {
+                var label = link.getLabel();
+                sb.append(label.isEmpty() ? link.getReference().getSignature() : label.toString());
+            } else if (docTree instanceof EndElementTree endElement
+                    && equalsIgnoreCase(endElement.getName(), tagName)) {
+                break;
+            } else if (docTree instanceof StartElementTree nested
+                    && equalsIgnoreCase(nested.getName(), "a")
+                    && hasIdAttribute(nested)) {
+                return; // Avoid generating id if embedded <a id=...> is present
+            }
+        }
+        HtmlId htmlId = htmlIds.forHeading(sb, headingIds);
+        content.add("id=\"").add(htmlId.name()).add("\"");
+    }
+
     /**
      * Returns true if relative links should be redirected.
      *

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

@@ -28,6 +28,7 @@
 import java.util.List;
 import java.util.Locale;
 import java.util.Map;
+import java.util.Set;
 import javax.lang.model.element.Element;
 import javax.lang.model.element.ExecutableElement;
 import javax.lang.model.element.PackageElement;
@@ -511,4 +512,29 @@ public HtmlId forPreviewSection(Element el) {
     public HtmlId forPage(Navigation.PageMode page) {
         return HtmlId.of(page.name().toLowerCase(Locale.ROOT).replace("_", "-"));
     }
+
+    /**
+     * Returns an id for a heading in a doc comment. The id value is derived from the contents
+     * of the heading with additional checks to make it unique within its containing page.
+     *
+     * @param headingText the text contained by the heading
+     * @param headingIds the set of heading ids already generated for the current page
+     * @return a unique id value for the heading
+     */
+    public HtmlId forHeading(CharSequence headingText, Set<String> headingIds) {
+        String idValue = headingText.toString()
+                .toLowerCase(Locale.ROOT)
+                .trim()
+                .replaceAll("[^\\w_-]+", "-");
+        // Make id value unique
+        idValue = idValue + "-heading";
+        if (!headingIds.add(idValue)) {
+            int counter = 1;
+            while (!headingIds.add(idValue + counter)) {
+                counter++;
+            }
+            idValue = idValue + counter;
+        }
+        return HtmlId.of(idValue);
+    }
 }

test/langtools/jdk/javadoc/doclet/testAutoHeaderId/TestAutoHeaderId.java

@@ -0,0 +1,126 @@
+/*
+ * Copyright (c) 2022, 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 8289332
+ * @summary Auto-generate ids for user-defined headings
+ * @library /tools/lib ../../lib
+ * @modules jdk.javadoc/jdk.javadoc.internal.tool
+ * @build javadoc.tester.* toolbox.ToolBox
+ * @run main TestAutoHeaderId
+ */
+
+import java.nio.file.Path;
+
+import toolbox.ToolBox;
+
+import javadoc.tester.JavadocTester;
+
+public class TestAutoHeaderId extends JavadocTester {
+
+    public static void main(String... args) throws Exception {
+        TestAutoHeaderId tester = new TestAutoHeaderId();
+        tester.runTests();
+    }
+
+    private final ToolBox tb;
+
+    TestAutoHeaderId() {
+        tb = new ToolBox();
+    }
+
+    @Test
+    public void testAutoHeaderId(Path base) throws Exception {
+        Path src = base.resolve("src");
+        tb.writeJavaFiles(src,
+                """
+                        package p;
+                        /**
+                         * First sentence.
+                         *
+                         * <h2>First Header</h2>
+                         *
+                         * <h3 id="fixed-id-1">Header with ID</h3>
+                         *
+                         * <h4><a id="fixed-id-2">Embedded A-Tag with ID</a></h4>
+                         *
+                         * <h5>{@code Embedded Code Tag}</h5>
+                         *
+                         * <h6>{@linkplain C Embedded Link Tag}</h6>
+                         *
+                         * <h3>Duplicate Text</h3>
+                         *
+                         * <h4>Duplicate Text</h4>
+                         *
+                         * <h2>Extra (#*!. chars</h2>
+                         *
+                         * <h3 style="color: red;" class="some-class">Other attributes</h3>
+                         *
+                         * <h4></h4>
+                         *
+                         * Last sentence.
+                         */
+                        public class C {
+                            /** Comment. */
+                            C() { }
+                        }
+                        """);
+
+        javadoc("-d", base.resolve("api").toString(),
+                "-sourcepath", src.toString(),
+                "--no-platform-links", "p");
+
+        checkOutput("p/C.html", true,
+                """
+                    <h2 id="first-header-heading">First Header</h2>
+                    """,
+                """
+                    <h3 id="fixed-id-1">Header with ID</h3>
+                    """,
+                """
+                    <h4><a id="fixed-id-2">Embedded A-Tag with ID</a></h4>
+                    """,
+                """
+                    <h5 id="embedded-code-tag-heading"><code>Embedded Code Tag</code></h5>
+                    """,
+                """
+                    <h6 id="embedded-link-tag-heading"><a href="C.html" title="class in p">Embedded Link Tag</a></h6>
+                    """,
+                """
+                    <h3 id="duplicate-text-heading">Duplicate Text</h3>
+                    """,
+                """
+                    <h4 id="duplicate-text-heading1">Duplicate Text</h4>
+                    """,
+                """
+                    <h2 id="extra-chars-heading">Extra (#*!. chars</h2>
+                    """,
+                """
+                    <h3 id="other-attributes-heading" style="color: red;" class="some-class">Other attributes</h3>
+                    """,
+                """
+                    <h4 id="-heading"></h4>
+                    """);
+    }
+}

test/langtools/jdk/javadoc/doclet/testIndexInDocFiles/TestIndexInDocFiles.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 2022, 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
@@ -100,13 +100,13 @@ public void testPackageDocFiles(Path base) throws IOException {
 
         checkOutput("doc-files/top-level-file.html", true,
                 """
-                    <h1>Package HTML file</h1>
+                    <h1 id="package-html-file-heading">Package HTML file</h1>
                     <span id="top-level-index" class="search-tag-result">top-level-index</span>
                     <code><span id="top.level.property" class="search-tag-result">top.level.property</span></code>
                     """);
         checkOutput("p/q/doc-files/package-file.html", true,
                 """
-                    <h1>Package HTML file</h1>
+                    <h1 id="package-html-file-heading">Package HTML file</h1>
                     <span id="package-index" class="search-tag-result">package-index</span>
                     <code><span id="package.property" class="search-tag-result">package.property</span></code>
                     """);
@@ -170,13 +170,13 @@ public void testModuleDocFiles(Path base) throws IOException {
 
         checkOutput("m.n/doc-files/module-file.html", true,
                 """
-                    <h1>Module HTML file</h1>
+                    <h1 id="module-html-file-heading">Module HTML file</h1>
                     <span id="module-index" class="search-tag-result">module-index</span>
                     <code><span id="module.property" class="search-tag-result">module.property</span></code>
                     """);
         checkOutput("m.n/p/q/doc-files/package-file.html", true,
                 """
-                    <h1>Package HTML file</h1>
+                    <h1 id="package-html-file-heading">Package HTML file</h1>
                     <span id="package-index" class="search-tag-result">package-index</span>
                     <code><span id="package.property" class="search-tag-result">package.property</span></code>
                     """);