8263198: javadoc HELP page

Reviewed-by: hannesw

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");

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.
      */

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
+     * 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. If "-notree"
+     * help file contents it also keeps track of user options.
-     * is used, then the "overview-tree.html" will not get added and hence
-     * help information also will not get added.
      *
-     * @param contentTree the content tree to which the help file contents will be added
+     * The general organization is:
+     * <ul>
+     * <li>Heading, and TOC
+     * <li>Navigation help
+     * <li>Page-specific help
+     * </ul>
      */
     protected void addHelpFileContents(Content contentTree) {
-        // Heading
+        HtmlTree mainTOC = new HtmlTree(TagName.UL).setStyle(HtmlStyle.helpTOC);
-        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,
+        contentTree.add(HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING, HtmlStyle.title,
-                getContent("doclet.help.intro"));
+                                        getContent("doclet.help.main_heading")))
-        div.add(intro);
+                .add(mainTOC)
-        contentTree.add(div);
+                .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:
+     * <ul>
+     * <li>General notes
+     * <li>Search
+     * </ul>
+     *
+     * @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))
+        mainTOC.add(HtmlTree.LI(new ContentBuilder(
-                .add(HtmlTree.SPAN(HtmlStyle.helpFootnote,
+                links.createLink(DocLink.fragment(HtmlIds.HELP_NAVIGATION.name()), navHeading),
-                            getContent("doclet.help.footnote")));
+                Text.of(": "), subTOC)));
+
+        return content;
+    }
+
+
+    /**
+     * Creates the page-specific help, adding an entry into the main table-of-contents.
+     *
+     * The general organization is:
+     * <ul>
+     * <li>Overview
+     * <li>Declaration pages: module, package, classes
+     * <li>Derived info for declarations: use and tree
+     * <li>General summary info: deprecated, preview
+     * <li>Detailed summary info: constant values, serialized form, system properties
+     * <li>Index info: all packages, all classes, full index
+     * </ul>
+     *
+     * @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) {

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("_", "-"));
+    }
 }

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, "")));
         }
     }

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,
+    //</editor-fold>
+
+    //<editor-fold desc="page styles for <body> elements">
+    //
+    // The following constants are used for the class of the {@code <body>} 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");
+
     //</editor-fold>
 
     private final String cssName;

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
+    JavaDoc Help
-doclet.help.intro=\
+doclet.help.navigation.head=\
-    This API (Application Programming Interface) document has pages corresponding to the items in \
+    Navigation
-    the navigation bar, described as follows.
+# 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 \
+    Each class, interface, nested class and nested interface has its own separate page. \
-    these pages has three sections consisting of a class/interface description, summary tables, \
+    Each of these pages has three sections consisting of a declaration and description, \
-    and detailed member descriptions:
+    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}

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=<a> 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

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.
  */

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",
                 """
-                    </div>
+                    <section class="help-section" id="package">
-                    <section class="help-section">
+                    <h3>Package</h3>""",
-                    <h2>Package</h2>""",
                 """
                     <ul class="help-section-list">
                     <li>Interfaces</li>
@@ -66,8 +65,8 @@ public class TestHelpFile extends JavadocTester {
                     <li>Enum Classes</li>""",
                 """
                     </section>
-                    <section class="help-section">
+                    <section class="help-section" id="class">
-                    <h2>Class or Interface</h2>""",
+                    <h3>Class or Interface</h3>""",
                 """
                     <ul class="help-section-list">
                     <li>Class Inheritance Diagram</li>

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, """
-            <li><a href="../help-doc.html">Help</a></li>""");
+            <li><a href="../help-doc.html#class">Help</a></li>""");
         checkExit(Exit.OK);
     }
 
@@ -102,7 +102,7 @@ public class TestHelpOption extends JavadocTester {
         checkExit(Exit.OK);
         checkOutput("Sample.html", true,
                 """
-                    <li><a href="test-help.html">Help</a></li>""");
+                    <li><a href="test-help.html#class">Help</a></li>""");
         checkOutput("test-help.html", true,
                 "Help, help.");
     }

test/langtools/jdk/javadoc/doclet/testHelpOption/test-help.html

@@ -4,6 +4,13 @@
 </head>
 <body bgcolor="white">
 Help, help.
+<p id="all-classes">All Classes</p>
+<p id="all-packages">All Packages</p>
+<p id="class">Class</p>
+<p id="help">Help</p>
+<p id="index">Index</p>
+<p id="package">Package</p>
+<p id="tree">Tree</p>
 </body>
 </html>
 

test/langtools/jdk/javadoc/doclet/testHtmlVersion/TestHtmlVersion.java

@@ -323,18 +323,18 @@ public class TestHtmlVersion extends JavadocTester {
                     <!-- ========= START OF TOP NAVBAR ======= -->""",
                 """
                     <main role="main">
-                    <div class="header">""",
+                    <h1 class="title">JavaDoc Help</h1>""",
                 """
-                    <section class="help-section">
+                    <section class="help-section" id="overview">
-                    <h2>Overview</h2>
+                    <h3>Overview</h3>
                     """,
                 """
-                    <section class="help-section">
+                    <section class="help-section" id="package">
-                    <h2>Package</h2>
+                    <h3>Package</h3>
                     """,
                 """
-                    <section class="help-section">
+                    <section class="help-section" id="class">
-                    <h2>Class or Interface</h2>
+                    <h3>Class or Interface</h3>
                     """,
                 """
                     <footer role="contentinfo">""",

test/langtools/jdk/javadoc/doclet/testSingletonLists/TestSingletonLists.java

@@ -231,7 +231,11 @@ public class TestSingletonLists extends JavadocTester {
         private int regionErrors;
         private String fileName;
         private boolean inheritanceClass;
-        private List<String> excludeFiles = List.of("overview-tree.html","package-tree.html","module-summary.html");
+        private List<String> excludeFiles = List.of(
+                "overview-tree.html",
+                "package-tree.html",
+                "module-summary.html",
+                "help-doc.html");
 
         ListChecker(PrintStream out, Function<Path,String> fileReader) {
             super(out, fileReader);