diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Contents.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Contents.java
index 485657cae05..db42f66c104 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Contents.java
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Contents.java
@@ -106,6 +106,7 @@ public class Contents {
public final Content functionalInterface;
public final Content functionalInterfaceMessage;
public final Content helpLabel;
+ public final Content helpSubNavLabel;
public final Content hierarchyForAllPackages;
public final Content implementation;
public final Content implementingClassesLabel;
@@ -130,6 +131,8 @@ public class Contents {
public final Content navConstructor;
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;
@@ -252,6 +255,7 @@ public class Contents {
functionalInterface = getContent("doclet.Functional_Interface");
functionalInterfaceMessage = getContent("doclet.Functional_Interface_Message");
helpLabel = getContent("doclet.Help");
+ helpSubNavLabel = getContent("doclet.Help_Sub_Nav");
hierarchyForAllPackages = getContent("doclet.Hierarchy_For_All_Packages");
implementation = getContent("doclet.Implementation");
implementingClassesLabel = getContent("doclet.Implementing_Classes");
@@ -276,6 +280,8 @@ public class Contents {
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");
navModules = getContent("doclet.navModules");
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Headings.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Headings.java
index f65f3cc59e9..0aed442460e 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Headings.java
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Headings.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1998, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -47,6 +47,12 @@ class Headings {
*/
static final TagName CONTENT_HEADING = TagName.H2;
+ /**
+ * Standard third-level heading for sundry pages that do
+ * not have their own page group.
+ */
+ static final TagName SUB_HEADING = TagName.H3;
+
/**
* Headings for the page for a module declaration.
*/
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HelpWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HelpWriter.java
index 6a0c8baaf3c..d38a1fb2015 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HelpWriter.java
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HelpWriter.java
@@ -29,6 +29,7 @@ import java.util.List;
import jdk.javadoc.internal.doclets.formats.html.markup.BodyContents;
import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
+import jdk.javadoc.internal.doclets.formats.html.markup.HtmlId;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
import jdk.javadoc.internal.doclets.formats.html.markup.TagName;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
@@ -36,6 +37,7 @@ import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
import jdk.javadoc.internal.doclets.formats.html.markup.Text;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
+import jdk.javadoc.internal.doclets.toolkit.util.DocLink;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
@@ -57,6 +59,11 @@ public class HelpWriter extends HtmlDocletWriter {
{"HM.cK", "\"java.util.HashMap.containsKey(Object)\""}
};
+ Content overviewLink;
+ Content indexLink;
+ Content allClassesLink;
+ Content allPackagesLink;
+
/**
* Constructor to construct HelpWriter object.
* @param configuration the configuration
@@ -65,6 +72,15 @@ public class HelpWriter extends HtmlDocletWriter {
public HelpWriter(HtmlConfiguration configuration,
DocPath filename) {
super(configuration, filename);
+
+ // yes, INDEX is correct in the following line
+ overviewLink = links.createLink(DocPaths.INDEX, resources.getText("doclet.Overview"));
+ allPackagesLink = links.createLink(DocPaths.ALLPACKAGES_INDEX, resources.getText("doclet.All_Packages"));
+ allClassesLink = links.createLink(DocPaths.ALLCLASSES_INDEX, resources.getText("doclet.All_Classes"));
+ DocPath dp = options.splitIndex()
+ ? DocPaths.INDEX_FILES.resolve(DocPaths.indexN(1))
+ : DocPaths.INDEX_ALL;
+ indexLink = links.createLink(dp, resources.getText("doclet.Index"));
}
/**
@@ -100,186 +116,72 @@ public class HelpWriter extends HtmlDocletWriter {
}
/**
- * Add the help file contents from the resource file to the content tree. While adding the
- * help file contents it also keeps track of user options. If "-notree"
- * is used, then the "overview-tree.html" will not get added and hence
- * help information also will not get added.
+ * Adds the help file contents from the resource file to the content tree. While adding the
+ * help file contents it also keeps track of user options.
*
- * @param contentTree the content tree to which the help file contents will be added
+ * The general organization is:
+ *
+ * - Heading, and TOC
+ *
- Navigation help
+ *
- Page-specific help
+ *
*/
protected void addHelpFileContents(Content contentTree) {
- // Heading
- Content heading = HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING, HtmlStyle.title,
- getContent("doclet.help.main_heading"));
- Content div = HtmlTree.DIV(HtmlStyle.header, heading);
- Content intro = HtmlTree.DIV(HtmlStyle.subTitle,
- getContent("doclet.help.intro"));
- div.add(intro);
- contentTree.add(div);
+ HtmlTree mainTOC = new HtmlTree(TagName.UL).setStyle(HtmlStyle.helpTOC);
+
+
+
+ contentTree.add(HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING, HtmlStyle.title,
+ getContent("doclet.help.main_heading")))
+ .add(mainTOC)
+ .add(new HtmlTree(TagName.HR))
+ .add(getNavigationSection(mainTOC))
+ .add(new HtmlTree(TagName.HR))
+ .add(getPageKindSection(mainTOC))
+ .add(new HtmlTree(TagName.HR))
+ .add(HtmlTree.SPAN(HtmlStyle.helpFootnote,
+ getContent("doclet.help.footnote")));
+ }
+
+ /**
+ * Creates the navigation help, adding an entry into the main table-of-contents.
+ *
+ * The general organization is:
+ *
+ * - General notes
+ *
- Search
+ *
+ *
+ * @param mainTOC the main table-of-contents
+ *
+ * @return the content containing the help
+ */
+ private Content getNavigationSection(HtmlTree mainTOC) {
+ Content content = new ContentBuilder();
+
+ Content navHeading = contents.getContent("doclet.help.navigation.head");
+ HtmlTree navSection = HtmlTree.DIV(HtmlStyle.subTitle)
+ .add(HtmlTree.HEADING(Headings.CONTENT_HEADING, navHeading).setId(HtmlIds.HELP_NAVIGATION))
+ .add(contents.getContent("doclet.help.navigation.intro", overviewLink));
+ if (options.createIndex()) {
+ Content links = new ContentBuilder();
+ if (!configuration.packages.isEmpty()) {
+ links.add(allPackagesLink);
+ links.add(", ");
+ }
+ links.add(allClassesLink);
+ navSection.add(" ")
+ .add(contents.getContent("doclet.help.navigation.index", indexLink, links));
+ }
+ content.add(navSection);
+
+ HtmlTree subTOC = new HtmlTree(TagName.UL).setStyle(HtmlStyle.helpSubTOC);
HtmlTree section;
- // Overview
- if (options.createOverview()) {
- section = newHelpSection(contents.overviewLabel);
- String overviewKey = configuration.showModules
- ? "doclet.help.overview.modules.body"
- : "doclet.help.overview.packages.body";
- Content overviewLink = links.createLink(
- DocPaths.INDEX, resources.getText("doclet.Overview"));
- section.add(HtmlTree.P(getContent(overviewKey, overviewLink)));
- contentTree.add(section);
- }
-
- // Module
- if (configuration.showModules) {
- section = newHelpSection(contents.moduleLabel);
- Content moduleIntro = getContent("doclet.help.module.intro");
- Content modulePara = HtmlTree.P(moduleIntro);
- section.add(modulePara)
- .add(newHelpSectionList(
- contents.packagesLabel,
- contents.modulesLabel,
- contents.servicesLabel));
- contentTree.add(section);
- }
-
- // Package
- section = newHelpSection(contents.packageLabel)
- .add(HtmlTree.P(getContent("doclet.help.package.intro")))
- .add(newHelpSectionList(
- contents.interfaces,
- contents.classes,
- contents.enums,
- contents.exceptions,
- contents.errors,
- contents.annotationTypes));
- contentTree.add(section);
-
- // Class/interface
- section = newHelpSection(getContent("doclet.help.class_interface.head"))
- .add(HtmlTree.P(getContent("doclet.help.class_interface.intro")))
- .add(newHelpSectionList(
- getContent("doclet.help.class_interface.inheritance_diagram"),
- getContent("doclet.help.class_interface.subclasses"),
- getContent("doclet.help.class_interface.subinterfaces"),
- getContent("doclet.help.class_interface.implementations"),
- getContent("doclet.help.class_interface.declaration"),
- getContent("doclet.help.class_interface.description")))
- .add(new HtmlTree(TagName.BR))
- .add(newHelpSectionList(
- contents.nestedClassSummary,
- contents.fieldSummaryLabel,
- contents.propertySummaryLabel,
- contents.constructorSummaryLabel,
- contents.methodSummary))
- .add(new HtmlTree(TagName.BR))
- .add(newHelpSectionList(
- contents.fieldDetailsLabel,
- contents.propertyDetailsLabel,
- contents.constructorDetailsLabel,
- contents.methodDetailLabel))
- .add(HtmlTree.P(getContent("doclet.help.class_interface.summary")));
- contentTree.add(section);
-
- // Annotation Types
- section = newHelpSection(contents.annotationType)
- .add(HtmlTree.P(getContent("doclet.help.annotation_type.intro")))
- .add(newHelpSectionList(
- getContent("doclet.help.annotation_type.declaration"),
- getContent("doclet.help.annotation_type.description"),
- contents.annotateTypeRequiredMemberSummaryLabel,
- contents.annotateTypeOptionalMemberSummaryLabel,
- contents.annotationTypeMemberDetail));
- contentTree.add(section);
-
- // Enums
- section = newHelpSection(contents.enum_)
- .add(HtmlTree.P(getContent("doclet.help.enum.intro")))
- .add(newHelpSectionList(
- getContent("doclet.help.enum.declaration"),
- getContent("doclet.help.enum.definition"),
- contents.enumConstantSummary,
- contents.enumConstantDetailLabel));
- contentTree.add(section);
-
- // Class Use
- if (options.classUse()) {
- section = newHelpSection(getContent("doclet.help.use.head"))
- .add(HtmlTree.P(getContent("doclet.help.use.body")));
- contentTree.add(section);
- }
-
- // Tree
- if (options.createTree()) {
- section = newHelpSection(getContent("doclet.help.tree.head"));
- Content treeIntro = getContent("doclet.help.tree.intro",
- links.createLink(DocPaths.OVERVIEW_TREE, resources.getText("doclet.Class_Hierarchy")),
- HtmlTree.CODE(Text.of("java.lang.Object")));
- section.add(HtmlTree.P(treeIntro))
- .add(newHelpSectionList(
- getContent("doclet.help.tree.overview"),
- getContent("doclet.help.tree.package")));
- contentTree.add(section);
- }
-
- // Deprecated
- if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.DEPRECATED)) {
- section = newHelpSection(contents.deprecatedAPI);
- Content deprBody = getContent("doclet.help.deprecated.body",
- links.createLink(DocPaths.DEPRECATED_LIST, resources.getText("doclet.Deprecated_API")));
- section.add(HtmlTree.P(deprBody));
- contentTree.add(section);
- }
-
- // Preview
- if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.PREVIEW)) {
- section = newHelpSection(contents.previewAPI);
- Content previewBody = getContent("doclet.help.preview.body",
- links.createLink(DocPaths.PREVIEW_LIST, contents.previewAPI));
- section.add(HtmlTree.P(previewBody));
- contentTree.add(section);
- }
-
- // Index
- if (options.createIndex()) {
- DocPath dp = options.splitIndex()
- ? DocPaths.INDEX_FILES.resolve(DocPaths.indexN(1))
- : DocPaths.INDEX_ALL;
- Content indexLink = links.createLink(dp, resources.getText("doclet.Index"));
- section = newHelpSection(getContent("doclet.help.index.head"))
- .add(HtmlTree.P(getContent("doclet.help.index.body", indexLink)));
- contentTree.add(section);
- }
-
- // Serialized Form
- if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.SERIALIZED_FORM)) {
- section = newHelpSection(contents.serializedForm)
- .add(HtmlTree.P(getContent("doclet.help.serial_form.body")));
- contentTree.add(section);
- }
-
- // Constant Field Values
- if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.CONSTANT_VALUES)) {
- section = newHelpSection(contents.constantsSummaryTitle);
- Content constantsBody = getContent("doclet.help.constants.body",
- links.createLink(DocPaths.CONSTANT_VALUES, resources.getText("doclet.Constants_Summary")));
- section.add(HtmlTree.P(constantsBody));
- contentTree.add(section);
- }
-
- // System Properties
- if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.SYSTEM_PROPERTIES)) {
- section = newHelpSection(contents.systemPropertiesLabel);
- Content sysPropsBody = getContent("doclet.help.systemProperties.body",
- links.createLink(DocPaths.SYSTEM_PROPERTIES, resources.getText("doclet.systemProperties")));
- section.add(HtmlTree.P(sysPropsBody));
- contentTree.add(section);
- }
-
// Search
if (options.createIndex()) {
- section = newHelpSection(getContent("doclet.help.search.head"));
+ section = newHelpSection(getContent("doclet.help.search.head"), subTOC, HtmlIds.HELP_SEARCH);
Content searchIntro = HtmlTree.P(getContent("doclet.help.search.intro"));
Content searchExamples = new HtmlTree(TagName.UL).setStyle(HtmlStyle.helpSectionList);
for (String[] example : SEARCH_EXAMPLES) {
@@ -294,12 +196,217 @@ public class HelpWriter extends HtmlDocletWriter {
section.add(searchIntro)
.add(searchExamples)
.add(searchRefer);
- contentTree.add(section);
+ navSection.add(section);
}
- contentTree.add(new HtmlTree(TagName.HR))
- .add(HtmlTree.SPAN(HtmlStyle.helpFootnote,
- getContent("doclet.help.footnote")));
+ mainTOC.add(HtmlTree.LI(new ContentBuilder(
+ links.createLink(DocLink.fragment(HtmlIds.HELP_NAVIGATION.name()), navHeading),
+ Text.of(": "), subTOC)));
+
+ return content;
+ }
+
+
+ /**
+ * Creates the page-specific help, adding an entry into the main table-of-contents.
+ *
+ * The general organization is:
+ *
+ * - Overview
+ *
- Declaration pages: module, package, classes
+ *
- Derived info for declarations: use and tree
+ *
- General summary info: deprecated, preview
+ *
- Detailed summary info: constant values, serialized form, system properties
+ *
- Index info: all packages, all classes, full index
+ *
+ *
+ * @param mainTOC the main table-of-contents
+ *
+ * @return the content containing the help
+ */
+ private Content getPageKindSection(HtmlTree mainTOC) {
+ Content pageKindsHeading = contents.getContent("doclet.help.page_kinds.head");
+ HtmlTree pageKindsSection = HtmlTree.DIV(HtmlStyle.subTitle)
+ .add(HtmlTree.HEADING(Headings.CONTENT_HEADING, pageKindsHeading).setId(HtmlIds.HELP_PAGES))
+ .add(contents.getContent("doclet.help.page_kinds.intro"));
+
+ HtmlTree subTOC = new HtmlTree(TagName.UL).setStyle(HtmlStyle.helpSubTOC);
+
+ HtmlTree section;
+
+ // Overview
+ if (options.createOverview()) {
+ section = newHelpSection(contents.overviewLabel, PageMode.OVERVIEW, subTOC);
+ String overviewKey = configuration.showModules
+ ? "doclet.help.overview.modules.body"
+ : "doclet.help.overview.packages.body";
+ section.add(HtmlTree.P(getContent(overviewKey, overviewLink)));
+ pageKindsSection.add(section);
+ }
+
+ // Module
+ if (configuration.showModules) {
+ section = newHelpSection(contents.moduleLabel, PageMode.MODULE, subTOC);
+ Content moduleIntro = getContent("doclet.help.module.intro");
+ Content modulePara = HtmlTree.P(moduleIntro);
+ section.add(modulePara)
+ .add(newHelpSectionList(
+ contents.packagesLabel,
+ contents.modulesLabel,
+ contents.servicesLabel));
+ pageKindsSection.add(section);
+ }
+
+ // Package
+ section = newHelpSection(contents.packageLabel, PageMode.PACKAGE, subTOC)
+ .add(HtmlTree.P(getContent("doclet.help.package.intro")))
+ .add(newHelpSectionList(
+ contents.interfaces,
+ contents.classes,
+ contents.enums,
+ contents.exceptions,
+ contents.errors,
+ contents.annotationTypes));
+ pageKindsSection.add(section);
+
+ // Class/interface
+ Content notes = new ContentBuilder(
+ HtmlTree.SPAN(HtmlStyle.helpNote, getContent("doclet.help.class_interface.note")),
+ Text.of(" "),
+ getContent("doclet.help.class_interface.anno"),
+ Text.of(" "),
+ getContent("doclet.help.class_interface.enum"),
+ Text.of(" "),
+ getContent("doclet.help.class_interface.record"),
+ Text.of(" "),
+ getContent("doclet.help.class_interface.property"));
+
+ section = newHelpSection(getContent("doclet.help.class_interface.head"), PageMode.CLASS, subTOC)
+ .add(HtmlTree.P(getContent("doclet.help.class_interface.intro")))
+ .add(newHelpSectionList(
+ getContent("doclet.help.class_interface.inheritance_diagram"),
+ getContent("doclet.help.class_interface.subclasses"),
+ getContent("doclet.help.class_interface.subinterfaces"),
+ getContent("doclet.help.class_interface.implementations"),
+ getContent("doclet.help.class_interface.declaration"),
+ getContent("doclet.help.class_interface.description")))
+ .add(new HtmlTree(TagName.BR))
+ .add(newHelpSectionList(
+ contents.nestedClassSummary,
+ contents.enumConstantSummary,
+ contents.fieldSummaryLabel,
+ contents.propertySummaryLabel,
+ contents.constructorSummaryLabel,
+ contents.methodSummary,
+ contents.annotateTypeRequiredMemberSummaryLabel,
+ contents.annotateTypeOptionalMemberSummaryLabel))
+ .add(new HtmlTree(TagName.BR))
+ .add(newHelpSectionList(
+ contents.enumConstantDetailLabel,
+ contents.fieldDetailsLabel,
+ contents.propertyDetailsLabel,
+ contents.constructorDetailsLabel,
+ contents.methodDetailLabel,
+ contents.annotationTypeMemberDetail))
+ .add(HtmlTree.P(notes))
+ .add(HtmlTree.P(getContent("doclet.help.class_interface.member_order")));
+ pageKindsSection.add(section);
+
+ section = newHelpSection(getContent("doclet.help.other_files.head"), PageMode.DOC_FILE, subTOC)
+ .add(HtmlTree.P(getContent("doclet.help.other_files.body")));
+ pageKindsSection.add(section);
+
+ // Class Use
+ if (options.classUse()) {
+ section = newHelpSection(getContent("doclet.help.use.head"), PageMode.USE, subTOC)
+ .add(HtmlTree.P(getContent("doclet.help.use.body")));
+ pageKindsSection.add(section);
+ }
+
+ // Tree
+ if (options.createTree()) {
+ section = newHelpSection(getContent("doclet.help.tree.head"), PageMode.TREE, subTOC);
+ Content treeIntro = getContent("doclet.help.tree.intro",
+ links.createLink(DocPaths.OVERVIEW_TREE, resources.getText("doclet.Class_Hierarchy")),
+ HtmlTree.CODE(Text.of("java.lang.Object")));
+ section.add(HtmlTree.P(treeIntro))
+ .add(newHelpSectionList(
+ getContent("doclet.help.tree.overview"),
+ getContent("doclet.help.tree.package")));
+ pageKindsSection.add(section);
+ }
+
+ // Deprecated
+ if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.DEPRECATED)) {
+ section = newHelpSection(contents.deprecatedAPI, PageMode.DEPRECATED, subTOC);
+ Content deprBody = getContent("doclet.help.deprecated.body",
+ links.createLink(DocPaths.DEPRECATED_LIST, resources.getText("doclet.Deprecated_API")));
+ section.add(HtmlTree.P(deprBody));
+ pageKindsSection.add(section);
+ }
+
+ // Preview
+ if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.PREVIEW)) {
+ section = newHelpSection(contents.previewAPI, PageMode.PREVIEW, subTOC);
+ Content previewBody = getContent("doclet.help.preview.body",
+ links.createLink(DocPaths.PREVIEW_LIST, contents.previewAPI));
+ section.add(HtmlTree.P(previewBody));
+ pageKindsSection.add(section);
+ }
+
+ // Constant Field Values
+ if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.CONSTANT_VALUES)) {
+ section = newHelpSection(contents.constantsSummaryTitle, PageMode.CONSTANT_VALUES, subTOC);
+ Content constantsBody = getContent("doclet.help.constants.body",
+ links.createLink(DocPaths.CONSTANT_VALUES, resources.getText("doclet.Constants_Summary")));
+ section.add(HtmlTree.P(constantsBody));
+ pageKindsSection.add(section);
+ }
+
+ // Serialized Form
+ if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.SERIALIZED_FORM)) {
+ section = newHelpSection(contents.serializedForm, PageMode.SERIALIZED_FORM, subTOC)
+ .add(HtmlTree.P(getContent("doclet.help.serial_form.body")));
+ pageKindsSection.add(section);
+ }
+
+ // System Properties
+ if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.SYSTEM_PROPERTIES)) {
+ section = newHelpSection(contents.systemPropertiesLabel, PageMode.SYSTEM_PROPERTIES, subTOC);
+ Content sysPropsBody = getContent("doclet.help.systemProperties.body",
+ links.createLink(DocPaths.SYSTEM_PROPERTIES, resources.getText("doclet.systemProperties")));
+ section.add(HtmlTree.P(sysPropsBody));
+ pageKindsSection.add(section);
+ }
+
+ // Index
+ if (options.createIndex()) {
+ if (!configuration.packages.isEmpty()) {
+ section = newHelpSection(getContent("doclet.help.all_packages.head"), PageMode.ALL_PACKAGES, subTOC)
+ .add(HtmlTree.P(getContent("doclet.help.all_packages.body", allPackagesLink)));
+ pageKindsSection.add(section);
+ }
+
+ section = newHelpSection(getContent("doclet.help.all_classes.head"), PageMode.ALL_CLASSES, subTOC)
+ .add(HtmlTree.P(getContent("doclet.help.all_classes.body", allClassesLink)));
+ pageKindsSection.add(section);
+
+ Content links = new ContentBuilder();
+ if (!configuration.packages.isEmpty()) {
+ links.add(allPackagesLink);
+ links.add(", ");
+ }
+ links.add(allClassesLink);
+ section = newHelpSection(getContent("doclet.help.index.head"), PageMode.INDEX, subTOC)
+ .add(HtmlTree.P(getContent("doclet.help.index.body", indexLink, links)));
+ pageKindsSection.add(section);
+ }
+
+ mainTOC.add(HtmlTree.LI(new ContentBuilder(
+ links.createLink(DocLink.fragment(HtmlIds.HELP_PAGES.name()), pageKindsHeading),
+ Text.of(": "), subTOC)));
+
+ return pageKindsSection;
}
private Content getContent(String key) {
@@ -314,9 +421,17 @@ public class HelpWriter extends HtmlDocletWriter {
return contents.getContent(key, arg1, arg2);
}
- private HtmlTree newHelpSection(Content headingContent) {
+ private HtmlTree newHelpSection(Content headingContent, HtmlTree toc, HtmlId id) {
+ Content link = links.createLink(DocLink.fragment(id.name()), headingContent);
+ toc.add(HtmlTree.LI(link));
+
return HtmlTree.SECTION(HtmlStyle.helpSection,
- HtmlTree.HEADING(Headings.CONTENT_HEADING, headingContent));
+ HtmlTree.HEADING(Headings.SUB_HEADING, headingContent))
+ .setId(id);
+ }
+
+ private HtmlTree newHelpSection(Content headingContent, Navigation.PageMode pm, HtmlTree toc) {
+ return newHelpSection(headingContent, toc, htmlIds.forPage(pm));
}
private HtmlTree newHelpSectionList(Content first, Content... rest) {
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java
index 36ea6469acf..977625f0fbf 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java
@@ -26,6 +26,7 @@
package jdk.javadoc.internal.doclets.formats.html;
import java.util.List;
+import java.util.Locale;
import java.util.Map;
import javax.lang.model.element.Element;
import javax.lang.model.element.ExecutableElement;
@@ -77,6 +78,9 @@ public class HtmlIds {
static final HtmlId FIELD_DETAIL = HtmlId.of("field-detail");
static final HtmlId FIELD_SUMMARY = HtmlId.of("field-summary");
static final HtmlId FOR_REMOVAL = HtmlId.of("for-removal");
+ static final HtmlId HELP_NAVIGATION = HtmlId.of("help-navigation");
+ static final HtmlId HELP_PAGES = HtmlId.of("help-pages");
+ static final HtmlId HELP_SEARCH = HtmlId.of("help-search");
static final HtmlId METHOD_DETAIL = HtmlId.of("method-detail");
static final HtmlId METHOD_SUMMARY = HtmlId.of("method-summary");
static final HtmlId METHOD_SUMMARY_TABLE = HtmlId.of("method-summary-table");
@@ -441,6 +445,13 @@ public class HtmlIds {
}
+ /**
+ * Returns an id for the "preview" section for an element.
+ *
+ * @param el the element
+ *
+ * @return the id
+ */
public HtmlId forPreviewSection(Element el) {
return HtmlId.of("preview-" + switch (el.getKind()) {
case CONSTRUCTOR, METHOD -> forMember((ExecutableElement) el).name();
@@ -448,4 +459,15 @@ public class HtmlIds {
default -> utils.getFullyQualifiedName(el, false);
});
}
+
+ /**
+ * Returns an id for the entry on the HELP page for a kind of generated page.
+ *
+ * @param page the kind of page
+ *
+ * @return the id
+ */
+ public HtmlId forPage(Navigation.PageMode page) {
+ return HtmlId.of(page.name().toLowerCase(Locale.ROOT).replace("_", "-"));
+ }
}
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java
index fcb830a8f9f..29c0329b4de 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java
@@ -387,6 +387,7 @@ public class Navigation {
addListToNav(listContents, tree);
}
break;
+
case MODULE:
if (displaySummaryModuleDescLink) {
addContentToList(listContents,
@@ -419,6 +420,18 @@ public class Navigation {
addListToNav(listContents, tree);
}
break;
+
+ case HELP:
+ addContentToList(listContents,
+ links.createLink(HtmlIds.HELP_NAVIGATION, contents.navHelpNavigation));
+ addContentToList(listContents,
+ links.createLink(HtmlIds.HELP_PAGES, contents.navHelpPages));
+ Content li = HtmlTree.LI(contents.helpSubNavLabel);
+ li.add(Entity.NO_BREAK_SPACE);
+ tree.add(li);
+ addListToNav(listContents, tree);
+ break;
+
default:
break;
}
@@ -601,7 +614,7 @@ public class Navigation {
for (VisibleMemberTable.Kind kind : detailSet) {
AbstractMemberWriter writer
= ((AbstractMemberWriter) memberSummaryBuilder.
- getMemberSummaryWriter(kind));
+ getMemberSummaryWriter(kind));
if (kind == ENUM_CONSTANTS && !configuration.utils.isEnum(typeElement)) {
continue;
}
@@ -884,7 +897,8 @@ public class Navigation {
DocFile file = DocFile.createFileForInput(configuration, helpfile);
helpfilenm = DocPath.create(file.getName());
}
- tree.add(HtmlTree.LI(links.createLink(pathToRoot.resolve(helpfilenm),
+ tree.add(HtmlTree.LI(links.createLink(
+ new DocLink(pathToRoot.resolve(helpfilenm), htmlIds.forPage(documentedPage).name()),
contents.helpLabel, "")));
}
}
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java
index 02c9aee9f0d..357b88128e9 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java
@@ -60,9 +60,6 @@ public enum HtmlStyle {
deprecationComment,
descfrmTypeLabel,
externalLink,
- helpFootnote,
- helpSection,
- helpSectionList,
hierarchy,
horizontal,
implementationLabel,
@@ -716,7 +713,44 @@ public enum HtmlStyle {
/**
* The class of the {@code body} element for the page for the class hierarchy.
*/
- treePage;
+ treePage,
+ //
+
+ //
+ //
+ // The following constants are used for the class of the {@code } element
+ // for the corresponding pages.
+
+ /**
+ * The class of the footnote at the bottom of the page.
+ */
+ helpFootnote,
+
+ /**
+ * The class of the "Note:" prefix.
+ */
+ helpNote,
+
+ /**
+ * The class of each subsection in the page.
+ */
+ helpSection,
+
+ /**
+ * The class of lists in a subsection in the page.
+ */
+ helpSectionList,
+
+ /**
+ * The class of the top level list for the table of contents for the page.
+ */
+ helpTOC("help-toc"),
+
+ /**
+ * The class of the second-level lists in the table of contents for the page.
+ */
+ helpSubTOC("help-subtoc");
+
//
private final String cssName;
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties
index 39151ec2036..1c200d1ee02 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties
@@ -53,6 +53,7 @@ doclet.Href_Class_Or_Interface_Title=class or interface in {0}
doclet.Summary=Summary:
doclet.Detail=Detail:
doclet.Module_Sub_Nav=Module:
+doclet.Help_Sub_Nav=Help:
doclet.navModuleDescription=Description
doclet.navModules=Modules
doclet.navPackages=Packages
@@ -66,6 +67,8 @@ doclet.navProperty=Property
doclet.navEnum=Enum Constants
doclet.navConstructor=Constr
doclet.navMethod=Method
+doclet.navNavigation=Navigation
+doclet.navPages=Pages
doclet.not.exhaustive=(not exhaustive)
doclet.Index=Index
doclet.Window_Single_Index=Index
@@ -143,28 +146,42 @@ doclet.Window_Source_title=Source code
doclet.Window_Help_title=API Help
doclet.help.main_heading=\
- How This API Document Is Organized
-doclet.help.intro=\
- This API (Application Programming Interface) document has pages corresponding to the items in \
- the navigation bar, described as follows.
+ JavaDoc Help
+doclet.help.navigation.head=\
+ Navigation
+# 0: link to the Overview page
+doclet.help.navigation.intro=\
+ Starting from the {0} page, you can browse the documentation using the links \
+ in each page, and in the navigation bar at the top of each page.
+# 0: link to the Index; 1: short list of links
+doclet.help.navigation.index=\
+ The {0} and Search box allow you to navigate to specific declarations and summary pages, \
+ including: {1}
+doclet.help.page_kinds.head=\
+ Kinds of Pages
+doclet.help.page_kinds.intro=\
+ The following sections describe the different kinds of pages in this collection.
+# 0: link to the Overview page
doclet.help.overview.modules.body=\
The {0} page is the front page of this API document and provides a list of all modules with a \
summary for each. This page can also contain an overall description of the set of modules.
+# 0: link to the Overview page
doclet.help.overview.packages.body=\
The {0} page is the front page of this API document and provides a list of all packages with a \
summary for each. This page can also contain an overall description of the set of packages.
doclet.help.package.intro=\
Each package has a page that contains a list of its classes and interfaces, with a summary for \
- each. These pages may contain six categories:
+ each. These pages may contain the following categories:
doclet.help.module.intro=\
Each module has a page that contains a list of its packages, dependencies on other modules, \
- and services, with a summary for each. These pages may contain three categories:
+ and services, with a summary for each. These pages may contain the following categories:
doclet.help.class_interface.head=\
Class or Interface
doclet.help.class_interface.intro=\
- Each class, interface, nested class and nested interface has its own separate page. Each of \
- these pages has three sections consisting of a class/interface description, summary tables, \
- and detailed member descriptions:
+ Each class, interface, nested class and nested interface has its own separate page. \
+ Each of these pages has three sections consisting of a declaration and description, \
+ member summary tables, and detailed member descriptions. Entries in each of these \
+ sections are omitted if they are empty or not applicable.
doclet.help.class_interface.inheritance_diagram=\
Class Inheritance Diagram
doclet.help.class_interface.subclasses=\
@@ -177,61 +194,89 @@ doclet.help.class_interface.declaration=\
Class or Interface Declaration
doclet.help.class_interface.description=\
Class or Interface Description
-doclet.help.class_interface.summary=\
+doclet.help.class_interface.member_order=\
The summary entries are alphabetical, while the detailed descriptions are in the order they \
appear in the source code. This preserves the logical groupings established by the programmer.
+doclet.help.class_interface.note=\
+ Note:
+doclet.help.class_interface.anno=\
+ Annotation interfaces have required and optional elements, but not methods.
+doclet.help.class_interface.enum=\
+ Only enum classes have enum constants.
+doclet.help.class_interface.record=\
+ The components of a record class are displayed as part of the declaration of the record class.
+doclet.help.class_interface.property=\
+ Properties are a feature of JavaFX.
+doclet.help.other_files.head=\
+ Other Files
+doclet.help.other_files.body=\
+ Packages and modules may contain pages with additional information related to the \
+ declarations nearby.
doclet.help.use.head=\
Use
doclet.help.use.body=\
Each documented package, class and interface has its own Use page. This page describes what \
packages, classes, methods, constructors and fields use any part of the given class or \
- package. Given a class or interface A, its "Use" page includes subclasses of A, fields declared \
+ package. Given a class or interface A, its Use page includes subclasses of A, fields declared \
as A, methods that return A, and methods and constructors with parameters of type A. \
You can access this page by first going to the package, class or interface, then clicking on \
- the "Use" link in the navigation bar.
+ the USE link in the navigation bar.
doclet.help.tree.head=\
Tree (Class Hierarchy)
+# 0: link to main Class Hierarchy page; 1: java.lang.Object
doclet.help.tree.intro=\
There is a {0} page for all packages, plus a hierarchy for each package. Each hierarchy page \
contains a list of classes and a list of interfaces. Classes are organized by inheritance \
structure starting with {1}. Interfaces do not inherit from {1}.
doclet.help.tree.overview=\
- When viewing the Overview page, clicking on "Tree" displays the hierarchy for all packages.
+ When viewing the Overview page, clicking on TREE displays the hierarchy for all packages.
doclet.help.tree.package=\
- When viewing a particular package, class or interface page, clicking on "Tree" displays the \
+ When viewing a particular package, class or interface page, clicking on TREE displays the \
hierarchy for only that package.
+# 0: link to the Deprecated summary page
doclet.help.deprecated.body=\
The {0} page lists all of the API that have been deprecated. A deprecated API is not \
recommended for use, generally due to shortcomings, and a replacement API is usually given. \
Deprecated APIs may be removed in future implementations.
+# 0: link to the Preview summary page
doclet.help.preview.body=\
The {0} page lists all of the Preview APIs. \
Preview APIs may be removed in future implementations.
doclet.help.index.head=\
Index
+# 0: link to Index page; 1: list of links to pages
doclet.help.index.body=\
The {0} contains an alphabetic index of all classes, interfaces, constructors, methods, \
- and fields, as well as lists of all packages and all classes.
+ and fields in the documentation, as well as summary pages such as {1}.
+doclet.help.all_classes.head=\
+ All Classes
+# 0: link to All Classes page
+doclet.help.all_classes.body=\
+ The {0} page contains an alphabetic index of all classes and interfaces contained in the \
+ documentation, including annotation interfaces, enum classes, and record classes.
+doclet.help.all_packages.head=\
+ All Packages
+# 0: link to All Packages page
+doclet.help.all_packages.body=\
+ The {0} page contains an alphabetic index of all packages contained in the documentation.
doclet.help.serial_form.body=\
Each serializable or externalizable class has a description of its serialization fields and \
methods. This information is of interest to those who implement rather than use the API. \
While there is no link in the navigation bar, you can get to this information by going to any \
serialized class and clicking "Serialized Form" in the "See Also" section of the class \
description.
+# 0: link to Constant Values page
doclet.help.constants.body=\
The {0} page lists the static final fields and their values.
+# 0: link to System Properties page
doclet.help.systemProperties.body=\
The {0} page lists references to system properties.
doclet.help.footnote=\
This help file applies to API documentation generated by the standard doclet.
doclet.help.enum.intro=\
- Each enum has its own separate page with the following sections:
+ Each enum class has its own separate page with the following sections:
doclet.help.enum.class.intro=\
Each enum class has its own separate page with the following sections:
-doclet.help.enum.declaration=\
- Enum Declaration
-doclet.help.enum.definition=\
- Enum Description
doclet.help.annotation_type.intro=\
Each annotation type has its own separate page with the following sections:
doclet.help.annotation_interface.intro=\
@@ -248,15 +293,15 @@ doclet.help.search.head=Search
# Introduction to Javadoc search features, followed by a list of examples
doclet.help.search.intro=You can search for definitions of modules, packages, types, fields, methods, \
system properties and other terms defined in the API, using some or all of the name, optionally \
- using "camel-case" abbreviations. For example:
+ using "camelCase" abbreviations. For example:
# Used to list search examples, {0} is a search term and {1} the matching result
doclet.help.search.example={0} will match {1}
# {0} contains a link to the current Javadoc Search Specification
-doclet.help.search.refer=Refer to {0} for a full description of search features.
+doclet.help.search.refer=Refer to the {0} for a full description of search features.
# The URL for the Javadoc Search Specification. {0} will be replaced by the JDK version number
doclet.help.search.spec.url=https://docs.oracle.com/en/java/javase/{0}/docs/specs/javadoc/javadoc-search-spec.html
# The title for the Javadoc Search Specification
-doclet.help.search.spec.title=the Javadoc Search Specification
+doclet.help.search.spec.title=Javadoc Search Specification
doclet.ClassUse_Packages.that.use.0=Packages that use {0}
doclet.ClassUse_Uses.of.0.in.1=Uses of {0} in {1}
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties
index 24ec216fd06..985cfa10136 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties
@@ -112,7 +112,6 @@ doclet.Factory=Factory:
doclet.UnknownTag={0} is an unknown tag.
doclet.UnknownTagLowercase={0} is an unknown tag -- same as a known tag except for case.
doclet.noInheritedDoc=@inheritDoc used but {0} does not override or implement any method.
-# doclet.malformed_html_link_tag= tag is malformed:\n"{0}"
doclet.tag_misuse=Tag {0} cannot be used in {1} documentation. It can only be used in the following types of documentation: {2}.
doclet.Package_Summary=Package Summary
doclet.Requires_Summary=Requires
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
index 8a2a2ef76b3..102bf23056d 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
@@ -675,6 +675,18 @@ section.description {
ul.help-section-list {
margin: 0;
}
+ul.help-subtoc > li {
+ display: inline-block;
+ padding-right: 5px;
+ font-size: smaller;
+}
+ul.help-subtoc > li::before {
+ content: "\2022" ;
+ padding-right:2px;
+}
+span.help-note {
+ font-style: italic;
+}
/*
* Indicator icon for external links.
*/
diff --git a/test/langtools/jdk/javadoc/doclet/testHelpFile/TestHelpFile.java b/test/langtools/jdk/javadoc/doclet/testHelpFile/TestHelpFile.java
index bc6c1d8f25c..df544cd8110 100644
--- a/test/langtools/jdk/javadoc/doclet/testHelpFile/TestHelpFile.java
+++ b/test/langtools/jdk/javadoc/doclet/testHelpFile/TestHelpFile.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -56,9 +56,8 @@ public class TestHelpFile extends JavadocTester {
// check a representative sample of the contents
checkOrder("help-doc.html",
"""
-
-
- Package
""",
+
+ Package
""",
"""
- Interfaces
@@ -66,8 +65,8 @@ public class TestHelpFile extends JavadocTester {
- Enum Classes
""",
"""
-
- Class or Interface
""",
+
+ Class or Interface
""",
"""
- Class Inheritance Diagram
diff --git a/test/langtools/jdk/javadoc/doclet/testHelpOption/TestHelpOption.java b/test/langtools/jdk/javadoc/doclet/testHelpOption/TestHelpOption.java
index fc60eae5b39..705b5bc7ef8 100644
--- a/test/langtools/jdk/javadoc/doclet/testHelpOption/TestHelpOption.java
+++ b/test/langtools/jdk/javadoc/doclet/testHelpOption/TestHelpOption.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -89,7 +89,7 @@ public class TestHelpOption extends JavadocTester {
"-nohelp",
testSrc("Sample.java"));
checkOutput("Sample.html", false, """
- - Help
""");
+ - Help
""");
checkExit(Exit.OK);
}
@@ -102,7 +102,7 @@ public class TestHelpOption extends JavadocTester {
checkExit(Exit.OK);
checkOutput("Sample.html", true,
"""
- - Help
""");
+ - Help
""");
checkOutput("test-help.html", true,
"Help, help.");
}
diff --git a/test/langtools/jdk/javadoc/doclet/testHelpOption/test-help.html b/test/langtools/jdk/javadoc/doclet/testHelpOption/test-help.html
index 36b9ee17202..b700df2b8ec 100644
--- a/test/langtools/jdk/javadoc/doclet/testHelpOption/test-help.html
+++ b/test/langtools/jdk/javadoc/doclet/testHelpOption/test-help.html
@@ -4,6 +4,13 @@
Help, help.
+All Classes
+All Packages
+Class
+Help
+Index
+Package
+Tree