Skip to content
Permalink
Browse files
8262992: Improve @see output
Reviewed-by: jjg
  • Loading branch information
hns committed May 7, 2021
1 parent d2b5350 commit e0c86884e56c0f826f7c1626abdcbb9926b297fb
Showing with 394 additions and 227 deletions.
  1. +8 −8 src/java.base/share/classes/java/net/URI.java
  2. +4 −4 src/java.base/share/classes/java/security/cert/PKIXRevocationChecker.java
  3. +21 −17 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java
  4. +11 −0 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java
  5. +12 −0 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
  6. +11 −7 test/langtools/jdk/javadoc/doclet/testConstructors/TestConstructors.java
  7. +81 −68 test/langtools/jdk/javadoc/doclet/testGenericTypeLink/TestGenericTypeLink.java
  8. +4 −2 test/langtools/jdk/javadoc/doclet/testHref/TestHref.java
  9. +58 −14 test/langtools/jdk/javadoc/doclet/testHtmlDefinitionListTag/TestHtmlDefinitionListTag.java
  10. +6 −2 test/langtools/jdk/javadoc/doclet/testJavaFX/TestJavaFX.java
  11. +14 −8 test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOption.java
  12. +2 −2 test/langtools/jdk/javadoc/doclet/testLinkOption/TestOptionOrder.java
  13. +8 −8 test/langtools/jdk/javadoc/doclet/testLinkOption/pkg/B.java
  14. +7 −3 test/langtools/jdk/javadoc/doclet/testModules/TestModules.java
  15. +5 −1 test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java
  16. +18 −6 test/langtools/jdk/javadoc/doclet/testProperty/TestProperty.java
  17. +28 −10 test/langtools/jdk/javadoc/doclet/testSeeTag/TestSeeTag.java
  18. +54 −46 test/langtools/jdk/javadoc/doclet/testSeeTag/TestSeeTagWithModule.java
  19. +2 −1 test/langtools/jdk/javadoc/doclet/testSeeTag/pkg/Test2.java
  20. +5 −1 test/langtools/jdk/javadoc/doclet/testSerializedForm/TestSerializedForm.java
  21. +11 −3 ...tools/jdk/javadoc/doclet/testSerializedFormDeprecationInfo/TestSerializedFormDeprecationInfo.java
  22. +14 −14 test/langtools/jdk/javadoc/doclet/testSingletonLists/TestSingletonLists.java
  23. +10 −2 test/langtools/jdk/javadoc/doclet/testTagOrder/TestTagOrder.java
@@ -486,14 +486,14 @@
* @since 1.4
*
* @see <a href="http://www.ietf.org/rfc/rfc2279.txt"><i>RFC&nbsp;2279: UTF-8, a
* transformation format of ISO 10646</i></a>, <br><a
* href="http://www.ietf.org/rfc/rfc2373.txt"><i>RFC&nbsp;2373: IPv6 Addressing
* Architecture</i></a>, <br><a
* href="http://www.ietf.org/rfc/rfc2396.txt"><i>RFC&nbsp;2396: Uniform
* Resource Identifiers (URI): Generic Syntax</i></a>, <br><a
* href="http://www.ietf.org/rfc/rfc2732.txt"><i>RFC&nbsp;2732: Format for
* Literal IPv6 Addresses in URLs</i></a>, <br><a
* href="URISyntaxException.html">URISyntaxException</a>
* transformation format of ISO 10646</i></a>
* @see <a href="http://www.ietf.org/rfc/rfc2373.txt"><i>RFC&nbsp;2373: IPv6 Addressing
* Architecture</i></a>
* @see <a href="http://www.ietf.org/rfc/rfc2396.txt"><i>RFC&nbsp;2396: Uniform
* Resource Identifiers (URI): Generic Syntax</i></a>
* @see <a href="http://www.ietf.org/rfc/rfc2732.txt"><i>RFC&nbsp;2732: Format for
* Literal IPv6 Addresses in URLs</i></a>
* @see <a href="URISyntaxException.html">URISyntaxException</a>
*/

public final class URI
@@ -91,10 +91,10 @@
*
* @see <a href="http://www.ietf.org/rfc/rfc2560.txt"><i>RFC&nbsp;2560: X.509
* Internet Public Key Infrastructure Online Certificate Status Protocol -
* OCSP</i></a>, <br><a
* href="http://www.ietf.org/rfc/rfc5280.txt"><i>RFC&nbsp;5280: Internet X.509
* Public Key Infrastructure Certificate and Certificate Revocation List (CRL)
* Profile</i></a>
* OCSP</i></a>
* @see <a href="http://www.ietf.org/rfc/rfc5280.txt"><i>RFC&nbsp;5280:
* Internet X.509 Public Key Infrastructure Certificate and Certificate
* Revocation List (CRL) Profile</i></a>
*/
public abstract class PKIXRevocationChecker extends PKIXCertPathChecker {
private URI ocspResponder;
@@ -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<? extends SeeTree> seeTags) {
ContentBuilder body = new ContentBuilder();
List<Content> 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
@@ -339,6 +339,17 @@
*/
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.
@@ -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.
*/
@@ -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,
"""
<dt>See Also:</dt>
<dd><a href="Outer.Inner.html#%3Cinit%3E()"><code>Inner()</code></a>,\s
<a href="Outer.Inner.html#%3Cinit%3E(int)"><code>Inner(int)</code></a>,\s
<a href="Outer.Inner.NestedInner.html#%3Cinit%3E()"><code>NestedInner()</code></a>,\s
<a href="Outer.Inner.NestedInner.html#%3Cinit%3E(int)"><code>NestedInner(int)</code></a>,\s
<a href="#%3Cinit%3E()"><code>Outer()</code></a>,\s
<a href="#%3Cinit%3E(int)"><code>Outer(int)</code></a></dd>""",
<dd>
<ul class="see-list">
<li><a href="Outer.Inner.html#%3Cinit%3E()"><code>Inner()</code></a></li>
<li><a href="Outer.Inner.html#%3Cinit%3E(int)"><code>Inner(int)</code></a></li>
<li><a href="Outer.Inner.NestedInner.html#%3Cinit%3E()"><code>NestedInner()</code></a></li>
<li><a href="Outer.Inner.NestedInner.html#%3Cinit%3E(int)"><code>NestedInner(int)</code></a></li>
<li><a href="#%3Cinit%3E()"><code>Outer()</code></a></li>
<li><a href="#%3Cinit%3E(int)"><code>Outer(int)</code></a></li>
</ul>
</dd>""",
"""
Link: <a href="Outer.Inner.html#%3Cinit%3E()"><code>Inner()</code></a>, <a href=\
"#%3Cinit%3E(int)"><code>Outer(int)</code></a>, <a href="Outer.Inner.NestedInner\

0 comments on commit e0c8688

Please sign in to comment.