Skip to content

Commit 3b513a4

Browse files
jonathan-gibbonsjonathan-gibbons
committedDec 1, 2022
8297802: display of @SPEC tags should mimic that of @see tags
Reviewed-by: prappo
1 parent 4485d4e commit 3b513a4

File tree

23 files changed

+135
-106
lines changed

23 files changed

+135
-106
lines changed
 

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

+17-19
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,6 @@
6161
import com.sun.source.doctree.SystemPropertyTree;
6262
import com.sun.source.doctree.TextTree;
6363
import com.sun.source.doctree.ThrowsTree;
64-
import com.sun.source.doctree.TextTree;
6564
import com.sun.source.util.DocTreePath;
6665
import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
6766
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlAttr;
@@ -85,7 +84,6 @@
8584
import jdk.javadoc.internal.doclets.toolkit.util.DocLink;
8685
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
8786
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
88-
import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants;
8987
import jdk.javadoc.internal.doclets.toolkit.util.IndexItem;
9088
import jdk.javadoc.internal.doclets.toolkit.util.Utils;
9189
import jdk.javadoc.internal.doclets.toolkit.util.Utils.PreviewFlagProvider;
@@ -163,7 +161,7 @@ Context within(DocTree tree) {
163161
private final Context context;
164162

165163
// Threshold for length of @see tag label for switching from inline to block layout.
166-
private static final int SEE_TAG_MAX_INLINE_LENGTH = 30;
164+
private static final int TAG_LIST_ITEM_MAX_INLINE_LENGTH = 30;
167165

168166
/**
169167
* Creates a taglet writer.
@@ -388,7 +386,7 @@ public Content seeTagOutput(Element holder, List<? extends SeeTree> seeTags) {
388386
}
389387
// Use a different style if any link label is longer than 30 chars or contains commas.
390388
boolean hasLongLabels = links.stream().anyMatch(this::isLongOrHasComma);
391-
var seeList = HtmlTree.UL(hasLongLabels ? HtmlStyle.seeListLong : HtmlStyle.seeList);
389+
var seeList = HtmlTree.UL(hasLongLabels ? HtmlStyle.tagListLong : HtmlStyle.tagList);
392390
links.stream()
393391
.filter(Predicate.not(Content::isEmpty))
394392
.forEach(item -> seeList.add(HtmlTree.LI(item)));
@@ -403,7 +401,7 @@ private boolean isLongOrHasComma(Content c) {
403401
.replaceAll("<.*?>", "") // ignore HTML
404402
.replaceAll("&#?[A-Za-z0-9]+;", " ") // entities count as a single character
405403
.replaceAll("\\R", "\n"); // normalize newlines
406-
return s.length() > SEE_TAG_MAX_INLINE_LENGTH || s.contains(",");
404+
return s.length() > TAG_LIST_ITEM_MAX_INLINE_LENGTH || s.contains(",");
407405
}
408406

409407
String textOf(List<? extends DocTree> trees) {
@@ -413,13 +411,6 @@ String textOf(List<? extends DocTree> trees) {
413411
.collect(Collectors.joining(" "));
414412
}
415413

416-
private void appendSeparatorIfNotEmpty(ContentBuilder body) {
417-
if (!body.isEmpty()) {
418-
body.add(", ");
419-
body.add(Text.NL);
420-
}
421-
}
422-
423414
/**
424415
* {@return the output for a single {@code @see} tag}
425416
*
@@ -753,17 +744,24 @@ public Element getLinkedElement(Element referer, String signature) {
753744

754745
@Override
755746
public Content specTagOutput(Element holder, List<? extends SpecTree> specTags) {
756-
ContentBuilder body = new ContentBuilder();
757-
for (SpecTree st : specTags) {
758-
appendSeparatorIfNotEmpty(body);
759-
body.add(specTagToContent(holder, st));
747+
if (specTags.isEmpty()) {
748+
return Text.EMPTY;
760749
}
761-
if (body.isEmpty())
762-
return body;
750+
751+
List<Content> links = specTags.stream()
752+
.map(st -> specTagToContent(holder, st))
753+
.collect(Collectors.toList());
754+
755+
// Use a different style if any link label is longer than 30 chars or contains commas.
756+
boolean hasLongLabels = links.stream().anyMatch(this::isLongOrHasComma);
757+
var specList = HtmlTree.UL(hasLongLabels ? HtmlStyle.tagListLong : HtmlStyle.tagList);
758+
links.stream()
759+
.filter(Predicate.not(Content::isEmpty))
760+
.forEach(item -> specList.add(HtmlTree.LI(item)));
763761

764762
return new ContentBuilder(
765763
HtmlTree.DT(contents.externalSpecifications),
766-
HtmlTree.DD(body));
764+
HtmlTree.DD(specList));
767765
}
768766

769767
private Content specTagToContent(Element holder, SpecTree specTree) {

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

+5-5
Original file line numberDiff line numberDiff line change
@@ -383,15 +383,15 @@ public enum HtmlStyle {
383383
previewLabel,
384384

385385
/**
386-
* The class for the list containing the {@code @see} tags of an element.
386+
* The class for a list containing the tags of an element.
387387
*/
388-
seeList,
388+
tagList,
389389

390390
/**
391-
* The class for the list containing the {@code @see} tags of an element
392-
* when some of the tags have longer labels.
391+
* The class for a list containing the tags of an element
392+
* when some tags have longer labels or contain commas.
393393
*/
394-
seeListLong,
394+
tagListLong,
395395

396396
//</editor-fold>
397397

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

+5-4
Original file line numberDiff line numberDiff line change
@@ -386,15 +386,16 @@ ul.ref-list > li {
386386
margin-top:0;
387387
margin-bottom:1px;
388388
}
389-
ul.see-list, ul.see-list-long {
389+
ul.tag-list, ul.tag-list-long {
390390
padding-left: 0;
391391
list-style: none;
392392
}
393-
ul.see-list li {
393+
ul.tag-list li {
394394
display: inline;
395395
}
396-
ul.see-list li:not(:last-child):after,
397-
ul.see-list-long li:not(:last-child):after {
396+
ul.tag-list li:not(:last-child):after,
397+
ul.tag-list-long li:not(:last-child):after
398+
{
398399
content: ", ";
399400
white-space: pre-wrap;
400401
}

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SpecTaglet.java

+3-4
Original file line numberDiff line numberDiff line change
@@ -63,15 +63,14 @@ public Content getAllBlockTagOutput(Element holder, TagletWriter writer) {
6363
Optional<Documentation> result = docFinder.search((ExecutableElement) holder,
6464
m -> Result.fromOptional(extract(utils, m))).toOptional();
6565
if (result.isPresent()) {
66-
ExecutableElement m = result.get().method();
67-
tags = utils.getSpecTrees(m);
68-
e = m;
66+
e = result.get().method();
67+
tags = result.get().specTrees();
6968
}
7069
}
7170
return writer.specTagOutput(e, tags);
7271
}
7372

74-
private record Documentation(List<? extends SpecTree> seeTrees, ExecutableElement method) { }
73+
private record Documentation(List<? extends SpecTree> specTrees, ExecutableElement method) { }
7574

7675
private static Optional<Documentation> extract(Utils utils, ExecutableElement method) {
7776
List<? extends SpecTree> tags = utils.getSpecTrees(method);

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ public void test() {
5151
"""
5252
<dt>See Also:</dt>
5353
<dd>
54-
<ul class="see-list">
54+
<ul class="tag-list">
5555
<li><a href="Outer.Inner.html#%3Cinit%3E()"><code>Inner()</code></a></li>
5656
<li><a href="Outer.Inner.html#%3Cinit%3E(int)"><code>Inner(int)</code></a></li>
5757
<li><a href="Outer.Inner.NestedInner.html#%3Cinit%3E()"><code>NestedInner()</code></a></li>

‎test/langtools/jdk/javadoc/doclet/testGenericTypeLink/TestGenericTypeLink.java

+4-4
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ r interface in java.util" class="external-link">List</a>&lt;? extends <a href="h
7070
<dl class="notes">
7171
<dt>See Also:</dt>
7272
<dd>
73-
<ul class="see-list-long">
73+
<ul class="tag-list-long">
7474
<li><code><a href="http://example.com/docs/api/java.base/java/util/Map.html" title="\
7575
class or interface in java.util" class="external-link">Map</a>&lt;<a href="http://ex\
7676
ample.com/docs/api/java.base/java/lang/String.html" title="class or interface in jav\
@@ -106,7 +106,7 @@ interface in java.util" class="external-link">link to generic type with label</a
106106
<dl class="notes">
107107
<dt>See Also:</dt>
108108
<dd>
109-
<ul class="see-list-long">
109+
<ul class="tag-list-long">
110110
<li><code><a href="A.html" title="class in pkg1">A</a>&lt;<a href="http://example.c\
111111
om/docs/api/java.base/java/lang/String.html" title="class or interface in java.lang\
112112
" class="external-link">String</a>,<wbr><a href="A.SomeException.html" title="class\
@@ -123,7 +123,7 @@ s or interface in java.util" class="external-link"><code>Link to generic type wi
123123
<dl class="notes">
124124
<dt>See Also:</dt>
125125
<dd>
126-
<ul class="see-list-long">
126+
<ul class="tag-list-long">
127127
<li><code><a href="A.html" title="class in pkg1">A</a>&lt;<a href="http://exampl\
128128
e.com/docs/api/java.base/java/lang/String.html" title="class or interface in jav\
129129
a.lang" class="external-link">String</a>,<wbr><a href="http://example.com/docs/a\
@@ -189,7 +189,7 @@ public void testInvalidLinks() {
189189
<dl class="notes">
190190
<dt>See Also:</dt>
191191
<dd>
192-
<ul class="see-list-long">
192+
<ul class="tag-list-long">
193193
<li>
194194
<details class="invalid-tag">
195195
<summary>invalid @see</summary>

‎test/langtools/jdk/javadoc/doclet/testHref/TestHref.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ public void test() {
6969
"""
7070
See Also:</dt>
7171
<dd>
72-
<ul class="see-list-long">
72+
<ul class="tag-list-long">
7373
<li><a href="C1.html#method(int,int,java.util.ArrayList)">"""
7474
);
7575

‎test/langtools/jdk/javadoc/doclet/testHtmlDefinitionListTag/TestHtmlDefinitionListTag.java

+11-11
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,7 @@ void checkCommentDeprecated(boolean expectFound) {
160160
<dd>JDK1.0</dd>
161161
<dt>See Also:</dt>
162162
<dd>
163-
<ul class="see-list">
163+
<ul class="tag-list">
164164
<li><a href="C2.html" title="class in pkg1"><code>C2</code></a></li>
165165
<li><a href="../serialized-form.html#pkg1.C1">Serialized Form</a></li>
166166
</ul>
@@ -172,7 +172,7 @@ void checkCommentDeprecated(boolean expectFound) {
172172
<dd>1.4</dd>
173173
<dt>See Also:</dt>
174174
<dd>
175-
<ul class="see-list">
175+
<ul class="tag-list">
176176
<li><a href="#setUndecorated(boolean)"><code>setUndecorated(boolean)</code></a></li>
177177
</ul>
178178
</dd>
@@ -197,7 +197,7 @@ void checkCommentDeprecated(boolean expectFound) {
197197
<dd>1.4</dd>
198198
<dt>See Also:</dt>
199199
<dd>
200-
<ul class="see-list">
200+
<ul class="tag-list">
201201
<li><a href="#readObject()"><code>readObject()</code></a></li>
202202
</ul>
203203
</dd>
@@ -208,7 +208,7 @@ void checkCommentDeprecated(boolean expectFound) {
208208
<dd><code>java.io.IOException</code></dd>
209209
<dt>See Also:</dt>
210210
<dd>
211-
<ul class="see-list">
211+
<ul class="tag-list">
212212
<li><a href="#setUndecorated(boolean)"><code>setUndecorated(boolean)</code></a></li>
213213
</ul>
214214
</dd>
@@ -230,7 +230,7 @@ void checkCommentDeprecated(boolean expectFound) {
230230
<dd><code>java.io.IOException</code></dd>
231231
<dt>See Also:</dt>
232232
<dd>
233-
<ul class="see-list">
233+
<ul class="tag-list">
234234
<li><a href="pkg1/C1.html#setUndecorated(boolean)"><code>C1.setUndecorated(boolean)</code></a></li>
235235
</ul>
236236
</dd>
@@ -246,7 +246,7 @@ void checkCommentDeprecated(boolean expectFound) {
246246
<dd>1.4</dd>
247247
<dt>See Also:</dt>
248248
<dd>
249-
<ul class="see-list">
249+
<ul class="tag-list">
250250
<li><a href="pkg1/C1.html#setUndecorated(boolean)"><code>C1.setUndecorated(boolean)</code></a></li>
251251
</ul>
252252
</dd>
@@ -288,7 +288,7 @@ void checkNoDeprecated() {
288288
<dd>JDK1.0</dd>
289289
<dt>See Also:</dt>
290290
<dd>
291-
<ul class="see-list">
291+
<ul class="tag-list">
292292
<li><a href="C2.html" title="class in pkg1"><code>C2</code></a></li>
293293
<li><a href="../serialized-form.html#pkg1.C1">Serialized Form</a></li>
294294
</ul>
@@ -316,7 +316,7 @@ void checkNoDeprecated() {
316316
<dd>1.4</dd>
317317
<dt>See Also:</dt>
318318
<dd>
319-
<ul class="see-list">
319+
<ul class="tag-list">
320320
<li><a href="#readObject()"><code>readObject()</code></a></li>
321321
</ul>
322322
</dd>
@@ -327,7 +327,7 @@ void checkNoDeprecated() {
327327
<dd><code>java.io.IOException</code></dd>
328328
<dt>See Also:</dt>
329329
<dd>
330-
<ul class="see-list">
330+
<ul class="tag-list">
331331
<li><a href="#setUndecorated(boolean)"><code>setUndecorated(boolean)</code></a></li>
332332
</ul>
333333
</dd>
@@ -340,7 +340,7 @@ void checkNoDeprecated() {
340340
<dd><code>java.io.IOException</code></dd>
341341
<dt>See Also:</dt>
342342
<dd>
343-
<ul class="see-list">
343+
<ul class="tag-list">
344344
<li><a href="pkg1/C1.html#setUndecorated(boolean)"><code>C1.setUndecorated(boolean)</code></a></li>
345345
</ul>
346346
</dd>
@@ -356,7 +356,7 @@ void checkNoDeprecated() {
356356
<dd>1.4</dd>
357357
<dt>See Also:</dt>
358358
<dd>
359-
<ul class="see-list">
359+
<ul class="tag-list">
360360
<li><a href="pkg1/C1.html#setUndecorated(boolean)"><code>C1.setUndecorated(boolean)</code></a></li>
361361
</ul>
362362
</dd>

‎test/langtools/jdk/javadoc/doclet/testJavaFX/TestJavaFX.java

+4-4
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ public void test1() {
6363
"""
6464
<dt>See Also:</dt>
6565
<dd>
66-
<ul class="see-list">
66+
<ul class="tag-list">
6767
<li><a href="#getRate()"><code>getRate()</code></a></li>
6868
<li><a href="#setRate(double)"><code>setRate(double)</code></a></li>
6969
</ul>
@@ -268,7 +268,7 @@ public void test2() {
268268
<dl class="notes">
269269
<dt>See Also:</dt>
270270
<dd>
271-
<ul class="see-list">
271+
<ul class="tag-list">
272272
<li><a href="#betaProperty()"><code>betaProperty()</code></a></li>
273273
</ul>
274274
</dd>
@@ -284,7 +284,7 @@ public void test2() {
284284
<dl class="notes">
285285
<dt>See Also:</dt>
286286
<dd>
287-
<ul class="see-list">
287+
<ul class="tag-list">
288288
<li><a href="#gammaProperty()"><code>gammaProperty()</code></a></li>
289289
</ul>
290290
</dd>
@@ -300,7 +300,7 @@ public void test2() {
300300
<dl class="notes">
301301
<dt>See Also:</dt>
302302
<dd>
303-
<ul class="see-list">
303+
<ul class="tag-list">
304304
<li><a href="#deltaProperty()"><code>deltaProperty()</code></a></li>
305305
</ul>
306306
</dd>

‎test/langtools/jdk/javadoc/doclet/testJavaFX/TestJavaFXCombo.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -329,7 +329,7 @@ String getSee(Kind pk, Kind gk, Kind sk) {
329329
return sb.isEmpty() ? "" : """
330330
<dt>See Also:</dt>
331331
<dd>
332-
<ul class="see-list">
332+
<ul class="tag-list">
333333
""" + sb + """
334334
</ul>
335335
</dd>""";

‎test/langtools/jdk/javadoc/doclet/testJavaFX/TestJavaFXMissingPropComments.java

+2-2
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ <dd>The value property (property method comment).</dd>
100100
<dd>the value of the <code>value</code> property</dd>
101101
<dt>See Also:</dt>
102102
<dd>
103-
<ul class="see-list">
103+
<ul class="tag-list">
104104
<li><a href="#valueProperty()"><code>valueProperty()</code></a></li>
105105
</ul>
106106
</dd>
@@ -164,7 +164,7 @@ <dd>The value property (field comment).</dd>
164164
<dd>the value of the <code>value</code> property</dd>
165165
<dt>See Also:</dt>
166166
<dd>
167-
<ul class="see-list">
167+
<ul class="tag-list">
168168
<li><a href="#valueProperty()"><code>valueProperty()</code></a></li>
169169
</ul>
170170
</dd>

‎test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOption.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ as the parent class loader.</div>""",
102102
"<code>createTempFile(prefix,&nbsp;suffix,&nbsp;null)</code>",
103103
"""
104104
<dd>
105-
<ul class="see-list-long">
105+
<ul class="tag-list-long">
106106
<li><a href="http://www.ietf.org/rfc/rfc2279.txt"><i>RFC&nbsp;2279: UTF-8, a
107107
transformation format of ISO 10646</i></a></li>
108108
<li><a href="http://www.ietf.org/rfc/rfc2373.txt"><i>RFC&nbsp;2373: IPv6 Addressing

‎test/langtools/jdk/javadoc/doclet/testModules/TestModules.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -629,7 +629,7 @@ void checkModuleTags() {
629629
"""
630630
<dt>See Also:</dt>
631631
<dd>
632-
<ul class="see-list">
632+
<ul class="tag-list">
633633
<li>"Test see tag"</li>
634634
<li><a href="testpkgmdltags/TestClassInModuleTags.html" title="class in testpkgmdlta\
635635
gs"><code>TestClassInModuleTags</code></a></li>

‎test/langtools/jdk/javadoc/doclet/testNewLanguageFeatures/TestNewLanguageFeatures.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ void checkTypeParameters() {
123123
<dl class="notes">
124124
<dt>See Also:</dt>
125125
<dd>
126-
<ul class="see-list">
126+
<ul class="tag-list">
127127
<li><a href="TypeParameters.html" title="class in pkg"><code>TypeParameters</code></a></li>
128128
</ul>
129129
</dd>

0 commit comments

Comments
 (0)
Please sign in to comment.