8320458: Improve structural navigation in API documentation

Reviewed-by: erikj, jjg

make/Docs.gmk

@@ -139,11 +139,6 @@ ifeq ($(IS_DRAFT), true)
   endif
   DRAFT_TEXT := This specification is not final and is subject to change. \
       Use is subject to <a href="$(LICENSE_URL)">license terms</a>.
-
-  # Workaround stylesheet bug
-  HEADER_STYLE := style="margin-top: 9px;"
-else
-  HEADER_STYLE := style="margin-top: 14px;"
 endif
 
 # $1 - Relative prefix to COPYRIGHT_URL
@@ -339,7 +334,7 @@ define SetupApiDocsGenerationBody
   $1_DOC_TITLE := $$($1_LONG_NAME)<br>Version $$(VERSION_SPECIFICATION) API \
       Specification
   $1_WINDOW_TITLE := $$(subst &amp;,&,$$($1_SHORT_NAME))$$(DRAFT_MARKER_TITLE)
-  $1_HEADER_TITLE := <div $$(HEADER_STYLE)><strong>$$($1_SHORT_NAME)</strong> \
+  $1_HEADER_TITLE := <div><strong>$$($1_SHORT_NAME)</strong> \
       $$(DRAFT_MARKER_STR)</div>
   ifneq ($$($1_OTHER_VERSIONS), )
       $1_JAVADOC_BOTTOM := $$(call JAVADOC_BOTTOM, <a href="$$($1_OTHER_VERSIONS)">Other versions.</a>)

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2024, 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
@@ -220,6 +220,7 @@ public void buildSummary(Content target)
             Content member = getMemberSummaryHeader(target);
             summaryTreeList.forEach(member::add);
             buildSummary(target, member);
+            writer.tableOfContents.addLink(HtmlIds.forMemberSummary(kind), getSummaryLabel());
         }
     }
 
@@ -306,6 +307,20 @@ private SortedSet<? extends Element> asSortedSet(Collection<? extends Element> m
         return out;
     }
 
