stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8297437: javadoc cannot link to old docs (with old style anchors)

Browse Source 
Reviewed-by: hannesw
This commit is contained in:
Roman Marchenko 2023-01-26 11:11:21 +00:00 committed by Hannes Wallnöfer
parent b0376a5f44
commit 15a1488401
6 changed files with 144 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1998, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1998, 2023, 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
@ -103,6 +103,11 @@ public class Extern {
*/
final boolean relative;
/**
* Indicates that docs use old-form of anchors.
*/
final boolean useOldFormId;
/**
* Constructor to build a Extern Item object and map it with the element name.
* If the same element name is found in the map, then the first mapped
@ -113,10 +118,11 @@ public class Extern {
* file is picked.
* @param relative True if path is URL, false if directory path.
*/
Item(String elementName, DocPath path, boolean relative) {
Item(String elementName, DocPath path, boolean relative, boolean useOldFormId) {
this.elementName = elementName;
this.path = path;
this.relative = relative;
this.useOldFormId = useOldFormId;
}
/**
@ -186,7 +192,7 @@ public class Extern {
DocPath p = fnd.relative ?
relativepath.resolve(fnd.path).resolve(filename) :
fnd.path.resolve(filename);
return new DocLink(p, memberName);
return new DocLink(p, fnd.useOldFormId ? getOldFormHtmlName(memberName) : memberName);
}
/**
@ -256,7 +262,7 @@ public class Extern {
reporter.print(Kind.WARNING, resources.getText("doclet.Resource_error", elementListPath.getPath()));
} else {
try (InputStream in = open(elementListUrl)) {
readElementList(in, docUrl, false, versionNumber);
readElementList(in, docUrl, false, versionNumber, isOldFormPlatformDocs(versionNumber));
} catch (IOException exc) {
throw new Fault(resources.getText(
"doclet.Resource_error", elementListPath.getPath()), exc);
@ -267,6 +273,18 @@ public class Extern {
}
}
/**
* Checks if platform docs for the specified version use old-form anchors.
* Old-form anchors are used by Oracle docs for JDKs 8 and 9.
* It can be checked on https://docs.oracle.com/javase/<version>/docs/api
*
* @param version
* @return True if docs use old-form anchors
*/
private boolean isOldFormPlatformDocs(int version) {
return 8 == version || 9 == version;
}
/**
* Return the resource path for the package or element list for the given {@code version}.
* @param version the platform version number
@ -419,7 +437,7 @@ public class Extern {
try {
URL link = elemlisturlpath.toURI().resolve(DocPaths.ELEMENT_LIST.getPath()).toURL();
try (InputStream in = open(link)) {
readElementList(in, urlpath, false, 0);
readElementList(in, urlpath, false, 0, false);
}
} catch (URISyntaxException | MalformedURLException exc) {
throw new Fault(resources.getText("doclet.MalformedURL", elemlisturlpath.toString()), exc);
@ -438,7 +456,7 @@ public class Extern {
try {
URL link = elemlisturlpath.toURI().resolve(DocPaths.PACKAGE_LIST.getPath()).toURL();
try (InputStream in = open(link)) {
readElementList(in, urlpath, false, 0);
readElementList(in, urlpath, false, 0, true);
}
} catch (URISyntaxException | MalformedURLException exc) {
throw new Fault(resources.getText("doclet.MalformedURL", elemlisturlpath.toString()), exc);
@ -462,27 +480,27 @@ public class Extern {
file = file.resolveAgainst(DocumentationTool.Location.DOCUMENTATION_OUTPUT);
}
if (file.exists()) {
readElementList(file, path);
readElementList(file, path, false);
} else {
DocFile file1 = elemListPath.resolve(DocPaths.PACKAGE_LIST);
if (!(file1.isAbsolute() || linkoffline)) {
file1 = file1.resolveAgainst(DocumentationTool.Location.DOCUMENTATION_OUTPUT);
}
if (file1.exists()) {
readElementList(file1, path);
readElementList(file1, path, true);
} else {
throw new Fault(resources.getText("doclet.File_error", file.getPath()), null);
}
}
}
private void readElementList(DocFile file, String path) throws Fault, DocFileIOException {
private void readElementList(DocFile file, String path, boolean isOldFormDoc) throws Fault, DocFileIOException {
try {
if (file.canRead()) {
boolean pathIsRelative
= !isUrl(path)
&& !DocFile.createFileForInput(configuration, path).isAbsolute();
readElementList(file.openInputStream(), path, pathIsRelative, 0);
readElementList(file.openInputStream(), path, pathIsRelative, 0, isOldFormDoc);
} else {
throw new Fault(resources.getText("doclet.File_error", file.getPath()), null);
}
@ -502,7 +520,8 @@ public class Extern {
* or {@code 0} if it does not belong to a platform libraries doc bundle.
* @throws IOException if there is a problem reading or closing the stream
*/
private void readElementList(InputStream input, String path, boolean relative, int platformVersion)
private void readElementList(InputStream input, String path, boolean relative, int platformVersion,
boolean isOldFormDoc)
throws IOException {
try (BufferedReader in = new BufferedReader(new InputStreamReader(input))) {
String elemname;
@ -515,7 +534,7 @@ public class Extern {
elempath = basePath;
if (elemname.startsWith(DocletConstants.MODULE_PREFIX)) {
moduleName = elemname.replace(DocletConstants.MODULE_PREFIX, "");
Item item = new Item(moduleName, elempath, relative);
Item item = new Item(moduleName, elempath, relative, isOldFormDoc);
moduleItems.put(moduleName, item);
} else {
DocPath pkgPath = DocPath.create(elemname.replace('.', '/'));
@ -533,7 +552,7 @@ public class Extern {
} else {
actualModuleName = moduleName == null ? DocletConstants.DEFAULT_ELEMENT_NAME : moduleName;
}
Item item = new Item(elemname, elempath, relative);
Item item = new Item(elemname, elempath, relative, isOldFormDoc);
packageItems.computeIfAbsent(actualModuleName, k -> new TreeMap<>())
.putIfAbsent(elemname, item); // first-one-wins semantics
showDiagnostic = false;
@ -662,4 +681,65 @@ public class Extern {
case WARN -> configuration.getMessages().warning(key, arg);
}
}
/**
* Converts a name to an old-form HTML name (old-form id).
*
* @param name the string that needs to be converted to a valid HTML name
* @return old-form HTML name
*/
private String getOldFormHtmlName(String name) {
/* The HTML 4 spec at http://www.w3.org/TR/html4/types.html#h-6.2 mentions
* that the name/id should begin with a letter followed by other valid characters.
* The HTML 5 spec (draft) is more permissive on names/ids where the only restriction
* is that it should be at least one character long and should not contain spaces.
* The spec draft is @ http://www.w3.org/html/wg/drafts/html/master/dom.html#the-id-attribute.
*
* For HTML 4, we need to check for non-characters at the beginning of the name and
* substitute it accordingly, "_" and "$" can appear at the beginning of a member name.
* The method substitutes "$" with "Z:Z:D" and will prefix "_" with "Z:Z".
*/
if (null == name)
return name;
StringBuilder sb = new StringBuilder();
for (int i = 0; i < name.length(); i++) {
char ch = name.charAt(i);
switch (ch) {
case '(':
case ')':
case '<':
case '>':
case ',':
sb.append('-');
break;
case ' ':
case '[':
break;
case ']':
sb.append(":A");
break;
// Any appearance of $ needs to be substituted with ":D" and not with hyphen
// since a field name "P$$ and a method P(), both valid member names, can end
// up as "P--". A member name beginning with $ needs to be substituted with
// "Z:Z:D".
case '$':
if (i == 0)
sb.append("Z:Z");
sb.append(":D");
break;
// A member name beginning with _ needs to be prefixed with "Z:Z" since valid anchor
// names can only begin with a letter.
case '_':
if (i == 0)
sb.append("Z:Z");
sb.append(ch);
break;
default:
sb.append(ch);
}
}
return sb.toString();
}
}

6
test/langtools/jdk/javadoc/doclet/testClassCrossReferences/TestClassCrossReferences.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2002, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2002, 2023, 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
@ -65,7 +65,7 @@ public class TestClassCrossReferences extends JavadocTester {
java/math/BigDecimal.html" title="class or interface in java.math" class="extern\
al-link"><code>Link to external class BigDecimal</code></a>""",
"<a href=\"" + uri + """
java/math/BigInteger.html#gcd(java.math.BigInteger)" title="class or interface i\
java/math/BigInteger.html#gcd-java.math.BigInteger-" title="class or interface i\
n java.math" class="external-link"><code>Link to external member gcd</code></a>""",
"<a href=\"" + uri + """
javax/tools/SimpleJavaFileObject.html#uri" title="class or interface in javax.to\
@ -102,7 +102,7 @@ public class TestClassCrossReferences extends JavadocTester {
java/math/BigDecimal.html" title="class or interface in java.math" class="extern\
al-link"><code>Link to external class BigDecimal</code></a>""",
"<a href=\"" + uri + """
java/math/BigInteger.html#gcd(java.math.BigInteger)" title="class or interface i\
java/math/BigInteger.html#gcd-java.math.BigInteger-" title="class or interface i\
n java.math" class="external-link"><code>Link to external member gcd</code></a>""",
"<a href=\"" + uri + """
javax/tools/SimpleJavaFileObject.html#uri" title="class or interface in javax.to\

6
test/langtools/jdk/javadoc/doclet/testExternalOverriddenMethod/TestExternalOverriddenMethod.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2023, 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
@ -56,13 +56,13 @@ public class TestExternalOverriddenMethod extends JavadocTester {
"""
<dt>Overrides:</dt>
<dd><code><a href=\"""" + uri + """
/java/io/FilterReader.html#read()" title="class or interface in java.io" class="\
/java/io/FilterReader.html#read--" title="class or interface in java.io" class="\
external-link">read</a></code>&nbsp;in class&nbsp;<code><a href=\"""" + uri + """
/java/io/FilterReader.html" title="class or interface in java.io" class="external-link">FilterReader</a></code></dd>""",
"""
<dt>Specified by:</dt>
<dd><code><a href=\"""" + uri + """
/java/io/DataInput.html#readInt()" title="class or interface in java.io" class="\
/java/io/DataInput.html#readInt--" title="class or interface in java.io" class="\
external-link">readInt</a></code>&nbsp;in interface&nbsp;<code><a href=\"""" + uri + """
/java/io/DataInput.html" title="class or interface in java.io" class="external-link">DataInput</a></code></dd>"""
);

4
test/langtools/jdk/javadoc/doclet/testHref/TestHref.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2023, 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
@ -53,7 +53,7 @@ public class TestHref extends JavadocTester {
checkOutput("pkg/C1.html", true,
//External link.
"""
href="http://java.sun.com/j2se/1.4/docs/api/java/lang/Object.html#wait(long,int)\"""",
href="http://java.sun.com/j2se/1.4/docs/api/java/lang/Object.html#wait-long-int-\"""",
//Member summary table link.
"""
href="#method(int,int,java.util.ArrayList)\"""",

4
test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOption.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2002, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2002, 2023, 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
@ -89,7 +89,7 @@ public class TestLinkOption extends JavadocTester {
checkOutput("pkg/B.html", true,
"""
<div class="block">A method with html tag the method <a href=\"""" + url + """
java/lang/ClassLoader.html#getSystemClassLoader()" title="class or interface in \
java/lang/ClassLoader.html#getSystemClassLoader--" title="class or interface in \
java.lang" class="external-link"><code><b>getSystemClassLoader()</b></code></a> \
as the parent class loader.</div>""",
"""

58
test/langtools/jdk/javadoc/doclet/testLinkPlatform/TestLinkPlatform.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2020, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2020, 2023, 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 8216497
* @bug 8216497 8297437
* @summary javadoc should auto-link to platform classes
* @library /tools/lib ../../lib
* @modules
@ -103,11 +103,19 @@ public class TestLinkPlatform extends JavadocTester {
// Make sure there is no message about missing element-list resource
checkOutput(Output.OUT, false, "element-list");
String url = getPlatformUrlString(version);
checkOutput("p/q/A.html", true,
"<a href=\"" + url + "\"",
"<a href=\"" + url + "#clone()\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#equals(java.lang.Object)\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#finalize()\" title=\"class or interface in java.lang\" class=\"external-link\">");
if (version <= 9) {
checkOutput("p/q/A.html", true,
"<a href=\"" + url + "\"",
"<a href=\"" + url + "#clone--\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#equals-java.lang.Object-\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#finalize--\" title=\"class or interface in java.lang\" class=\"external-link\">");
} else {
checkOutput("p/q/A.html", true,
"<a href=\"" + url + "\"",
"<a href=\"" + url + "#clone()\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#equals(java.lang.Object)\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#finalize()\" title=\"class or interface in java.lang\" class=\"external-link\">");
}
}
}
@ -125,11 +133,19 @@ public class TestLinkPlatform extends JavadocTester {
checkExit(Exit.OK);
String url = getCustomPlatformUrlString(version);
checkOutput("p/q/A.html", true,
"<a href=\"" + url + "\"",
"<a href=\"" + url + "#clone()\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#equals(java.lang.Object)\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#finalize()\" title=\"class or interface in java.lang\" class=\"external-link\">");
if (version <= 9) {
checkOutput("p/q/A.html", true,
"<a href=\"" + url + "\"",
"<a href=\"" + url + "#clone--\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#equals-java.lang.Object-\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#finalize--\" title=\"class or interface in java.lang\" class=\"external-link\">");
} else {
checkOutput("p/q/A.html", true,
"<a href=\"" + url + "\"",
"<a href=\"" + url + "#clone()\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#equals(java.lang.Object)\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#finalize()\" title=\"class or interface in java.lang\" class=\"external-link\">");
}
}
}
@ -147,11 +163,19 @@ public class TestLinkPlatform extends JavadocTester {
checkExit(Exit.OK);
String url = getCustomPlatformUrlString(version);
checkOutput("p/q/A.html", true,
"<a href=\"" + url + "\"",
"<a href=\"" + url + "#clone()\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#equals(java.lang.Object)\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#finalize()\" title=\"class or interface in java.lang\" class=\"external-link\">");
if (version <= 9) {
checkOutput("p/q/A.html", true,
"<a href=\"" + url + "\"",
"<a href=\"" + url + "#clone--\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#equals-java.lang.Object-\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#finalize--\" title=\"class or interface in java.lang\" class=\"external-link\">");
} else {
checkOutput("p/q/A.html", true,
"<a href=\"" + url + "\"",
"<a href=\"" + url + "#clone()\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#equals(java.lang.Object)\" title=\"class or interface in java.lang\" class=\"external-link\">",
"<a href=\"" + url + "#finalize()\" title=\"class or interface in java.lang\" class=\"external-link\">");
}
}
}