8289332: Auto-generate ids for user-defined headings

Reviewed-by: jjg
This commit is contained in:
Hannes Wallnöfer 2022-08-17 17:14:34 +00:00
parent 0fc92637d2
commit 8b4e6ba01f
5 changed files with 195 additions and 11 deletions
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html
test/langtools/jdk/javadoc/doclet
testAutoHeaderId
testIndexInDocFiles

@ -27,7 +27,6 @@ package jdk.javadoc.internal.doclets.formats.html;
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.JavaFileManager;
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;

@ -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 @@ public class HtmlDocletWriter {
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 class HtmlDocletWriter {
@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 @@ public class HtmlDocletWriter {
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.
*

@ -28,6 +28,7 @@ package jdk.javadoc.internal.doclets.formats.html;
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 class HtmlIds {
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);
}
}

@ -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>
""");
}
}

@ -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 class TestIndexInDocFiles extends JavadocTester {
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 class TestIndexInDocFiles extends JavadocTester {
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>
""");