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

8207214: Broken links in JDK API serialized-form page

Browse Source 
Reviewed-by: hannesw
This commit is contained in:
Jonathan Gibbons 2018-07-24 11:37:43 -07:00
parent 1dcf1dda27
commit 955ce37d60
5 changed files with 189 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -893,7 +893,7 @@ public class HtmlDocletWriter {
return getDocLink(context, typeElement, element, label, strong, false);
}
/**
/**
* Return the link for the given member.
*
* @param context the id of the context where the link will be printed.
@ -913,22 +913,26 @@ public class HtmlDocletWriter {
public Content getDocLink(LinkInfoImpl.Kind context, TypeElement typeElement, Element element,
Content label, boolean strong, boolean isProperty) {
if (! (utils.isIncluded(element) || utils.isLinkable(typeElement))) {
if (!utils.isLinkable(typeElement, element)) {
return label;
} else if (utils.isExecutableElement(element)) {
}
if (utils.isExecutableElement(element)) {
ExecutableElement ee = (ExecutableElement)element;
return getLink(new LinkInfoImpl(configuration, context, typeElement)
.label(label)
.where(links.getName(getAnchor(ee, isProperty)))
.strong(strong));
} else if (utils.isVariableElement(element) || utils.isTypeElement(element)) {
}
if (utils.isVariableElement(element) || utils.isTypeElement(element)) {
return getLink(new LinkInfoImpl(configuration, context, typeElement)
.label(label)
.where(links.getName(element.getSimpleName().toString()))
.strong(strong));
} else {
return label;
}
return label;
}
/**
@ -982,7 +986,6 @@ public class HtmlDocletWriter {
}
public Content seeTagToContent(Element element, DocTree see) {
Kind kind = see.getKind();
if (!(kind == LINK || kind == SEE || kind == LINK_PLAIN)) {
return new ContentBuilder();

8
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java
View File

@ -273,11 +273,9 @@ public class TagletWriterImpl extends TagletWriter {
*/
public Content seeTagOutput(Element holder, List<? extends DocTree> seeTags) {
ContentBuilder body = new ContentBuilder();
if (!seeTags.isEmpty()) {
for (DocTree dt : seeTags) {
appendSeparatorIfNotEmpty(body);
body.addContent(htmlWriter.seeTagToContent(holder, dt));
}
for (DocTree dt : seeTags) {
appendSeparatorIfNotEmpty(body);
body.addContent(htmlWriter.seeTagToContent(holder, dt));
}
if (utils.isVariableElement(holder) && ((VariableElement)holder).getConstantValue() != null &&
htmlWriter instanceof ClassWriterImpl) {

1
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties
View File

@ -223,7 +223,6 @@ doclet.Annotation_Type_Optional_Member=Optional Element
doclet.Annotation_Type_Required_Member=Required Element
doclet.Annotation_Type_Member=Annotation Type Element
doclet.Enum_Constant=Enum Constant
doclet.Class=Class
doclet.Description=Description
doclet.ConstantField=Constant Field
doclet.Value=Value

43
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java
View File

@ -1016,9 +1016,9 @@ public class Utils {
}
/**
* Return true if this class is linkable and false if we can't link to the
* desired class.
* <br>
* Returns true if this class is linkable and false if we can't link to it.
*
* <p>
* <b>NOTE:</b> You can only link to external classes if they are public or
* protected.
*
@ -1033,6 +1033,43 @@ public class Utils {
(isPublic(typeElem) || isProtected(typeElem)));
}
/**
* Returns true if an element is linkable in the context of a given type element.
*
* If the element is a type element, it delegates to {@link #isLinkable(TypeElement)}.
* Otherwise, the element is linkable if any of the following are true:
* <ul>
* <li>it is "included" (see {@link jdk.javadoc.doclet})
* <li>it is inherited from an undocumented supertype
* <li>it is a public or protected member of an external API
* </ul>
*
* @param typeElem the type element
* @param elem the element
* @return whether or not the element is linkable
*/
public boolean isLinkable(TypeElement typeElem, Element elem) {
if (isTypeElement(elem)) {
return isLinkable((TypeElement) elem); // defer to existing behavior
}
if (isIncluded(elem)) {
return true;
}
// Allow for the behavior that members of undocumented supertypes
// may be included in documented types
TypeElement enclElem = getEnclosingTypeElement(elem);
if (typeElem != enclElem && isSubclassOf(typeElem, enclElem)) {
return true;
}
// Allow for external members
return isLinkable(typeElem)
&& configuration.extern.isExternal(typeElem)
&& (isPublic(elem) || isProtected(elem));
}
/**
* Return this type as a {@code TypeElement} if it represents a class
* interface or annotation. Array dimensions are ignored.

136
test/langtools/jdk/javadoc/doclet/testSerializedFormWithSee/TestSerializedFormWithSee.java Normal file
View File

@ -0,0 +1,136 @@
/*
* Copyright (c) 2018, 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 8207214
* @summary Test serialized forms, with at-see to other members
* @library /tools/lib ../lib
* @modules jdk.javadoc/jdk.javadoc.internal.tool
* @build JavadocTester toolbox.ToolBox
* @run main TestSerializedFormWithSee
*/
import java.io.IOException;
import java.nio.file.Path;
import java.nio.file.Paths;
import toolbox.ToolBox;
/**
* Test the links generated in source files with combinations
* of modules, Serializable, and @see for public and private methods.
*
* In the various test cases, in addition to the explicit call
* to {@code checkExit}, the primary check is the implicit call
* to {@code checkLinks}, to verify that there are no broken
* links in the generated files.
*/
public class TestSerializedFormWithSee extends JavadocTester {
public static void main(String... args) throws Exception {
TestSerializedFormWithSee tester = new TestSerializedFormWithSee();
tester.runTests(m -> new Object[] { Paths.get(m.getName()) });
}
private final ToolBox tb;
TestSerializedFormWithSee() {
tb = new ToolBox();
}
@Test
public void test_noModule_notSerializable(Path base) throws IOException {
Path srcDir = generateSource(base, false, false);
Path outDir = base.resolve("out");
javadoc("-d", outDir.toString(),
"-sourcepath", srcDir.toString(),
"p");
checkExit(Exit.OK);
}
@Test
public void test_noModule_serializable(Path base) throws IOException {
Path srcDir = generateSource(base, false, true);
Path outDir = base.resolve("out");
javadoc("-d", outDir.toString(),
"-sourcepath", srcDir.toString(),
"p");
checkExit(Exit.OK);
}
@Test
public void test_module_notSerializable(Path base) throws IOException {
Path srcDir = generateSource(base, true, false);
Path outDir = base.resolve("out");
javadoc("-d", outDir.toString(),
"-sourcepath", srcDir.toString(),
"m/p");
checkExit(Exit.OK);
}
@Test
public void test_module_serializable(Path base) throws IOException {
Path srcDir = generateSource(base, true, true);
Path outDir = base.resolve("out");
javadoc("-d", outDir.toString(),
"-sourcepath", srcDir.toString(),
"m/p");
checkExit(Exit.OK);
}
Path generateSource(Path base, boolean module, boolean serializable) throws IOException {
Path dir = base.resolve("src");
if (module) {
tb.writeJavaFiles(dir, "module m { }");
}
StringBuilder sb = new StringBuilder();
sb.append("package p;\n");
sb.append("public class C " + (serializable ? "implements java.io.Serializable " : "") + "{\n");
for (String access : new String[] { "public", "private" }) {
sb.append(" /**\n");
sb.append(" * This is a " + access + " " + (serializable ? "serializable " : "") + "field.\n");
sb.append(" * More description.\n");
sb.append(" * " + (serializable ? "@serial This is the serial description." : "") + "\n");
sb.append(" * @see #publicMethod()\n");
sb.append(" * @see #privateMethod()\n");
sb.append(" */\n");
sb.append(" " + access + " int " + access + "Field;\n");
}
for (String access : new String[] { "public", "private" }) {
sb.append(" /**\n");
sb.append(" * This is a " + access + " method.\n");
sb.append(" * More description.\n");
sb.append(" * @return zero.\n");
sb.append(" */\n");
sb.append(" " + access + " int " + access + "Method() { return 0; }\n");
}
sb.append(" }\n");
tb.writeJavaFiles(dir, sb.toString());
return dir;
}
}