Skip to content

Commit e0c8688

Browse files
hnshns
committed
8262992: Improve @see output
Reviewed-by: jjg
1 parent d2b5350 commit e0c8688

File tree

23 files changed

+394
-227
lines changed

23 files changed

+394
-227
lines changed

‎src/java.base/share/classes/java/net/URI.java

+8-8
Original file line numberDiff line numberDiff line change
@@ -486,14 +486,14 @@
486486
* @since 1.4
487487
*
488488
* @see <a href="http://www.ietf.org/rfc/rfc2279.txt"><i>RFC&nbsp;2279: UTF-8, a
489-
* transformation format of ISO 10646</i></a>, <br><a
490-
* href="http://www.ietf.org/rfc/rfc2373.txt"><i>RFC&nbsp;2373: IPv6 Addressing
491-
* Architecture</i></a>, <br><a
492-
* href="http://www.ietf.org/rfc/rfc2396.txt"><i>RFC&nbsp;2396: Uniform
493-
* Resource Identifiers (URI): Generic Syntax</i></a>, <br><a
494-
* href="http://www.ietf.org/rfc/rfc2732.txt"><i>RFC&nbsp;2732: Format for
495-
* Literal IPv6 Addresses in URLs</i></a>, <br><a
496-
* href="URISyntaxException.html">URISyntaxException</a>
489+
* transformation format of ISO 10646</i></a>
490+
* @see <a href="http://www.ietf.org/rfc/rfc2373.txt"><i>RFC&nbsp;2373: IPv6 Addressing
491+
* Architecture</i></a>
492+
* @see <a href="http://www.ietf.org/rfc/rfc2396.txt"><i>RFC&nbsp;2396: Uniform
493+
* Resource Identifiers (URI): Generic Syntax</i></a>
494+
* @see <a href="http://www.ietf.org/rfc/rfc2732.txt"><i>RFC&nbsp;2732: Format for
495+
* Literal IPv6 Addresses in URLs</i></a>
496+
* @see <a href="URISyntaxException.html">URISyntaxException</a>
497497
*/
498498

499499
public final class URI

‎src/java.base/share/classes/java/security/cert/PKIXRevocationChecker.java