+    private Content getSummaryLabel() {
+        return switch (kind) {
+            case FIELDS -> contents.fieldSummaryLabel;
+            case METHODS -> contents.methodSummary;
+            case CONSTRUCTORS -> contents.constructorSummaryLabel;
+            case ENUM_CONSTANTS -> contents.enumConstantSummary;
+            case NESTED_CLASSES -> contents.nestedClassSummary;
+            case PROPERTIES -> contents.propertySummaryLabel;
+            case ANNOTATION_TYPE_MEMBER_OPTIONAL -> contents.annotateTypeOptionalMemberSummaryLabel;
+            case ANNOTATION_TYPE_MEMBER_REQUIRED -> contents.annotateTypeRequiredMemberSummaryLabel;
+            default -> throw new IllegalArgumentException(kind.toString());
+        };
+    }
+
     /**
      * Returns the member summary header for the given class.
      *

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2024, 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
@@ -90,6 +90,8 @@ protected void buildAnnotationTypeMember(Content target) {
             addAnnotationDetailsMarker(target);
             Content annotationDetailsHeader = getAnnotationDetailsHeader();
             Content memberList = getMemberList();
+            writer.tableOfContents.addLink(HtmlIds.ANNOTATION_TYPE_ELEMENT_DETAIL, contents.annotationTypeDetailsLabel);
+            writer.tableOfContents.pushNestedList();
 
             for (Element member : members) {
                 currentMember = member;
@@ -98,9 +100,12 @@ protected void buildAnnotationTypeMember(Content target) {
                 buildAnnotationTypeMemberChildren(div);
                 annotationContent.add(div);
                 memberList.add(writer.getMemberListItem(annotationContent));
+                writer.tableOfContents.addLink(htmlIds.forMember(typeElement, (ExecutableElement) member),
+                        Text.of(name(member)));
             }
             Content annotationDetails = getAnnotationDetails(annotationDetailsHeader, memberList);
             target.add(annotationDetails);
+            writer.tableOfContents.popNestedList();
         }
     }
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2024, 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
@@ -34,6 +34,7 @@
 import java.util.TreeSet;
 
 import javax.lang.model.element.Element;
+import javax.lang.model.element.ModuleElement;
 import javax.lang.model.element.PackageElement;
 import javax.lang.model.element.TypeElement;
 import javax.tools.Diagnostic;
@@ -42,6 +43,7 @@
 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;
+import jdk.javadoc.internal.doclets.formats.html.markup.Text;
 import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
 import jdk.javadoc.internal.doclets.toolkit.DocletException;
 import jdk.javadoc.internal.doclets.toolkit.util.ClassTree;
@@ -418,14 +420,19 @@ protected HtmlTree getClassUseHeader() {
 
     @Override
     protected Navigation getNavBar(PageMode pageMode, Element element) {
-        Content mdleLinkContent = getModuleLink(utils.elementUtils.getModuleOf(typeElement),
-                contents.moduleLabel);
-        Content classLinkContent = getLink(new HtmlLinkInfo(
-                configuration, HtmlLinkInfo.Kind.PLAIN, typeElement)
-                .label(resources.getText("doclet.Class"))
-                .skipPreview(true));
-        return super.getNavBar(pageMode, element)
-                .setNavLinkModule(mdleLinkContent)
-                .setNavLinkClass(classLinkContent);
+        List<Content> subnavLinks = new ArrayList<>();
+        if (configuration.showModules) {
+            ModuleElement mdle = utils.elementUtils.getModuleOf(typeElement);
+            subnavLinks.add(getModuleLink(mdle, Text.of(mdle.getQualifiedName())));
+        }
+        PackageElement pkg = utils.containingPackage(typeElement);
+        subnavLinks.add(getPackageLink(pkg, getLocalizedPackageName(pkg)));
+        subnavLinks.add(getLink(
+                new HtmlLinkInfo(configuration, HtmlLinkInfo.Kind.PLAIN, typeElement)
+                        .style(HtmlStyle.currentSelection)
+                        .skipPreview(true)));
+
+        return super.getNavBar(pageMode, element).setSubNavLinks(subnavLinks);
     }
 }
+

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2024, 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
@@ -48,7 +48,6 @@
 
 import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
 import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
-import jdk.javadoc.internal.doclets.formats.html.markup.Entity;
 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlAttr;
 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
@@ -61,7 +60,6 @@
 import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
 import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
-import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable;
 
 /**
  * Generate the Class Information Page.
@@ -435,24 +433,6 @@ private void setRecordDocumentation(TypeElement elem) {
     protected Content getHeader(String header) {
         HtmlTree body = getBody(getWindowTitle(utils.getSimpleName(typeElement)));
         var div = HtmlTree.DIV(HtmlStyle.header);
-        if (configuration.showModules) {
-            ModuleElement mdle = configuration.docEnv.getElementUtils().getModuleOf(typeElement);
-            var classModuleLabel = HtmlTree.SPAN(HtmlStyle.moduleLabelInType, contents.moduleLabel);
-            var moduleNameDiv = HtmlTree.DIV(HtmlStyle.subTitle, classModuleLabel);
-            moduleNameDiv.add(Entity.NO_BREAK_SPACE);
-            moduleNameDiv.add(getModuleLink(mdle,
-                    Text.of(mdle.getQualifiedName())));
-            div.add(moduleNameDiv);
-        }
-        PackageElement pkg = utils.containingPackage(typeElement);
-        if (!pkg.isUnnamed()) {
-            var classPackageLabel = HtmlTree.SPAN(HtmlStyle.packageLabelInType, contents.packageLabel);
-            var pkgNameDiv = HtmlTree.DIV(HtmlStyle.subTitle, classPackageLabel);
-            pkgNameDiv.add(Entity.NO_BREAK_SPACE);
-            Content pkgNameContent = getPackageLink(pkg, getLocalizedPackageName(pkg));
-            pkgNameDiv.add(pkgNameContent);
-            div.add(pkgNameDiv);
-        }
         HtmlLinkInfo linkInfo = new HtmlLinkInfo(configuration,
                 HtmlLinkInfo.Kind.SHOW_TYPE_PARAMS_AND_BOUNDS, typeElement)
                 .linkToSelf(false);  // Let's not link to ourselves in the header
@@ -472,21 +452,17 @@ protected Content getClassContentHeader() {
 
     @Override
     protected Navigation getNavBar(PageMode pageMode, Element element) {
-        Content linkContent = getModuleLink(utils.elementUtils.getModuleOf(element),
-                contents.moduleLabel);
-        return super.getNavBar(pageMode, element)
-                .setNavLinkModule(linkContent)
-                .setSubNavLinks(() -> {
-                    List<Content> list = new ArrayList<>();
-                    VisibleMemberTable vmt = configuration.getVisibleMemberTable(typeElement);
-                    Set<VisibleMemberTable.Kind> summarySet =
-                            VisibleMemberTable.Kind.forSummariesOf(element.getKind());
-                    for (VisibleMemberTable.Kind kind : summarySet) {
-                        list.add(links.createLink(HtmlIds.forMemberSummary(kind),
-                                contents.getNavLinkLabelContent(kind), vmt.hasVisibleMembers(kind)));
-                    }
-                    return list;
-                });
+        List<Content> subnavLinks = new ArrayList<>();
+        if (configuration.showModules) {
+            ModuleElement mdle = configuration.docEnv.getElementUtils().getModuleOf(typeElement);
+            subnavLinks.add(getModuleLink(mdle, Text.of(mdle.getQualifiedName())));
+        }
+        PackageElement pkg = utils.containingPackage(typeElement);
+        subnavLinks.add(getPackageLink(pkg, getLocalizedPackageName(pkg)));
+        subnavLinks.add(getLink(new HtmlLinkInfo(configuration, HtmlLinkInfo.Kind.PLAIN, typeElement)
+                        .style(HtmlStyle.currentSelection)
+                        .skipPreview(true)));
+        return super.getNavBar(pageMode, element).setSubNavLinks(subnavLinks);
     }
 
     protected void addFooter() {
@@ -520,10 +496,13 @@ protected void addClassSignature(Content classInfo) {
 
     protected void addClassDescription(Content classInfo) {
         addPreviewInfo(classInfo);
+        tableOfContents.addLink(HtmlIds.TOP_OF_PAGE, contents.descriptionLabel);
         if (!options.noComment()) {
             // generate documentation for the class.
             if (!utils.getFullBody(typeElement).isEmpty()) {
+                tableOfContents.pushNestedList();
                 addInlineComment(typeElement, classInfo);
+                tableOfContents.popNestedList();
             }
         }
     }
@@ -535,7 +514,9 @@ private void addPreviewInfo(Content content) {
     protected void addClassTagInfo(Content classInfo) {
         if (!options.noComment()) {
             // Print Information about all the tags here
+            tableOfContents.pushNestedList();
             addTagsInfo(typeElement, classInfo);
+            tableOfContents.popNestedList();
         }
     }
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2001, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2001, 2024, 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
@@ -50,7 +50,6 @@
 import jdk.javadoc.internal.doclets.formats.html.markup.Text;
 import jdk.javadoc.internal.doclets.toolkit.DocletException;
 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
-import jdk.javadoc.internal.doclets.toolkit.util.DocLink;
 import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
 import jdk.javadoc.internal.doclets.toolkit.util.IndexItem;
 import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable;
@@ -144,16 +143,18 @@ protected void buildConstantSummary() throws DocletException {
      * Builds the list of contents for the groups of packages appearing in the constants summary page.
      */
     protected void buildContents() {
-        Content contentList = getContentsHeader();
+        tableOfContents.addLink(HtmlIds.TOP_OF_PAGE, Text.of(resources.getText("doclet.Constants_Summary")))
+                .pushNestedList();
         packageGroupHeadings.clear();
         for (PackageElement pkg : configuration.packages) {
             String abbrevPackageName = getAbbrevPackageName(pkg);
             if (hasConstantField(pkg) && !packageGroupHeadings.contains(abbrevPackageName)) {
-                addLinkToPackageContent(abbrevPackageName, contentList);
+                addLinkToTableOfContents(abbrevPackageName);
                 packageGroupHeadings.add(abbrevPackageName);
             }
         }
-        addContentsList(contentList);
+        tableOfContents.popNestedList();
+        bodyContents.setSideContent(tableOfContents.toContent(true));
     }
 
     /**
@@ -322,42 +323,27 @@ protected SortedSet<VariableElement> members() {
     }
 
      Content getHeader() {
-        String label = resources.getText("doclet.Constants_Summary");
-        HtmlTree body = getBody(getWindowTitle(label));
-        bodyContents.setHeader(getHeader(PageMode.CONSTANT_VALUES));
-        return body;
+         String label = resources.getText("doclet.Constants_Summary");
+         HtmlTree body = getBody(getWindowTitle(label));
+         bodyContents.setHeader(getHeader(PageMode.CONSTANT_VALUES));
+         Content titleContent = contents.constantsSummaryTitle;
+         var pHeading = HtmlTree.HEADING_TITLE(Headings.PAGE_TITLE_HEADING,
+                 HtmlStyle.title, titleContent);
+         var div = HtmlTree.DIV(HtmlStyle.header, pHeading);
+         bodyContents.addMainContent(div);
+         return body;
     }
 
-     Content getContentsHeader() {
+    Content getContentsHeader() {
         return HtmlTree.UL(HtmlStyle.contentsList);
     }
 
-     void addLinkToPackageContent(String abbrevPackageName, Content content) {
-        //add link to summary
-        Content link;
+    void addLinkToTableOfContents(String abbrevPackageName) {
         if (abbrevPackageName.isEmpty()) {
-            link = links.createLink(HtmlIds.UNNAMED_PACKAGE_ANCHOR,
-                    contents.defaultPackageLabel, "");
+            tableOfContents.addLink(HtmlIds.UNNAMED_PACKAGE_ANCHOR, contents.defaultPackageLabel);
         } else {
-            Content packageNameContent = Text.of(abbrevPackageName + ".*");
-            link = links.createLink(DocLink.fragment(abbrevPackageName),
-                    packageNameContent, "");
+            tableOfContents.addLink(HtmlId.of(abbrevPackageName), Text.of(abbrevPackageName + ".*"));
         }
-        content.add(HtmlTree.LI(link));
-    }
-
-     void addContentsList(Content content) {
-        Content titleContent = contents.constantsSummaryTitle;
-        var pHeading = HtmlTree.HEADING_TITLE(Headings.PAGE_TITLE_HEADING,
-                HtmlStyle.title, titleContent);
-        var div = HtmlTree.DIV(HtmlStyle.header, pHeading);
-        bodyContents.addMainContent(div);
-        Content headingContent = contents.contentsHeading;
-        var heading = HtmlTree.HEADING_TITLE(Headings.CONTENT_HEADING,
-                headingContent);
-        var section = HtmlTree.SECTION(HtmlStyle.packages, heading);
-        section.add(content);
-        bodyContents.addMainContent(section);
     }
 
      void addPackageGroup(String abbrevPackageName, Content toContent) {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2024, 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
@@ -102,6 +102,8 @@ protected void buildConstructorDoc(Content target) {
 
             Content constructorDetailsHeader = getConstructorDetailsHeader(target);
             Content memberList = getMemberList();
+            writer.tableOfContents.addLink(HtmlIds.CONSTRUCTOR_DETAIL, contents.constructorDetailsLabel);
+            writer.tableOfContents.pushNestedList();
 
             for (Element constructor : constructors) {
                 currentConstructor = (ExecutableElement)constructor;
@@ -114,9 +116,13 @@ protected void buildConstructorDoc(Content target) {
                 buildTagInfo(div);
                 constructorContent.add(div);
                 memberList.add(getMemberListItem(constructorContent));
+                writer.tableOfContents.addLink(htmlIds.forMember(currentConstructor),
+                        Text.of(utils.getSimpleName(constructor)
+                                + utils.makeSignature(currentConstructor, typeElement, false, true)));
             }
             Content constructorDetails = getConstructorDetails(constructorDetailsHeader, memberList);
             target.add(constructorDetails);
+            writer.tableOfContents.popNestedList();
         }
     }