Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
8263507: Improve structure of package summary pages 
Reviewed-by: jjg
  • Loading branch information
@hns
hns committed May 7, 2021
1 parent a65021e commit d2b5350
Show file tree
Hide file tree
Showing 40 changed files with 704 additions and 852 deletions.
15 changes: 8 additions & 7 deletions ...avadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AllClassesIndexWriter.java
View file
Expand Up @@ -115,13 +115,14 @@ protected void addContents(Content content) {
.setHeader(new TableHeader(contents.classLabel, contents.descriptionLabel))
.setColumnStyles(HtmlStyle.colFirst, HtmlStyle.colLast)
.setId(HtmlIds.ALL_CLASSES_TABLE)
.setDefaultTab(resources.getText("doclet.All_Classes"))
.addTab(contents.interfaceSummary, utils::isInterface)
.addTab(contents.classSummary, e -> utils.isOrdinaryClass((TypeElement)e))
.addTab(contents.enumSummary, utils::isEnum)
.addTab(contents.exceptionSummary, e -> utils.isException((TypeElement)e))
.addTab(contents.errorSummary, e -> utils.isError((TypeElement)e))
.addTab(contents.annotationTypeSummary, utils::isAnnotationType);
.setDefaultTab(contents.allClassesAndInterfacesLabel.toString())
.addTab(contents.interfaces.toString(), utils::isInterface)
.addTab(contents.classes.toString(), e -> utils.isOrdinaryClass((TypeElement)e))
.addTab(contents.enums.toString(), utils::isEnum)
.addTab(contents.records.toString(), e -> utils.isRecord((TypeElement)e))
.addTab(contents.exceptions.toString(), e -> utils.isException((TypeElement)e))
.addTab(contents.errors.toString(), e -> utils.isError((TypeElement)e))
.addTab(contents.annotationTypes.toString(), utils::isAnnotationType);
for (Character unicode : indexBuilder.getFirstCharacters()) {
for (IndexItem indexItem : indexBuilder.getItems(unicode)) {
TypeElement typeElement = (TypeElement) indexItem.getElement();
Expand Down
2 changes: 1 addition & 1 deletion ...vadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AllPackagesIndexWriter.java
View file
Expand Up @@ -95,7 +95,7 @@ protected void buildAllPackagesFile() throws DocFileIOException {
*/
protected void addPackages(Content content) {
Table table = new Table(HtmlStyle.summaryTable)
.setCaption(Text.of(contents.packageSummary))
.setCaption(Text.of(contents.packageSummaryLabel.toString()))
.setHeader(new TableHeader(contents.packageLabel, contents.descriptionLabel))
.setColumnStyles(HtmlStyle.colFirst, HtmlStyle.colLast);
for (PackageElement pkg : configuration.packages) {
Expand Down
14 changes: 13 additions & 1 deletion src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java
View file
Expand Up @@ -25,6 +25,7 @@

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

import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
import java.util.Set;
Expand Down Expand Up @@ -55,6 +56,7 @@
import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable;

/**
* Generate the Class Information Page.
Expand Down Expand Up @@ -150,7 +152,17 @@ protected Navigation getNavBar(PageMode pageMode, Element element) {
contents.moduleLabel);
return super.getNavBar(pageMode, element)
.setNavLinkModule(linkContent)
.setMemberSummaryBuilder(configuration.getBuilderFactory().getMemberSummaryBuilder(this));
.setSubNavLinks(() -> {
List<Content> list = new ArrayList<>();
VisibleMemberTable vmt = configuration.getVisibleMemberTable(typeElement);
Set<VisibleMemberTable.Kind> summarySet =
VisibleMemberTable.Kind.forSummariesOf(element.getKind());
for (VisibleMemberTable.Kind kind : summarySet) {
list.add(links.createLink(HtmlIds.forMemberSummary(kind),
contents.getNavLinkLabelContent(kind), vmt.hasVisibleMembers(kind)));
}
return list;
});
}

@Override
Expand Down
41 changes: 17 additions & 24 deletions src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Contents.java
View file
Expand Up @@ -36,7 +36,6 @@
import jdk.javadoc.internal.doclets.formats.html.markup.Text;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.Resources;
import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants;
import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable;


Expand All @@ -53,6 +52,7 @@
public class Contents {

public final Content allClassesLabel;
public final Content allClassesAndInterfacesLabel;
public final Content allImplementedInterfacesLabel;
public final Content allModulesLabel;
public final Content allPackagesLabel;
Expand Down Expand Up @@ -128,13 +128,14 @@ public class Contents {
public final Content navAnnotationTypeMember;
public final Content navAnnotationTypeOptionalMember;
public final Content navAnnotationTypeRequiredMember;
public final Content navClassesAndInterfaces;
public final Content navConstructor;
public final Content navDescription;
public final Content navEnum;
public final Content navField;
public final Content navHelpNavigation;
public final Content navHelpPages;
public final Content navMethod;
public final Content navModuleDescription;
public final Content navModules;
public final Content navNested;
public final Content navPackages;
Expand All @@ -150,6 +151,8 @@ public class Contents {
public final Content packageLabel;
public final Content package_;
public final Content packagesLabel;
public final Content packageSubNavLabel;
public final Content packageSummaryLabel;
public final Content parameters;
public final Content previewAPI;
public final Content previewLabel;
Expand All @@ -159,7 +162,7 @@ public class Contents {
public final Content propertyLabel;
public final Content propertyDetailsLabel;
public final Content propertySummaryLabel;
public final Content record;
public final Content records;
public final Content recordComponents;
public final Content referencedIn;
public final Content relatedPackages;
Expand All @@ -182,15 +185,6 @@ public class Contents {

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

public final String annotationTypeSummary;
public final String classSummary;
public final String enumSummary;
public final String errorSummary;
public final String exceptionSummary;
public final String interfaceSummary;
public final String packageSummary;
public final String recordSummary;

private final Resources resources;

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

allClassesLabel = getNonBreakResource("doclet.All_Classes");
this.allClassesAndInterfacesLabel = getContent("doclet.All_Classes_And_Interfaces");
allImplementedInterfacesLabel = getContent("doclet.All_Implemented_Interfaces");
allModulesLabel = getNonBreakResource("doclet.All_Modules");
allPackagesLabel = getNonBreakResource("doclet.All_Packages");
Expand Down Expand Up @@ -278,13 +273,14 @@ public class Contents {
navAnnotationTypeMember = getContent("doclet.navAnnotationTypeMember");
navAnnotationTypeOptionalMember = getContent("doclet.navAnnotationTypeOptionalMember");
navAnnotationTypeRequiredMember = getContent("doclet.navAnnotationTypeRequiredMember");
navClassesAndInterfaces = getContent("doclet.navClassesAndInterfaces");
navConstructor = getContent("doclet.navConstructor");
navEnum = getContent("doclet.navEnum");
navField = getContent("doclet.navField");
navHelpNavigation = getContent("doclet.navNavigation");
navHelpPages = getContent("doclet.navPages");
navMethod = getContent("doclet.navMethod");
navModuleDescription = getContent("doclet.navModuleDescription");
navDescription = getContent("doclet.navDescription");
navModules = getContent("doclet.navModules");
navNested = getContent("doclet.navNested");
navPackages = getContent("doclet.navPackages");
Expand All @@ -300,6 +296,8 @@ public class Contents {
packageLabel = getContent("doclet.Package");
package_ = getContent("doclet.package");
packagesLabel = getContent("doclet.Packages");
packageSubNavLabel = getContent("doclet.Package_Sub_Nav");
this.packageSummaryLabel = getContent("doclet.Package_Summary");
parameters = getContent("doclet.Parameters");
previewAPI = getContent("doclet.Preview_API");
previewLabel = getContent("doclet.Preview_Label");
Expand All @@ -309,7 +307,7 @@ public class Contents {
propertyLabel = getContent("doclet.Property");
propertyDetailsLabel = getContent("doclet.Property_Detail");
propertySummaryLabel = getContent("doclet.Property_Summary");
record = getContent("doclet.RecordClass");
records = getContent("doclet.RecordClasses");
recordComponents = getContent("doclet.RecordComponents");
referencedIn = getContent("doclet.ReferencedIn");
relatedPackages = getContent("doclet.Related_Packages");
Expand All @@ -331,20 +329,15 @@ record = getContent("doclet.RecordClass");
valueLabel = getContent("doclet.Value");

navLinkLabels = new EnumMap<>(VisibleMemberTable.Kind.class);
navLinkLabels.put(VisibleMemberTable.Kind.INNER_CLASSES, getContent("doclet.navNested"));
navLinkLabels.put(VisibleMemberTable.Kind.NESTED_CLASSES, getContent("doclet.navNested"));
navLinkLabels.put(VisibleMemberTable.Kind.ENUM_CONSTANTS, getContent("doclet.navEnum"));
navLinkLabels.put(VisibleMemberTable.Kind.FIELDS, getContent("doclet.navField"));
navLinkLabels.put(VisibleMemberTable.Kind.CONSTRUCTORS, getContent("doclet.navConstructor"));
navLinkLabels.put(VisibleMemberTable.Kind.METHODS, getContent("doclet.navMethod"));

this.annotationTypeSummary = resources.getText("doclet.Annotation_Types_Summary");
this.classSummary = resources.getText("doclet.Class_Summary");
this.enumSummary = resources.getText("doclet.Enum_Summary");
this.errorSummary = resources.getText("doclet.Error_Summary");
this.exceptionSummary = resources.getText("doclet.Exception_Summary");
this.interfaceSummary = resources.getText("doclet.Interface_Summary");
this.packageSummary = resources.getText("doclet.Package_Summary");
this.recordSummary = resources.getText("doclet.Record_Class_Summary");
navLinkLabels.put(VisibleMemberTable.Kind.ANNOTATION_TYPE_MEMBER_OPTIONAL,
getContent("doclet.navAnnotationTypeOptionalMember"));
navLinkLabels.put(VisibleMemberTable.Kind.ANNOTATION_TYPE_MEMBER_REQUIRED,
getContent("doclet.navAnnotationTypeRequiredMember"));
}

/**
Expand Down
10 changes: 10 additions & 0 deletions src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HelpWriter.java
View file
Expand Up @@ -26,6 +26,7 @@
package jdk.javadoc.internal.doclets.formats.html;

import java.util.List;
import javax.lang.model.element.Element;

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

@Override
protected Navigation getNavBar(PageMode pageMode, Element element) {
return super.getNavBar(pageMode, element)
.setSubNavLinks(() -> List.of(
links.createLink(HtmlIds.HELP_NAVIGATION, contents.navHelpNavigation),
links.createLink(HtmlIds.HELP_PAGES, contents.navHelpPages))
);
}

/**
* Creates the navigation help, adding an entry into the main table-of-contents.
*
Expand Down
2 changes: 0 additions & 2 deletions src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java
View file
Expand Up @@ -139,8 +139,6 @@ protected Function<String, String> getResourceKeyMapper(DocletEnvironment docEnv
{ "doclet.help.annotation_type.description", "doclet.help.annotation_interface.description" },

// in doclets.properties
{ "doclet.Annotation_Types_Summary", "doclet.Annotation_Interfaces_Summary" },
{ "doclet.Enum_Summary", "doclet.Enum_Class_Summary" },
{ "doclet.Enums", "doclet.EnumClasses" },
{ "doclet.AnnotationType", "doclet.AnnotationInterface" },
{ "doclet.AnnotationTypes", "doclet.AnnotationInterfaces" },
Expand Down
23 changes: 23 additions & 0 deletions src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java
View file
Expand Up @@ -42,6 +42,7 @@
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlId;
import jdk.javadoc.internal.doclets.toolkit.util.SummaryAPIListBuilder;
import jdk.javadoc.internal.doclets.toolkit.util.Utils;
import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable;

/**
* Centralized constants and factory methods for HTML ids.
Expand Down Expand Up @@ -72,6 +73,7 @@ public class HtmlIds {
static final HtmlId ANNOTATION_TYPE_OPTIONAL_ELEMENT_SUMMARY = HtmlId.of("annotation-interface-optional-element-summary");
static final HtmlId ANNOTATION_TYPE_REQUIRED_ELEMENT_SUMMARY = HtmlId.of("annotation-interface-required-element-summary");
static final HtmlId CLASS_DESCRIPTION = HtmlId.of("class-description");
static final HtmlId CLASS_SUMMARY = HtmlId.of("class-summary");
static final HtmlId CONSTRUCTOR_DETAIL = HtmlId.of("constructor-detail");
static final HtmlId CONSTRUCTOR_SUMMARY = HtmlId.of("constructor-summary");
static final HtmlId ENUM_CONSTANT_DETAIL = HtmlId.of("enum-constant-detail");
Expand All @@ -95,6 +97,7 @@ public class HtmlIds {
static final HtmlId PACKAGE_SUMMARY_TABLE = HtmlId.of("package-summary-table");
static final HtmlId PROPERTY_DETAIL = HtmlId.of("property-detail");
static final HtmlId PROPERTY_SUMMARY = HtmlId.of("property-summary");
static final HtmlId RELATED_PACKAGE_SUMMARY = HtmlId.of("related-package-summary");
static final HtmlId RESET_BUTTON = HtmlId.of("reset-button");
static final HtmlId SEARCH_INPUT = HtmlId.of("search-input");
static final HtmlId SERVICES = HtmlId.of("services-summary");
Expand Down Expand Up @@ -424,6 +427,26 @@ static HtmlId forSummaryKind(SummaryAPIListBuilder.SummaryElementKind kind) {
});
}

/**
* Returns an id for the member summary table of the given {@code kind} in a class page.
*
* @param kind the kind of member
*
* @return the id
*/
static HtmlId forMemberSummary(VisibleMemberTable.Kind kind) {
return switch (kind) {
case NESTED_CLASSES -> NESTED_CLASS_SUMMARY;
case ENUM_CONSTANTS -> ENUM_CONSTANT_SUMMARY;
case FIELDS -> FIELD_SUMMARY;
case CONSTRUCTORS -> CONSTRUCTOR_SUMMARY;
case METHODS -> METHOD_SUMMARY;
case ANNOTATION_TYPE_MEMBER_OPTIONAL -> ANNOTATION_TYPE_OPTIONAL_ELEMENT_SUMMARY;
case ANNOTATION_TYPE_MEMBER_REQUIRED -> ANNOTATION_TYPE_REQUIRED_ELEMENT_SUMMARY;
case PROPERTIES -> PROPERTY_SUMMARY;
};
}

/**
* Returns an id for a "tab" in a table.
*
Expand Down
15 changes: 10 additions & 5 deletions ...jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriterImpl.java
View file
Expand Up @@ -197,11 +197,16 @@ public Content getModuleHeader(String heading) {
@Override
protected Navigation getNavBar(PageMode pageMode, Element element) {
return super.getNavBar(pageMode, element)
.setDisplaySummaryModuleDescLink(!utils.getFullBody(mdle).isEmpty() && !options.noComment())
.setDisplaySummaryModulesLink(display(requires) || display(indirectModules))
.setDisplaySummaryPackagesLink(display(packages) || display(indirectPackages)
|| display(indirectOpenPackages))
.setDisplaySummaryServicesLink(displayServices(uses, usesTrees) || displayServices(provides.keySet(), providesTrees));
.setSubNavLinks(() -> List.of(
links.createLink(HtmlIds.MODULE_DESCRIPTION, contents.navDescription,
!utils.getFullBody(mdle).isEmpty() && !options.noComment()),
links.createLink(HtmlIds.MODULES, contents.navModules,
display(requires) || display(indirectModules)),
links.createLink(HtmlIds.PACKAGES, contents.navPackages,
display(packages) || display(indirectPackages) || display(indirectOpenPackages)),
links.createLink(HtmlIds.SERVICES, contents.navServices,
displayServices(uses, usesTrees) || displayServices(provides.keySet(), providesTrees))
));
}

/**
Expand Down

1 comment on commit d2b5350

@openjdk-notifier
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review

Issues

Please sign in to comment.