+4-4
Original file line numberDiff line numberDiff line change
@@ -91,10 +91,10 @@
9191
*
9292
* @see <a href="http://www.ietf.org/rfc/rfc2560.txt"><i>RFC&nbsp;2560: X.509
9393
* Internet Public Key Infrastructure Online Certificate Status Protocol -
94-
* OCSP</i></a>, <br><a
95-
* href="http://www.ietf.org/rfc/rfc5280.txt"><i>RFC&nbsp;5280: Internet X.509
96-
* Public Key Infrastructure Certificate and Certificate Revocation List (CRL)
97-
* Profile</i></a>
94+
* OCSP</i></a>
95+
* @see <a href="http://www.ietf.org/rfc/rfc5280.txt"><i>RFC&nbsp;5280:
96+
* Internet X.509 Public Key Infrastructure Certificate and Certificate
97+
* Revocation List (CRL) Profile</i></a>
9898
*/
9999
public abstract class PKIXRevocationChecker extends PKIXCertPathChecker {
100100
private URI ocspResponder;

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java

+21-17
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@
2525

2626
package jdk.javadoc.internal.doclets.formats.html;
2727

28+
import java.util.ArrayList;
2829
import java.util.EnumSet;
2930
import java.util.List;
3031
import java.util.Set;
@@ -53,6 +54,7 @@
5354
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
5455
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
5556
import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
57+
import jdk.javadoc.internal.doclets.formats.html.markup.TagName;
5658
import jdk.javadoc.internal.doclets.formats.html.markup.Text;
5759
import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
5860
import jdk.javadoc.internal.doclets.toolkit.Content;
@@ -141,6 +143,9 @@ Context within(DocTree tree) {
141143
private final Contents contents;
142144
private final Context context;
143145

146+
// Threshold for length of @see tag label for switching from inline to block layout.
147+
private static final int SEE_TAG_MAX_INLINE_LENGTH = 30;
148+
144149
/**
145150
* Creates a taglet writer.
146151
*
@@ -310,48 +315,47 @@ public Content returnTagOutput(Element element, ReturnTree returnTag, boolean in
310315

311316
@Override
312317
public Content seeTagOutput(Element holder, List<? extends SeeTree> seeTags) {
313-
ContentBuilder body = new ContentBuilder();
318+
List<Content> links = new ArrayList<>();
314319
for (DocTree dt : seeTags) {
315-
appendSeparatorIfNotEmpty(body);
316-
body.add(htmlWriter.seeTagToContent(holder, dt, context.within(dt)));
320+
links.add(htmlWriter.seeTagToContent(holder, dt, context.within(dt)));
317321
}
318322
if (utils.isVariableElement(holder) && ((VariableElement)holder).getConstantValue() != null &&
319323
htmlWriter instanceof ClassWriterImpl) {
320324
//Automatically add link to constant values page for constant fields.
321-
appendSeparatorIfNotEmpty(body);
322325
DocPath constantsPath =
323326
htmlWriter.pathToRoot.resolve(DocPaths.CONSTANT_VALUES);
324327
String whichConstant =
325328
((ClassWriterImpl) htmlWriter).getTypeElement().getQualifiedName() + "." +
326329
utils.getSimpleName(holder);
327330
DocLink link = constantsPath.fragment(whichConstant);
328-
body.add(htmlWriter.links.createLink(link,
331+
links.add(htmlWriter.links.createLink(link,
329332
Text.of(resources.getText("doclet.Constants_Summary"))));
330333
}
331334
if (utils.isClass(holder) && utils.isSerializable((TypeElement)holder)) {
332335
//Automatically add link to serialized form page for serializable classes.
333336
if (SerializedFormBuilder.serialInclude(utils, holder) &&
334337
SerializedFormBuilder.serialInclude(utils, utils.containingPackage(holder))) {
335-
appendSeparatorIfNotEmpty(body);
336338
DocPath serialPath = htmlWriter.pathToRoot.resolve(DocPaths.SERIALIZED_FORM);
337339
DocLink link = serialPath.fragment(utils.getFullyQualifiedName(holder));
338-
body.add(htmlWriter.links.createLink(link,
340+
links.add(htmlWriter.links.createLink(link,
339341
Text.of(resources.getText("doclet.Serialized_Form"))));
340342
}
341343
}
342-
if (body.isEmpty())
343-
return body;
344+
if (links.isEmpty()) {
345+
return Text.EMPTY;
346+
}
347+
// Use a different style if any link label is longer than 30 chars or contains commas.
348+
boolean hasLongLabels = links.stream()
349+
.anyMatch(c -> c.charCount() > SEE_TAG_MAX_INLINE_LENGTH || c.toString().contains(","));
350+
HtmlTree seeList = new HtmlTree(TagName.UL)
351+
.setStyle(hasLongLabels ? HtmlStyle.seeListLong : HtmlStyle.seeList);
352+
links.stream().filter(Content::isValid).forEach(item -> {
353+
seeList.add(HtmlTree.LI(item));
354+
});
344355

345356
return new ContentBuilder(
346357
HtmlTree.DT(contents.seeAlso),
347-
HtmlTree.DD(body));
348-
}
349-
350-
private void appendSeparatorIfNotEmpty(ContentBuilder body) {
351-
if (!body.isEmpty()) {
352-
body.add(", ");
353-
body.add(DocletConstants.NL);
354-
}
358+
HtmlTree.DD(seeList));
355359
}
356360

357361
@Override

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java

+11
Original file line numberDiff line numberDiff line change
@@ -339,6 +339,17 @@ public enum HtmlStyle {
339339
*/
340340
propertyDetails,
341341

342+
/**
343+
* The class for the list containing the {@code @see} tags of an element.
344+
*/
345+
seeList,
346+
347+
/**
348+
* The class for the list containing the {@code @see} tags of an element
349+
* when some of the tags have longer labels.
350+
*/
351+
seeListLong,
352+
342353
/**
343354
* The class for a {@code section} element containing details of the
344355
* serialized form of an element, on the "Serialized Form" page.

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css

+12
Original file line numberDiff line numberDiff line change
@@ -332,6 +332,18 @@ ul.summary-list > li {
332332
margin-top:0;
333333
margin-bottom:1px;
334334
}
335+
ul.see-list, ul.see-list-long {
336+
padding-left: 0;
337+
list-style: none;
338+
}
339+
ul.see-list li {
340+
display: inline;
341+
}
342+
ul.see-list li:not(:last-child):after,
343+
ul.see-list-long li:not(:last-child):after {
344+
content: ", ";
345+
white-space: pre-wrap;
346+
}
335347
/*
336348
* Styles for tables.
337349
*/

‎test/langtools/jdk/javadoc/doclet/testConstructors/TestConstructors.java

+11-7
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2013, 2020, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2013, 2021, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -50,12 +50,16 @@ public void test() {
5050
checkOutput("pkg1/Outer.html", true,
5151
"""
5252
<dt>See Also:</dt>
53-
<dd><a href="Outer.Inner.html#%3Cinit%3E()"><code>Inner()</code></a>,\s
54-
<a href="Outer.Inner.html#%3Cinit%3E(int)"><code>Inner(int)</code></a>,\s
55-
<a href="Outer.Inner.NestedInner.html#%3Cinit%3E()"><code>NestedInner()</code></a>,\s
56-
<a href="Outer.Inner.NestedInner.html#%3Cinit%3E(int)"><code>NestedInner(int)</code></a>,\s
57-
<a href="#%3Cinit%3E()"><code>Outer()</code></a>,\s
58-
<a href="#%3Cinit%3E(int)"><code>Outer(int)</code></a></dd>""",
53+
<dd>
54+
<ul class="see-list">
55+
<li><a href="Outer.Inner.html#%3Cinit%3E()"><code>Inner()</code></a></li>
56+
<li><a href="Outer.Inner.html#%3Cinit%3E(int)"><code>Inner(int)</code></a></li>
57+
<li><a href="Outer.Inner.NestedInner.html#%3Cinit%3E()"><code>NestedInner()</code></a></li>
58+
<li><a href="Outer.Inner.NestedInner.html#%3Cinit%3E(int)"><code>NestedInner(int)</code></a></li>
59+
<li><a href="#%3Cinit%3E()"><code>Outer()</code></a></li>
60+
<li><a href="#%3Cinit%3E(int)"><code>Outer(int)</code></a></li>
61+
</ul>
62+
</dd>""",
5963
"""
6064
Link: <a href="Outer.Inner.html#%3Cinit%3E()"><code>Inner()</code></a>, <a href=\
6165
"#%3Cinit%3E(int)"><code>Outer(int)</code></a>, <a href="Outer.Inner.NestedInner\

0 commit comments

Comments
 (0)