Skip to content

Commit f71d515

Browse files
hnshns
committed
8345777: Improve sections for inherited members
Reviewed-by: prappo
1 parent b8bb51e commit f71d515

File tree

16 files changed

+153
-127
lines changed

16 files changed

+153
-127
lines changed

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

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,6 @@
3131
import javax.lang.model.element.ElementKind;
3232
import javax.lang.model.element.ExecutableElement;
3333
import javax.lang.model.element.TypeElement;
34-
import javax.lang.model.element.TypeParameterElement;
3534
import javax.lang.model.element.VariableElement;
3635
import javax.lang.model.type.DeclaredType;
3736
import javax.lang.model.type.ExecutableType;
@@ -43,7 +42,6 @@
4342
import jdk.javadoc.internal.html.Content;
4443
import jdk.javadoc.internal.html.ContentBuilder;
4544
import jdk.javadoc.internal.html.Entity;
46-
import jdk.javadoc.internal.html.HtmlTag;
4745
import jdk.javadoc.internal.html.HtmlTree;
4846
import jdk.javadoc.internal.html.Text;
4947

@@ -94,7 +92,6 @@ protected AbstractExecutableMemberWriter(SubWriterHolderWriter writer) {
9492
*/
9593
protected Content getTypeParameters(ExecutableElement member) {
9694
HtmlLinkInfo linkInfo = new HtmlLinkInfo(configuration, LINK_TYPE_PARAMS_AND_BOUNDS, member)
97-
.addLineBreaksInTypeParameters(true)
9895
.showTypeParameterAnnotations(true);
9996
return writer.getTypeParameterLinks(linkInfo);
10097
}
@@ -129,7 +126,15 @@ protected void addSummaryLink(HtmlLinkInfo.Kind context, TypeElement te, Element
129126

130127
@Override
131128
protected void addInheritedSummaryLink(TypeElement te, Element member, Content target) {
132-
target.add(writer.getDocLink(PLAIN, te, member, name(member)));
129+
// Use method name as link label, but add signature as title attribute
130+
String name = name(member);
131+
ExecutableElement ee = (ExecutableElement) member;
132+
String title = name + utils.makeSignature(ee, typeElement, false, true);
133+
target.add(writer.getLink(new HtmlLinkInfo(configuration, PLAIN, te)
134+
.label(name)
135+
.fragment(htmlIds.forMember(ee).getFirst().name())
136+
.targetMember(member)
137+
.title(title)));
133138
}
134139

135140
/**

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

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,8 @@
5252
import jdk.javadoc.internal.html.Content;
5353
import jdk.javadoc.internal.html.ContentBuilder;
5454
import jdk.javadoc.internal.html.Entity;
55-
import jdk.javadoc.internal.html.HtmlTag;
5655
import jdk.javadoc.internal.html.HtmlTree;
56+
import jdk.javadoc.internal.html.Text;
5757

5858
import static jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable.Kind.ANNOTATION_TYPE_MEMBER;
5959
import static jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable.Kind.ANNOTATION_TYPE_MEMBER_OPTIONAL;
@@ -717,4 +717,19 @@ protected Content getMemberListItem(Content memberContent) {
717717
return writer.getMemberListItem(memberContent);
718718
}
719719

720+
/**
721+
* {@return a link to the member summary section of class or interface {@code element} indicated
722+
* by {@code summaryKind} with the simple type name as link label, or the fully qualified type name
723+
* if the class or interface is not linkable}
724+
*/
725+
protected Content getMemberSummaryLinkOrFQN(TypeElement element, VisibleMemberTable.Kind summaryKind) {
726+
if (utils.isLinkable(element)) {
727+
return writer.getLink((new HtmlLinkInfo(configuration, HtmlLinkInfo.Kind.PLAIN, element)
728+
.label(utils.getSimpleName(element))
729+
.fragment(HtmlIds.forMemberSummary(summaryKind).name())));
730+
} else {
731+
return Text.of(utils.getFullyQualifiedName(element));
732+
}
733+
}
734+
720735
}

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

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -230,8 +230,7 @@ protected Table<Element> createSummaryTable() {
230230

231231
@Override
232232
public void addInheritedSummaryLabel(TypeElement typeElement, Content content) {
233-
Content classLink = writer.getPreQualifiedClassLink(
234-
HtmlLinkInfo.Kind.PLAIN, typeElement);
233+
Content classLink = getMemberSummaryLinkOrFQN(typeElement, VisibleMemberTable.Kind.FIELDS);
235234
Content label;
236235
if (options.summarizeOverriddenMethods()) {
237236
label = Text.of(utils.isClass(typeElement)

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

Lines changed: 15 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -236,20 +236,16 @@ public Content visitDeclared(DeclaredType type, HtmlLinkInfo linkInfo) {
236236
protected Content getClassLink(HtmlLinkInfo linkInfo) {
237237
BaseConfiguration configuration = m_writer.configuration;
238238
TypeElement typeElement = linkInfo.getTypeElement();
239-
// Create a tool tip if we are linking to a class or interface. Don't
240-
// create one if we are linking to a member.
241-
String title = "";
242-
String fragment = linkInfo.getFragment();
243-
boolean hasFragment = fragment != null && !fragment.isEmpty();
244-
if (!hasFragment) {
245-
boolean isTypeLink = linkInfo.getType() != null &&
246-
utils.isTypeVariable(utils.getComponentType(linkInfo.getType()));
247-
title = getClassToolTip(typeElement, isTypeLink);
248-
if (isTypeLink) {
249-
linkInfo.fragment(m_writer.configuration.htmlIds.forTypeParam(
250-
utils.getTypeName(utils.getComponentType(linkInfo.getType()), false),
251-
typeElement).name());
252-
}
239+
// Create a tool tip if we are linking to a class or interface, or one of
240+
// its summary sections. Don't create one if we are linking to a member.
241+
boolean isPageOrSummaryLink = linkInfo.isPageOrSummaryLink();
242+
TypeMirror type = linkInfo.getType();
243+
if (type != null && utils.isTypeVariable(utils.getComponentType(type))) {
244+
linkInfo.fragment(m_writer.configuration.htmlIds.forTypeParam(
245+
utils.getTypeName(utils.getComponentType(type), false), typeElement).name())
246+
.title(getClassToolTip(typeElement, true));
247+
} else if (isPageOrSummaryLink) {
248+
linkInfo.title(getClassToolTip(typeElement, false));
253249
}
254250
Content label = linkInfo.getClassLinkLabel(configuration);
255251
if (linkInfo.getContext() == HtmlLinkInfo.Kind.SHOW_TYPE_PARAMS_IN_LABEL) {
@@ -261,7 +257,7 @@ protected Content getClassLink(HtmlLinkInfo linkInfo) {
261257
Element previewTarget;
262258
ExecutableElement restrictedTarget;
263259
boolean showPreview = !linkInfo.isSkipPreview();
264-
if (!hasFragment && showPreview) {
260+
if (isPageOrSummaryLink && showPreview) {
265261
flags = utils.elementFlags(typeElement);
266262
previewTarget = typeElement;
267263
restrictedTarget = null;
@@ -301,7 +297,7 @@ protected Content getClassLink(HtmlLinkInfo linkInfo) {
301297
if (linkInfo.linkToSelf() || typeElement != m_writer.getCurrentPageElement()) {
302298
link.add(m_writer.links.createLink(
303299
fileName.fragment(linkInfo.getFragment()),
304-
label, linkInfo.getStyle(), title));
300+
label, linkInfo.getStyle(), linkInfo.getTitle()));
305301
addSuperscript(link, flags, fileName, null, previewTarget, restrictedTarget);
306302
return link;
307303
}
@@ -461,11 +457,12 @@ private HtmlLinkInfo getBoundsLinkInfo(HtmlLinkInfo linkInfo, TypeMirror bound)
461457
* Given a class, return the appropriate tool tip.
462458
*
463459
* @param typeElement the class to get the tool tip for.
460+
* @param isTypeParamLink true if link target is a type parameter
464461
* @return the tool tip for the appropriate class.
465462
*/
466-
private String getClassToolTip(TypeElement typeElement, boolean isTypeLink) {
463+
private String getClassToolTip(TypeElement typeElement, boolean isTypeParamLink) {
467464
Resources resources = m_writer.configuration.getDocResources();
468-
if (isTypeLink) {
465+
if (isTypeParamLink) {
469466
return resources.getText("doclet.Href_Type_Param_Title",
470467
utils.getSimpleName(typeElement));
471468
} else if (utils.isPlainInterface(typeElement)){

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

Lines changed: 23 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,6 @@
3131
import javax.lang.model.type.DeclaredType;
3232
import javax.lang.model.type.TypeMirror;
3333

34-
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyles;
3534
import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
3635
import jdk.javadoc.internal.doclets.toolkit.util.Utils;
3736
import jdk.javadoc.internal.html.Content;
@@ -110,6 +109,9 @@ public enum Kind {
110109
// The label for the link.
111110
private Content label;
112111

112+
// The title attribute for the link
113+
private String title;
114+
113115
// True if we should print the type bounds for the type parameter.
114116
private boolean showTypeBounds = true;
115117

@@ -123,9 +125,6 @@ public enum Kind {
123125
// True iff the preview flags should be skipped for this link.
124126
private boolean skipPreview;
125127

126-
// True if type parameters should be separated by hard line breaks.
127-
private boolean addLineBreaksInTypeParameters = false;
128-
129128
// True if additional <wbr> tags should be added to type parameters
130129
private boolean addLineBreakOpportunitiesInTypeParameters = false;
131130

@@ -183,7 +182,6 @@ public HtmlLinkInfo forType(TypeMirror type) {
183182
linkInfo.showTypeBounds = showTypeBounds;
184183
linkInfo.linkTypeParameters = linkTypeParameters;
185184
linkInfo.linkToSelf = linkToSelf;
186-
linkInfo.addLineBreaksInTypeParameters = addLineBreaksInTypeParameters;
187185
linkInfo.showTypeParameterAnnotations = showTypeParameterAnnotations;
188186
linkInfo.skipPreview = skipPreview;
189187
return linkInfo;
@@ -264,6 +262,23 @@ public HtmlStyle getStyle() {
264262
return style;
265263
}
266264

265+
/**
266+
* Sets the title attribute for the link.
267+
* @param title the value of the title attribute
268+
* @return this object
269+
*/
270+
public HtmlLinkInfo title(String title) {
271+
this.title = title;
272+
return this;
273+
}
274+
275+
/**
276+
* {@return the value of the title attribute}
277+
*/
278+
public String getTitle() {
279+
return title;
280+
}
281+
267282
/**
268283
* Set whether or not this is a link to a varargs parameter.
269284
* @param varargs the new value
@@ -299,20 +314,10 @@ public String getFragment() {
299314
}
300315

301316
/**
302-
* Sets the addLineBreaksInTypeParameters flag for this link.
303-
* @param addLineBreaksInTypeParameters the new value
304-
* @return this object
305-
*/
306-
public HtmlLinkInfo addLineBreaksInTypeParameters(boolean addLineBreaksInTypeParameters) {
307-
this.addLineBreaksInTypeParameters = addLineBreaksInTypeParameters;
308-
return this;
309-
}
310-
311-
/**
312-
* {@return true if type parameters should be separated by line breaks}
317+
* {@return {@code true} if the link target is the top level page or one of its summary sections}
313318
*/
314-
public boolean addLineBreaksInTypeParameters() {
315-
return addLineBreaksInTypeParameters;
319+
public boolean isPageOrSummaryLink() {
320+
return fragment == null || fragment.isEmpty() || fragment.endsWith("-summary");
316321
}
317322

318323
/**
@@ -506,7 +511,6 @@ public String toString() {
506511
", showTypeBounds=" + showTypeBounds +
507512
", linkTypeParameters=" + linkTypeParameters +
508513
", linkToSelf=" + linkToSelf +
509-
", addLineBreaksInTypeParameters=" + addLineBreaksInTypeParameters +
510514
", showTypeParameterAnnotations=" + showTypeParameterAnnotations +
511515
", context=" + context +
512516
", fragment=" + fragment +

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

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -306,8 +306,7 @@ protected Table<Element> createSummaryTable() {
306306

307307
@Override
308308
public void addInheritedSummaryLabel(TypeElement typeElement, Content content) {
309-
Content classLink = writer.getPreQualifiedClassLink(
310-
HtmlLinkInfo.Kind.PLAIN, typeElement);
309+
Content classLink = getMemberSummaryLinkOrFQN(typeElement, VisibleMemberTable.Kind.METHODS);
311310
Content label;
312311
if (options.summarizeOverriddenMethods()) {
313312
label = Text.of(utils.isClass(typeElement)

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ protected Table<Element> createSummaryTable() {
105105

106106
@Override
107107
public void addInheritedSummaryLabel(TypeElement typeElement, Content content) {
108-
Content classLink = writer.getPreQualifiedClassLink(HtmlLinkInfo.Kind.PLAIN, typeElement);
108+
Content classLink = getMemberSummaryLinkOrFQN(typeElement, VisibleMemberTable.Kind.NESTED_CLASSES);
109109
Content label;
110110
if (options.summarizeOverriddenMethods()) {
111111
label = Text.of(utils.isPlainInterface(typeElement)
@@ -135,7 +135,7 @@ protected void addSummaryLink(HtmlLinkInfo.Kind context, TypeElement typeElement
135135
@Override
136136
protected void addInheritedSummaryLink(TypeElement typeElement, Element member, Content target) {
137137
target.add(
138-
writer.getLink(new HtmlLinkInfo(configuration, HtmlLinkInfo.Kind.LINK_TYPE_PARAMS_AND_BOUNDS,
138+
writer.getLink(new HtmlLinkInfo(configuration, HtmlLinkInfo.Kind.SHOW_TYPE_PARAMS,
139139
(TypeElement)member)));
140140
}
141141

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

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -259,8 +259,7 @@ protected Table<Element> createSummaryTable() {
259259

260260
@Override
261261
public void addInheritedSummaryLabel(TypeElement typeElement, Content content) {
262-
Content classLink = writer.getPreQualifiedClassLink(
263-
HtmlLinkInfo.Kind.PLAIN, typeElement);
262+
Content classLink = getMemberSummaryLinkOrFQN(typeElement, VisibleMemberTable.Kind.PROPERTIES);
264263
Content label;
265264
if (options.summarizeOverriddenMethods()) {
266265
label = Text.of(utils.isClass(typeElement)

‎test/langtools/jdk/javadoc/doclet/testHiddenTag/TestHiddenTag.java‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -70,10 +70,11 @@ public void test1() {
7070
"""
7171
<code><a href="A.html#visibleField">visibleField</a></code>""",
7272
"""
73-
<code><a href="A.html#visibleMethod()">visibleMethod</a></code>""",
73+
<code><a href="A.html#visibleMethod()" title="visibleMethod()">visibleMethod</a></code>""",
7474
"""
7575
<h3 id="nested-classes-inherited-from-class-pkg1.A">Nested classes/interfaces in\
76-
herited from class&nbsp;pkg1.<a href="A.html" title="class in pkg1">A</a></h3>
76+
herited from class&nbsp;<a href="A.html#nested-class-summary" title="class in pk\
77+
g1">A</a></h3>
7778
<code><a href="A.VisibleInner.html" title="class in pkg1">A.VisibleInner</a>, <a\
7879
href="A.VisibleInnerExtendsInvisibleInner.html" title="class in pkg1">A.Visible\
7980
InnerExtendsInvisibleInner</a></code></div>
@@ -92,7 +93,7 @@ public void test1() {
9293
"""
9394
<code><a href="A.html#visibleField">visibleField</a></code>""",
9495
"""
95-
<code><a href="A.html#visibleMethod()">visibleMethod</a></code>""");
96+
<code><a href="A.html#visibleMethod()" title="visibleMethod()">visibleMethod</a></code>""");
9697

9798
checkOutput("pkg1/A.VisibleInnerExtendsInvisibleInner.html", false,
9899
"invisibleField",
@@ -127,7 +128,7 @@ public void test1() {
127128
"""
128129
<a href="#visibleMethod(pkg1.InvisibleParent)" class="member-name-link">visibleMethod</a>""",
129130
"""
130-
<a href="Intf.html#visibleDefaultMethod()">visibleDefaultMethod</a>""",
131+
<a href="Intf.html#visibleDefaultMethod()" title="visibleDefaultMethod()">visibleDefaultMethod</a>""",
131132
// Invisible return or parameter types must not be linked
132133
"""
133134
<span class="return-type">pkg1.InvisibleParent</span>""",

‎test/langtools/jdk/javadoc/doclet/testInterface/TestInterface.java‎

Lines changed: 5 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -205,22 +205,13 @@ public void test2() {
205205
// Ensure the correct type parameters are displayed correctly
206206
"""
207207
<h3 id="nested-classes-inherited-from-class-pkg2.Spliterator">Nested classes/int\
208-
erfaces inherited from interface&nbsp;pkg2.<a href="Spliterator.html" title="int\
209-
erface in pkg2">Spliterator</a></h3>
208+
erfaces inherited from interface&nbsp;<a href="Spliterator.html#nested-class-sum\
209+
mary" title="interface in pkg2">Spliterator</a></h3>
210210
<code><a href="Spliterator.OfDouble.html" title="interface in pkg2">Spliterator.\
211211
OfDouble</a>, <a href="Spliterator.OfInt.html" title="interface in pkg2">Spliter\
212-
ator.OfInt</a>&lt;<a href="Spliterator.OfInt.html#type-param-Integer" title="type parameter in Spli\
213-
terator.OfInt">Integer</a>&gt;, <a href="Spliterator.OfPrimitive.html" title="in\
214-
terface in pkg2">Spliterator.OfPrimitive</a>&lt;<a href="Spliterator.OfPrimitive\
215-
.html#type-param-T" title="type parameter in Spliterator.OfPrimitive">T</a>, <a href="Spl\
216-
iterator.OfPrimitive.html#type-param-T_CONS" title="type parameter in Spliterator.OfPrimitive">T_C\
217-
ONS</a>, <a href="Spliterator.OfPrimitive.html#type-param-T_SPLITR" title="type parameter in Spl\
218-
iterator.OfPrimitive">T_SPLITR</a> extends <a href="Spliterator.OfPrimitive.html\
219-
" title="interface in pkg2">Spliterator.OfPrimitive</a>&lt;<a href="Spliterator.\
220-
OfPrimitive.html#type-param-T" title="type parameter in Spliterator.OfPrimitive">T</a>,<wbr><\
221-
a href="Spliterator.OfPrimitive.html#type-param-T_CONS" title="type parameter in Spliterator.OfPri\
222-
mitive">T_CONS</a>,<wbr><a href="Spliterator.OfPrimitive.html#type-param-T_SPLITR" title="type param\
223-
eter in Spliterator.OfPrimitive">T_SPLITR</a>&gt;&gt;</code>""");
212+
ator.OfInt</a>&lt;Integer&gt;, <a href="Spliterator.OfPrimitive.html" title="int\
213+
erface in pkg2">Spliterator.OfPrimitive</a>&lt;T,<wbr>T_CONS,<wbr>T_SPLITR&gt;</\
214+
code></div>""");
224215
checkOutput("pkg2/Spliterator.html", true,
225216
"""
226217
<div class="caption"><span>Nested Classes</span></div>

0 commit comments

Comments
 (0)