Skip to content

Commit d2b5350

Browse files
hnshns
committed
8263507: Improve structure of package summary pages
Reviewed-by: jjg
1 parent a65021e commit d2b5350

40 files changed

+704
-852
lines changed

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

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -115,13 +115,14 @@ protected void addContents(Content content) {
115115
.setHeader(new TableHeader(contents.classLabel, contents.descriptionLabel))
116116
.setColumnStyles(HtmlStyle.colFirst, HtmlStyle.colLast)
117117
.setId(HtmlIds.ALL_CLASSES_TABLE)
118-
.setDefaultTab(resources.getText("doclet.All_Classes"))
119-
.addTab(contents.interfaceSummary, utils::isInterface)
120-
.addTab(contents.classSummary, e -> utils.isOrdinaryClass((TypeElement)e))
121-
.addTab(contents.enumSummary, utils::isEnum)
122-
.addTab(contents.exceptionSummary, e -> utils.isException((TypeElement)e))
123-
.addTab(contents.errorSummary, e -> utils.isError((TypeElement)e))
124-
.addTab(contents.annotationTypeSummary, utils::isAnnotationType);
118+
.setDefaultTab(contents.allClassesAndInterfacesLabel.toString())
119+
.addTab(contents.interfaces.toString(), utils::isInterface)
120+
.addTab(contents.classes.toString(), e -> utils.isOrdinaryClass((TypeElement)e))
121+
.addTab(contents.enums.toString(), utils::isEnum)
122+
.addTab(contents.records.toString(), e -> utils.isRecord((TypeElement)e))
123+
.addTab(contents.exceptions.toString(), e -> utils.isException((TypeElement)e))
124+
.addTab(contents.errors.toString(), e -> utils.isError((TypeElement)e))
125+
.addTab(contents.annotationTypes.toString(), utils::isAnnotationType);
125126
for (Character unicode : indexBuilder.getFirstCharacters()) {
126127
for (IndexItem indexItem : indexBuilder.getItems(unicode)) {
127128
TypeElement typeElement = (TypeElement) indexItem.getElement();

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,7 @@ protected void buildAllPackagesFile() throws DocFileIOException {
9595
*/
9696
protected void addPackages(Content content) {
9797
Table table = new Table(HtmlStyle.summaryTable)
98-
.setCaption(Text.of(contents.packageSummary))
98+
.setCaption(Text.of(contents.packageSummaryLabel.toString()))
9999
.setHeader(new TableHeader(contents.packageLabel, contents.descriptionLabel))
100100
.setColumnStyles(HtmlStyle.colFirst, HtmlStyle.colLast);
101101
for (PackageElement pkg : configuration.packages) {

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

Lines changed: 13 additions & 1 deletion
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.Collection;
2930
import java.util.List;
3031
import java.util.Set;
@@ -55,6 +56,7 @@
5556
import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
5657
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
5758
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
59+
import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable;
5860

5961
/**
6062
* Generate the Class Information Page.
@@ -150,7 +152,17 @@ protected Navigation getNavBar(PageMode pageMode, Element element) {
150152
contents.moduleLabel);
151153
return super.getNavBar(pageMode, element)
152154
.setNavLinkModule(linkContent)
153-
.setMemberSummaryBuilder(configuration.getBuilderFactory().getMemberSummaryBuilder(this));
155+
.setSubNavLinks(() -> {
156+
List<Content> list = new ArrayList<>();
157+
VisibleMemberTable vmt = configuration.getVisibleMemberTable(typeElement);
158+
Set<VisibleMemberTable.Kind> summarySet =
159+
VisibleMemberTable.Kind.forSummariesOf(element.getKind());
160+
for (VisibleMemberTable.Kind kind : summarySet) {
161+
list.add(links.createLink(HtmlIds.forMemberSummary(kind),
162+
contents.getNavLinkLabelContent(kind), vmt.hasVisibleMembers(kind)));
163+
}
164+
return list;
165+
});
154166
}
155167

156168
@Override

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

Lines changed: 17 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,6 @@
3636
import jdk.javadoc.internal.doclets.formats.html.markup.Text;
3737
import jdk.javadoc.internal.doclets.toolkit.Content;
3838
import jdk.javadoc.internal.doclets.toolkit.Resources;
39-
import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants;
4039
import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable;
4140

4241

@@ -53,6 +52,7 @@
5352
public class Contents {
5453

5554
public final Content allClassesLabel;
55+
public final Content allClassesAndInterfacesLabel;
5656
public final Content allImplementedInterfacesLabel;
5757
public final Content allModulesLabel;
5858
public final Content allPackagesLabel;
@@ -128,13 +128,14 @@ public class Contents {
128128
public final Content navAnnotationTypeMember;
129129
public final Content navAnnotationTypeOptionalMember;
130130
public final Content navAnnotationTypeRequiredMember;
131+
public final Content navClassesAndInterfaces;
131132
public final Content navConstructor;
133+
public final Content navDescription;
132134
public final Content navEnum;
133135
public final Content navField;
134136
public final Content navHelpNavigation;
135137
public final Content navHelpPages;
136138
public final Content navMethod;
137-
public final Content navModuleDescription;
138139
public final Content navModules;
139140
public final Content navNested;
140141
public final Content navPackages;
@@ -150,6 +151,8 @@ public class Contents {
150151
public final Content packageLabel;
151152
public final Content package_;
152153
public final Content packagesLabel;
154+
public final Content packageSubNavLabel;
155+
public final Content packageSummaryLabel;
153156
public final Content parameters;
154157
public final Content previewAPI;
155158
public final Content previewLabel;
@@ -159,7 +162,7 @@ public class Contents {
159162
public final Content propertyLabel;
160163
public final Content propertyDetailsLabel;
161164
public final Content propertySummaryLabel;
162-
public final Content record;
165+
public final Content records;
163166
public final Content recordComponents;
164167
public final Content referencedIn;
165168
public final Content relatedPackages;
@@ -182,15 +185,6 @@ public class Contents {
182185

183186
private final EnumMap<VisibleMemberTable.Kind, Content> navLinkLabels;
184187

185-
public final String annotationTypeSummary;
186-
public final String classSummary;
187-
public final String enumSummary;
188-
public final String errorSummary;
189-
public final String exceptionSummary;
190-
public final String interfaceSummary;
191-
public final String packageSummary;
192-
public final String recordSummary;
193-
194188
private final Resources resources;
195189

196190
/**
@@ -203,6 +197,7 @@ public class Contents {
203197
this.resources = configuration.getDocResources();
204198

205199
allClassesLabel = getNonBreakResource("doclet.All_Classes");
200+
this.allClassesAndInterfacesLabel = getContent("doclet.All_Classes_And_Interfaces");
206201
allImplementedInterfacesLabel = getContent("doclet.All_Implemented_Interfaces");
207202
allModulesLabel = getNonBreakResource("doclet.All_Modules");
208203
allPackagesLabel = getNonBreakResource("doclet.All_Packages");
@@ -278,13 +273,14 @@ public class Contents {
278273
navAnnotationTypeMember = getContent("doclet.navAnnotationTypeMember");
279274
navAnnotationTypeOptionalMember = getContent("doclet.navAnnotationTypeOptionalMember");
280275
navAnnotationTypeRequiredMember = getContent("doclet.navAnnotationTypeRequiredMember");
276+
navClassesAndInterfaces = getContent("doclet.navClassesAndInterfaces");
281277
navConstructor = getContent("doclet.navConstructor");
282278
navEnum = getContent("doclet.navEnum");
283279
navField = getContent("doclet.navField");
284280
navHelpNavigation = getContent("doclet.navNavigation");
285281
navHelpPages = getContent("doclet.navPages");
286282
navMethod = getContent("doclet.navMethod");
287-
navModuleDescription = getContent("doclet.navModuleDescription");
283+
navDescription = getContent("doclet.navDescription");
288284
navModules = getContent("doclet.navModules");
289285
navNested = getContent("doclet.navNested");
290286
navPackages = getContent("doclet.navPackages");
@@ -300,6 +296,8 @@ public class Contents {
300296
packageLabel = getContent("doclet.Package");
301297
package_ = getContent("doclet.package");
302298
packagesLabel = getContent("doclet.Packages");
299+
packageSubNavLabel = getContent("doclet.Package_Sub_Nav");
300+
this.packageSummaryLabel = getContent("doclet.Package_Summary");
303301
parameters = getContent("doclet.Parameters");
304302
previewAPI = getContent("doclet.Preview_API");
305303
previewLabel = getContent("doclet.Preview_Label");
@@ -309,7 +307,7 @@ public class Contents {
309307
propertyLabel = getContent("doclet.Property");
310308
propertyDetailsLabel = getContent("doclet.Property_Detail");
311309
propertySummaryLabel = getContent("doclet.Property_Summary");
312-
record = getContent("doclet.RecordClass");
310+
records = getContent("doclet.RecordClasses");
313311
recordComponents = getContent("doclet.RecordComponents");
314312
referencedIn = getContent("doclet.ReferencedIn");
315313
relatedPackages = getContent("doclet.Related_Packages");
@@ -331,20 +329,15 @@ record = getContent("doclet.RecordClass");
331329
valueLabel = getContent("doclet.Value");
332330

333331
navLinkLabels = new EnumMap<>(VisibleMemberTable.Kind.class);
334-
navLinkLabels.put(VisibleMemberTable.Kind.INNER_CLASSES, getContent("doclet.navNested"));
332+
navLinkLabels.put(VisibleMemberTable.Kind.NESTED_CLASSES, getContent("doclet.navNested"));
335333
navLinkLabels.put(VisibleMemberTable.Kind.ENUM_CONSTANTS, getContent("doclet.navEnum"));
336334
navLinkLabels.put(VisibleMemberTable.Kind.FIELDS, getContent("doclet.navField"));
337335
navLinkLabels.put(VisibleMemberTable.Kind.CONSTRUCTORS, getContent("doclet.navConstructor"));
338336
navLinkLabels.put(VisibleMemberTable.Kind.METHODS, getContent("doclet.navMethod"));
339-
340-
this.annotationTypeSummary = resources.getText("doclet.Annotation_Types_Summary");
341-
this.classSummary = resources.getText("doclet.Class_Summary");
342-
this.enumSummary = resources.getText("doclet.Enum_Summary");
343-
this.errorSummary = resources.getText("doclet.Error_Summary");
344-
this.exceptionSummary = resources.getText("doclet.Exception_Summary");
345-
this.interfaceSummary = resources.getText("doclet.Interface_Summary");
346-
this.packageSummary = resources.getText("doclet.Package_Summary");
347-
this.recordSummary = resources.getText("doclet.Record_Class_Summary");
337+
navLinkLabels.put(VisibleMemberTable.Kind.ANNOTATION_TYPE_MEMBER_OPTIONAL,
338+
getContent("doclet.navAnnotationTypeOptionalMember"));
339+
navLinkLabels.put(VisibleMemberTable.Kind.ANNOTATION_TYPE_MEMBER_REQUIRED,
340+
getContent("doclet.navAnnotationTypeRequiredMember"));
348341
}
349342

350343
/**

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@
2626
package jdk.javadoc.internal.doclets.formats.html;
2727

2828
import java.util.List;
29+
import javax.lang.model.element.Element;
2930

3031
import jdk.javadoc.internal.doclets.formats.html.markup.BodyContents;
3132
import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
@@ -143,6 +144,15 @@ protected void addHelpFileContents(Content contentTree) {
143144
getContent("doclet.help.footnote")));
144145
}
145146

147+
@Override
148+
protected Navigation getNavBar(PageMode pageMode, Element element) {
149+
return super.getNavBar(pageMode, element)
150+
.setSubNavLinks(() -> List.of(
151+
links.createLink(HtmlIds.HELP_NAVIGATION, contents.navHelpNavigation),
152+
links.createLink(HtmlIds.HELP_PAGES, contents.navHelpPages))
153+
);
154+
}
155+
146156
/**
147157
* Creates the navigation help, adding an entry into the main table-of-contents.
148158
*

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

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -139,8 +139,6 @@ protected Function<String, String> getResourceKeyMapper(DocletEnvironment docEnv
139139
{ "doclet.help.annotation_type.description", "doclet.help.annotation_interface.description" },
140140

141141
// in doclets.properties
142-
{ "doclet.Annotation_Types_Summary", "doclet.Annotation_Interfaces_Summary" },
143-
{ "doclet.Enum_Summary", "doclet.Enum_Class_Summary" },
144142
{ "doclet.Enums", "doclet.EnumClasses" },
145143
{ "doclet.AnnotationType", "doclet.AnnotationInterface" },
146144
{ "doclet.AnnotationTypes", "doclet.AnnotationInterfaces" },

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@
4242
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlId;
4343
import jdk.javadoc.internal.doclets.toolkit.util.SummaryAPIListBuilder;
4444
import jdk.javadoc.internal.doclets.toolkit.util.Utils;
45+
import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable;
4546

4647
/**
4748
* Centralized constants and factory methods for HTML ids.
@@ -72,6 +73,7 @@ public class HtmlIds {
7273
static final HtmlId ANNOTATION_TYPE_OPTIONAL_ELEMENT_SUMMARY = HtmlId.of("annotation-interface-optional-element-summary");
7374
static final HtmlId ANNOTATION_TYPE_REQUIRED_ELEMENT_SUMMARY = HtmlId.of("annotation-interface-required-element-summary");
7475
static final HtmlId CLASS_DESCRIPTION = HtmlId.of("class-description");
76+
static final HtmlId CLASS_SUMMARY = HtmlId.of("class-summary");
7577
static final HtmlId CONSTRUCTOR_DETAIL = HtmlId.of("constructor-detail");
7678
static final HtmlId CONSTRUCTOR_SUMMARY = HtmlId.of("constructor-summary");
7779
static final HtmlId ENUM_CONSTANT_DETAIL = HtmlId.of("enum-constant-detail");
@@ -95,6 +97,7 @@ public class HtmlIds {
9597
static final HtmlId PACKAGE_SUMMARY_TABLE = HtmlId.of("package-summary-table");
9698
static final HtmlId PROPERTY_DETAIL = HtmlId.of("property-detail");
9799
static final HtmlId PROPERTY_SUMMARY = HtmlId.of("property-summary");
100+
static final HtmlId RELATED_PACKAGE_SUMMARY = HtmlId.of("related-package-summary");
98101
static final HtmlId RESET_BUTTON = HtmlId.of("reset-button");
99102
static final HtmlId SEARCH_INPUT = HtmlId.of("search-input");
100103
static final HtmlId SERVICES = HtmlId.of("services-summary");
@@ -424,6 +427,26 @@ static HtmlId forSummaryKind(SummaryAPIListBuilder.SummaryElementKind kind) {
424427
});
425428
}
426429

430+
/**
431+
* Returns an id for the member summary table of the given {@code kind} in a class page.
432+
*
433+
* @param kind the kind of member
434+
*
435+
* @return the id
436+
*/
437+
static HtmlId forMemberSummary(VisibleMemberTable.Kind kind) {
438+
return switch (kind) {
439+
case NESTED_CLASSES -> NESTED_CLASS_SUMMARY;
440+
case ENUM_CONSTANTS -> ENUM_CONSTANT_SUMMARY;
441+
case FIELDS -> FIELD_SUMMARY;
442+
case CONSTRUCTORS -> CONSTRUCTOR_SUMMARY;
443+
case METHODS -> METHOD_SUMMARY;
444+
case ANNOTATION_TYPE_MEMBER_OPTIONAL -> ANNOTATION_TYPE_OPTIONAL_ELEMENT_SUMMARY;
445+
case ANNOTATION_TYPE_MEMBER_REQUIRED -> ANNOTATION_TYPE_REQUIRED_ELEMENT_SUMMARY;
446+
case PROPERTIES -> PROPERTY_SUMMARY;
447+
};
448+
}
449+
427450
/**
428451
* Returns an id for a "tab" in a table.
429452
*

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

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -197,11 +197,16 @@ public Content getModuleHeader(String heading) {
197197
@Override
198198
protected Navigation getNavBar(PageMode pageMode, Element element) {
199199
return super.getNavBar(pageMode, element)
200-
.setDisplaySummaryModuleDescLink(!utils.getFullBody(mdle).isEmpty() && !options.noComment())
201-
.setDisplaySummaryModulesLink(display(requires) || display(indirectModules))
202-
.setDisplaySummaryPackagesLink(display(packages) || display(indirectPackages)
203-
|| display(indirectOpenPackages))
204-
.setDisplaySummaryServicesLink(displayServices(uses, usesTrees) || displayServices(provides.keySet(), providesTrees));
200+
.setSubNavLinks(() -> List.of(
201+
links.createLink(HtmlIds.MODULE_DESCRIPTION, contents.navDescription,
202+
!utils.getFullBody(mdle).isEmpty() && !options.noComment()),
203+
links.createLink(HtmlIds.MODULES, contents.navModules,
204+
display(requires) || display(indirectModules)),
205+
links.createLink(HtmlIds.PACKAGES, contents.navPackages,
206+
display(packages) || display(indirectPackages) || display(indirectOpenPackages)),
207+
links.createLink(HtmlIds.SERVICES, contents.navServices,
208+
displayServices(uses, usesTrees) || displayServices(provides.keySet(), providesTrees))
209+
));
205210
}
206211

207212
/**

0 commit comments

Comments
 (0)