8289332: Auto-generate ids for user-defined headings
Reviewed-by: jjg
This commit is contained in:
parent
0fc92637d2
commit
8b4e6ba01f
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html
test/langtools/jdk/javadoc/doclet
@ -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>
|
||||
""");
|
||||
|
Loading…
x
Reference in New Issue
Block a user