diff --git a/src/java.base/share/classes/java/net/URI.java b/src/java.base/share/classes/java/net/URI.java index 7248c8f0e154e..5df726966dbc2 100644 --- a/src/java.base/share/classes/java/net/URI.java +++ b/src/java.base/share/classes/java/net/URI.java @@ -486,14 +486,14 @@ * @since 1.4 * * @see RFC 2279: UTF-8, a - * transformation format of ISO 10646,
RFC 2373: IPv6 Addressing - * Architecture,
RFC 2396: Uniform - * Resource Identifiers (URI): Generic Syntax,
RFC 2732: Format for - * Literal IPv6 Addresses in URLs,
URISyntaxException + * transformation format of ISO 10646 + * @see RFC 2373: IPv6 Addressing + * Architecture + * @see RFC 2396: Uniform + * Resource Identifiers (URI): Generic Syntax + * @see RFC 2732: Format for + * Literal IPv6 Addresses in URLs + * @see URISyntaxException */ public final class URI diff --git a/src/java.base/share/classes/java/security/cert/PKIXRevocationChecker.java b/src/java.base/share/classes/java/security/cert/PKIXRevocationChecker.java index 14e17cccb2d7c..f176568d224e5 100644 --- a/src/java.base/share/classes/java/security/cert/PKIXRevocationChecker.java +++ b/src/java.base/share/classes/java/security/cert/PKIXRevocationChecker.java @@ -91,10 +91,10 @@ * * @see RFC 2560: X.509 * Internet Public Key Infrastructure Online Certificate Status Protocol - - * OCSP,
RFC 5280: Internet X.509 - * Public Key Infrastructure Certificate and Certificate Revocation List (CRL) - * Profile + * OCSP + * @see RFC 5280: + * Internet X.509 Public Key Infrastructure Certificate and Certificate + * Revocation List (CRL) Profile */ public abstract class PKIXRevocationChecker extends PKIXCertPathChecker { private URI ocspResponder; diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java index 6177605d58fcf..d1fc7a5149d74 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java @@ -25,6 +25,7 @@ package jdk.javadoc.internal.doclets.formats.html; +import java.util.ArrayList; import java.util.EnumSet; import java.util.List; import java.util.Set; @@ -53,6 +54,7 @@ import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml; +import jdk.javadoc.internal.doclets.formats.html.markup.TagName; import jdk.javadoc.internal.doclets.formats.html.markup.Text; import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration; import jdk.javadoc.internal.doclets.toolkit.Content; @@ -141,6 +143,9 @@ Context within(DocTree tree) { private final Contents contents; private final Context context; + // Threshold for length of @see tag label for switching from inline to block layout. + private static final int SEE_TAG_MAX_INLINE_LENGTH = 30; + /** * Creates a taglet writer. * @@ -310,48 +315,47 @@ public Content returnTagOutput(Element element, ReturnTree returnTag, boolean in @Override public Content seeTagOutput(Element holder, List seeTags) { - ContentBuilder body = new ContentBuilder(); + List links = new ArrayList<>(); for (DocTree dt : seeTags) { - appendSeparatorIfNotEmpty(body); - body.add(htmlWriter.seeTagToContent(holder, dt, context.within(dt))); + links.add(htmlWriter.seeTagToContent(holder, dt, context.within(dt))); } if (utils.isVariableElement(holder) && ((VariableElement)holder).getConstantValue() != null && htmlWriter instanceof ClassWriterImpl) { //Automatically add link to constant values page for constant fields. - appendSeparatorIfNotEmpty(body); DocPath constantsPath = htmlWriter.pathToRoot.resolve(DocPaths.CONSTANT_VALUES); String whichConstant = ((ClassWriterImpl) htmlWriter).getTypeElement().getQualifiedName() + "." + utils.getSimpleName(holder); DocLink link = constantsPath.fragment(whichConstant); - body.add(htmlWriter.links.createLink(link, + links.add(htmlWriter.links.createLink(link, Text.of(resources.getText("doclet.Constants_Summary")))); } if (utils.isClass(holder) && utils.isSerializable((TypeElement)holder)) { //Automatically add link to serialized form page for serializable classes. if (SerializedFormBuilder.serialInclude(utils, holder) && SerializedFormBuilder.serialInclude(utils, utils.containingPackage(holder))) { - appendSeparatorIfNotEmpty(body); DocPath serialPath = htmlWriter.pathToRoot.resolve(DocPaths.SERIALIZED_FORM); DocLink link = serialPath.fragment(utils.getFullyQualifiedName(holder)); - body.add(htmlWriter.links.createLink(link, + links.add(htmlWriter.links.createLink(link, Text.of(resources.getText("doclet.Serialized_Form")))); } } - if (body.isEmpty()) - return body; + if (links.isEmpty()) { + return Text.EMPTY; + } + // Use a different style if any link label is longer than 30 chars or contains commas. + boolean hasLongLabels = links.stream() + .anyMatch(c -> c.charCount() > SEE_TAG_MAX_INLINE_LENGTH || c.toString().contains(",")); + HtmlTree seeList = new HtmlTree(TagName.UL) + .setStyle(hasLongLabels ? HtmlStyle.seeListLong : HtmlStyle.seeList); + links.stream().filter(Content::isValid).forEach(item -> { + seeList.add(HtmlTree.LI(item)); + }); return new ContentBuilder( HtmlTree.DT(contents.seeAlso), - HtmlTree.DD(body)); - } - - private void appendSeparatorIfNotEmpty(ContentBuilder body) { - if (!body.isEmpty()) { - body.add(", "); - body.add(DocletConstants.NL); - } + HtmlTree.DD(seeList)); } @Override diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java index e1f3128d7d51c..32e6b6931de9f 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java @@ -339,6 +339,17 @@ public enum HtmlStyle { */ propertyDetails, + /** + * The class for the list containing the {@code @see} tags of an element. + */ + seeList, + + /** + * The class for the list containing the {@code @see} tags of an element + * when some of the tags have longer labels. + */ + seeListLong, + /** * The class for a {@code section} element containing details of the * serialized form of an element, on the "Serialized Form" page. diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css index c25513569e9e1..d41946b5ad1ad 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css @@ -332,6 +332,18 @@ ul.summary-list > li { margin-top:0; margin-bottom:1px; } +ul.see-list, ul.see-list-long { + padding-left: 0; + list-style: none; +} +ul.see-list li { + display: inline; +} +ul.see-list li:not(:last-child):after, +ul.see-list-long li:not(:last-child):after { + content: ", "; + white-space: pre-wrap; +} /* * Styles for tables. */ diff --git a/test/langtools/jdk/javadoc/doclet/testConstructors/TestConstructors.java b/test/langtools/jdk/javadoc/doclet/testConstructors/TestConstructors.java index 10cbc8bbeaddf..6738a2121fc2c 100644 --- a/test/langtools/jdk/javadoc/doclet/testConstructors/TestConstructors.java +++ b/test/langtools/jdk/javadoc/doclet/testConstructors/TestConstructors.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2013, 2020, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2013, 2021, 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 @@ -50,12 +50,16 @@ public void test() { checkOutput("pkg1/Outer.html", true, """
See Also:
-
Inner(),\s - Inner(int),\s - NestedInner(),\s - NestedInner(int),\s - Outer(),\s - Outer(int)
""", +
+ +
""", """ Link: Inner(), Outer(int), List<String>\n" - + " " - + "List<? extends CharSequence>\n" - + " someMethod(" - + "ArrayList<Integer>, int)\n" - + " otherMethod(" - + "Map<String, StringBuilder>, double)\n", + """ +
List<\ + ;String> + List<? extends CharSequence> + someMethod(ArrayList<Integer>\ + ;, int) + otherMethod(Map<String, Stri\ + ngBuilder>, double)
+ """, - "
\n" - + "
See Also:
\n" - + "
Map<String,​? extends " - + "CharSequence>, \n" - + "Map<String,​? super " - + "A<String,​? extends RuntimeException" - + ">>, \n" - + "someMethod" - + "(List<Number>, int), \n" - + "otherMethod" - + "(Map<String, ? extends CharSequence>, double)
\n" - + "
"); + """ +
+
See Also:
+
+ +
+
"""); checkOutput("pkg1/A.SomeException.html", true, - "
A<" - + "String" - + ",​A.SomeException>\n" - + " " - + "link to generic type with label
", - - "
\n" - + "
See Also:
\n" - + "
A<String" - + ",​A.SomeException>, \n" - + "Link to generic type with label
\n" - + "
" + """ +
A<String,​A.SomeException> + link to generic type with label\ +
""", + """ +
+
See Also:
+
+ +
+
""" ); } @@ -125,15 +131,22 @@ public void testInvalidLinks() { "-package", "pkg2"); checkExit(Exit.ERROR); checkOutput("pkg2/B.html", true, - "
java.util.Foo<String>\n" - + " Baz<Object>\n" - + " #b(List<Integer>)
", + """ +
java.util.Foo<String> + Baz<Object> + #b(List<Integer>)
""", - "
\n" - + "
See Also:
\n" - + "
java.util.List<Bar>, \n" - + "Baz<Object, String>, \n" - + "B#b(List<Baz>)
\n
"); + """ +
+
See Also:
+
+
    +
  • java.util.List<Bar>
    • +
  • Baz<Object, String>
    • +
  • B#b(List<Baz>)
    • +
+
+
"""); } } diff --git a/test/langtools/jdk/javadoc/doclet/testHref/TestHref.java b/test/langtools/jdk/javadoc/doclet/testHref/TestHref.java index d8a085e560289..dd3987a06e222 100644 --- a/test/langtools/jdk/javadoc/doclet/testHref/TestHref.java +++ b/test/langtools/jdk/javadoc/doclet/testHref/TestHref.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2003, 2021, 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 @@ -68,7 +68,9 @@ public void test() { //@see test. """ See Also: -
""" +
+