8325325: Breadcrumb navigation shows preview link for modules and packages

Reviewed-by: jjg

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

@@ -34,7 +34,6 @@ import java.util.SortedSet;
 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;
@@ -43,7 +42,6 @@ import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
 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;
@@ -422,15 +420,14 @@ public class ClassUseWriter extends SubWriterHolderWriter {
     protected Navigation getNavBar(PageMode pageMode, Element element) {
         List<Content> subnavLinks = new ArrayList<>();
         if (configuration.showModules) {
-            ModuleElement mdle = utils.elementUtils.getModuleOf(typeElement);
+            subnavLinks.add(getBreadcrumbLink(utils.elementUtils.getModuleOf(typeElement), false));
-            subnavLinks.add(getModuleLink(mdle, Text.of(mdle.getQualifiedName())));
+        }
+        // We may generate a class-use page for an otherwise undocumented page in the condition below.
+        boolean isUndocumented = options.noDeprecated() && utils.isDeprecated(typeElement);
+        subnavLinks.add(getBreadcrumbLink(utils.containingPackage(typeElement), isUndocumented));
+        if (!isUndocumented) {
+            subnavLinks.add(getBreadcrumbLink(typeElement, true));
         }
-        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

@@ -35,7 +35,6 @@ import java.util.stream.Collectors;
 
 import javax.lang.model.element.Element;
 import javax.lang.model.element.ExecutableElement;
-import javax.lang.model.element.ModuleElement;
 import javax.lang.model.element.Name;
 import javax.lang.model.element.PackageElement;
 import javax.lang.model.element.TypeElement;
@@ -454,14 +453,10 @@ public class ClassWriter extends SubWriterHolderWriter {
     protected Navigation getNavBar(PageMode pageMode, Element element) {
         List<Content> subnavLinks = new ArrayList<>();
         if (configuration.showModules) {
-            ModuleElement mdle = configuration.docEnv.getElementUtils().getModuleOf(typeElement);
+            subnavLinks.add(getBreadcrumbLink(utils.elementUtils.getModuleOf(typeElement), false));
-            subnavLinks.add(getModuleLink(mdle, Text.of(mdle.getQualifiedName())));
         }
-        PackageElement pkg = utils.containingPackage(typeElement);
+        subnavLinks.add(getBreadcrumbLink(utils.containingPackage(typeElement), false));
-        subnavLinks.add(getPackageLink(pkg, getLocalizedPackageName(pkg)));
+        subnavLinks.add(getBreadcrumbLink(typeElement, true));
-        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/DocFilesHandler.java

@@ -30,9 +30,7 @@ import com.sun.source.doctree.EndElementTree;
 import com.sun.source.doctree.StartElementTree;
 import com.sun.source.util.DocTreeFactory;
 import jdk.javadoc.internal.doclets.formats.html.markup.BodyContents;
-import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
-import jdk.javadoc.internal.doclets.formats.html.markup.Text;
 import jdk.javadoc.internal.doclets.toolkit.DocFileElement;
 import jdk.javadoc.internal.doclets.toolkit.DocletException;
 import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
@@ -220,14 +218,10 @@ public class DocFilesHandler {
             List<Content> subnavLinks = new ArrayList<>();
             var pkg = dfElement.getPackageElement();
             if (configuration.showModules) {
-                var mdle = utils.elementUtils.getModuleOf(element);
+                subnavLinks.add(getBreadcrumbLink(utils.elementUtils.getModuleOf(element), pkg.isUnnamed()));
-                subnavLinks.add(links.createLink(pathToRoot.resolve(docPaths.moduleSummary(mdle)),
-                        Text.of(mdle.getQualifiedName()),
-                        pkg.isUnnamed() ? HtmlStyle.currentSelection : null, ""));
             }
             if (!pkg.isUnnamed()) {
-                subnavLinks.add(links.createLink(pathString(pkg, DocPaths.PACKAGE_SUMMARY),
+                subnavLinks.add(getBreadcrumbLink(pkg, true));
-                        getLocalizedPackageName(pkg), HtmlStyle.currentSelection, ""));
             }
             return super.getNavBar(pageMode, element).setSubNavLinks(subnavLinks);
         }

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

@@ -31,7 +31,6 @@ import java.util.Comparator;
 import java.util.EnumSet;
 import java.util.HashMap;
 import java.util.HashSet;
-import java.util.LinkedHashMap;
 import java.util.LinkedList;
 import java.util.List;
 import java.util.ListIterator;
@@ -84,13 +83,11 @@ import com.sun.source.util.SimpleDocTreeVisitor;
 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.Head;
-import jdk.javadoc.internal.doclets.formats.html.markup.HtmlAttr;
 import jdk.javadoc.internal.doclets.formats.html.markup.HtmlDocument;
 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.HtmlTree;
 import jdk.javadoc.internal.doclets.formats.html.markup.Links;
-import jdk.javadoc.internal.doclets.formats.html.markup.ListBuilder;
 import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
 import jdk.javadoc.internal.doclets.formats.html.markup.Script;
 import jdk.javadoc.internal.doclets.formats.html.markup.TagName;
@@ -634,6 +631,29 @@ public abstract class HtmlDocletWriter {
         return pathToRoot.resolve(docPaths.forPackage(packageElement).resolve(name));
     }
 
+    /**
+     * {@return a content element containing a breadcrumb navigtation link for {@code elem}}
+     * Only module, package and type elements can appear in breadcrumb navigation.
+     *
+     * @param elem the element
+     * @param selected whether to use the style for current page element
+     */
+    protected Content getBreadcrumbLink(Element elem, boolean selected) {
+        HtmlTree link = switch (elem) {
+            case ModuleElement mdle -> links.createLink(pathToRoot.resolve(docPaths.moduleSummary(mdle)),
+                    Text.of(mdle.getQualifiedName()));
+            case PackageElement pkg -> links.createLink(pathString(pkg, DocPaths.PACKAGE_SUMMARY),
+                    getLocalizedPackageName(pkg));
+            case TypeElement type -> links.createLink(pathString(type, docPaths.forName(type)),
+                    utils.getSimpleName(type));
+            default -> throw new IllegalArgumentException(Objects.toString(elem));
+        };
+        if (selected) {
+            link.setStyle(HtmlStyle.currentSelection);
+        }
+        return link;
+    }
+
     /**
      * {@return the link to the given package}
      *

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

@@ -277,10 +277,7 @@ public class ModuleWriter extends HtmlDocletWriter {
     @Override
     protected Navigation getNavBar(PageMode pageMode, Element element) {
         return super.getNavBar(pageMode, element)
-                .setSubNavLinks(List.of(
+                .setSubNavLinks(List.of(getBreadcrumbLink(mdle, true)));
-                    links.createLink(pathToRoot.resolve(docPaths.moduleSummary(mdle)),
-                            Text.of(mdle.getQualifiedName()),
-                            HtmlStyle.currentSelection, "")));
     }
 
     protected Content getContentHeader() {

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

@@ -220,11 +220,9 @@ public class PackageUseWriter extends SubWriterHolderWriter {
     protected Navigation getNavBar(PageMode pageMode, Element element) {
         List<Content> subnavLinks = new ArrayList<>();
         if (configuration.showModules) {
-            var mdle = utils.elementUtils.getModuleOf(packageElement);
+            subnavLinks.add(getBreadcrumbLink(utils.elementUtils.getModuleOf(packageElement), false));
-            subnavLinks.add(getModuleLink(mdle, Text.of(mdle.getQualifiedName())));
         }
-        subnavLinks.add(links.createLink(pathString(packageElement, DocPaths.PACKAGE_SUMMARY),
+        subnavLinks.add(getBreadcrumbLink(packageElement, true));
-                getLocalizedPackageName(packageElement), HtmlStyle.currentSelection, ""));
         return super.getNavBar(pageMode, element).setSubNavLinks(subnavLinks);
     }
 }

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

@@ -272,12 +272,9 @@ public class PackageWriter extends HtmlDocletWriter {
     protected Navigation getNavBar(PageMode pageMode, Element element) {
         List<Content> subnavLinks = new ArrayList<>();
         if (configuration.showModules) {
-            ModuleElement mdle = configuration.docEnv.getElementUtils().getModuleOf(packageElement);
+            subnavLinks.add(getBreadcrumbLink(utils.elementUtils.getModuleOf(packageElement), false));
-            subnavLinks.add(links.createLink(pathToRoot.resolve(docPaths.moduleSummary(mdle)),
-                    Text.of(mdle.getQualifiedName())));
         }
-        subnavLinks.add(links.createLink(pathString(packageElement, DocPaths.PACKAGE_SUMMARY),
+        subnavLinks.add(getBreadcrumbLink(packageElement, true));
-                getLocalizedPackageName(packageElement), HtmlStyle.currentSelection, ""));
         return super.getNavBar(pageMode, element).setSubNavLinks(subnavLinks);
     }
 

test/langtools/jdk/javadoc/doclet/testModules/TestModulePackages.java

@@ -172,7 +172,7 @@ public class TestModulePackages extends JavadocTester {
                      > 
                     <li><a href="package-summary.html">p</a></li>
                     &nbsp;&gt;&nbsp;
-                    <li><a href="C.html" class="current-selection" title="class in p">C</a></li>
+                    <li><a href="C.html" class="current-selection">C</a></li>
                     </ol>
                     """);
         checkOutput("o/p/C.html", true,
@@ -182,7 +182,7 @@ public class TestModulePackages extends JavadocTester {
                     &nbsp;&gt;&nbsp;
                     <li><a href="package-summary.html">p</a></li>
                     &nbsp;&gt;&nbsp;
-                    <li><a href="C.html" class="current-selection" title="class in p">C</a></li>
+                    <li><a href="C.html" class="current-selection">C</a></li>
                     </ol>
                     """);
         checkOutput("type-search-index.js", true,

test/langtools/jdk/javadoc/doclet/testNavigation/TestNavigation.java

@@ -412,7 +412,7 @@ public class TestNavigation extends JavadocTester {
                     <ol class="sub-nav-list">
                     <li><a href="package-summary.html">Unnamed Package</a></li>
                     &nbsp;&gt;&nbsp;
-                    <li><a href="C.html" class="current-selection" title="class in Unnamed Package">C</a></li>
+                    <li><a href="C.html" class="current-selection">C</a></li>
                     </ol>""");
     }
 

test/langtools/jdk/javadoc/doclet/testPreview/TestPreview.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2022, 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
@@ -23,7 +23,7 @@
 
 /*
  * @test
- * @bug      8250768 8261976 8277300 8282452 8287597
+ * @bug      8250768 8261976 8277300 8282452 8287597 8325325
  * @summary  test generated docs for items declared using preview
  * @library  ../../lib
  * @modules jdk.javadoc/jdk.javadoc.internal.tool
@@ -77,7 +77,7 @@ public class TestPreview extends JavadocTester {
         checkExit(Exit.OK);
 
         checkOutput("preview-list.html", true,
-                    """
+                """
                     <ul class="preview-feature-list">
                     <li><label for="feature-1">
                     <input type="checkbox" id="feature-1" disabled checked onclick="toggleGlobal(this, '1', 3)">
@@ -85,12 +85,29 @@ public class TestPreview extends JavadocTester {
                     </ul>
                     <h2 title="Contents">Contents</h2>
                     <ul class="contents-list">
+                    <li id="contents-package"><a href="#package">Packages</a></li>
                     <li id="contents-class"><a href="#class">Classes</a></li>
                     <li id="contents-record-class"><a href="#record-class">Record Classes</a></li>
                     <li id="contents-method"><a href="#method">Methods</a></li>
                     </ul>
                     """,
-                    """
+                """
+                    <div id="package">
+                    <div class="table-tabs" role="tablist" aria-orientation="horizontal">
+                    <div class="caption"><span>Packages</span></div>
+                    </div>
+                    <div id="package.tabpanel" role="tabpanel" aria-labelledby="package-tab0">
+                    <div class="summary-table three-column-summary">
+                    <div class="table-header col-first sort-asc" onclick="sortTable(this, 0, 3)">Package</div>
+                    <div class="table-header col-second" onclick="sortTable(this, 1, 3)">Preview Feature</div>
+                    <div class="table-header col-last">Description</div>
+                    <div class="col-summary-item-name even-row-color package package-tab1"><a href="java.base/preview/package-summary.html">preview</a><sup><a href="java.base/preview/package-summary.html#preview-preview">PREVIEW</a></sup></div>
+                    <div class="col-second even-row-color package package-tab1">Test Feature</div>
+                    <div class="col-last even-row-color package package-tab1">
+                    <div class="block">Preview package.</div>
+                    </div>
+                    """,
+                """
                     <div id="record-class">
                     <div class="table-tabs" role="tablist" aria-orientation="horizontal">
                     <div class="caption"><span>Record Classes</span></div>
@@ -105,7 +122,7 @@ public class TestPreview extends JavadocTester {
                     <div class="col-last even-row-color record-class record-class-tab1"></div>
                     </div>
                     """,
-                    """
+                """
                     <div id="method">
                     <div class="table-tabs" role="tablist" aria-orientation="horizontal">
                     <div class="caption"><span>Methods</span></div>
@@ -121,6 +138,24 @@ public class TestPreview extends JavadocTester {
                     <div class="block">Returns the value of the <code>i</code> record component.</div>
                     </div>
                     """);
+
+        // 8325325: Breadcrumb navigation links should not contain PREVIEW link
+        checkOutput("java.base/preview/package-summary.html", true,
+                """
+                    <ol class="sub-nav-list">
+                    <li><a href="../module-summary.html">java.base</a></li>
+                    &nbsp;&gt;&nbsp;
+                    <li><a href="package-summary.html" class="current-selection">preview</a></li>
+                    </ol>""");
+        checkOutput("java.base/preview/Core.html", true,
+                """
+                    <ol class="sub-nav-list">
+                    <li><a href="../module-summary.html">java.base</a></li>
+                    &nbsp;&gt;&nbsp;
+                    <li><a href="package-summary.html">preview</a></li>
+                    &nbsp;&gt;&nbsp;
+                    <li><a href="Core.html" class="current-selection">Core</a></li>
+                    </ol>""");
     }
 
     @Test

test/langtools/jdk/javadoc/doclet/testPreview/api/preview/package-info.java

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/**
+ * Preview package.
+ */
+@PreviewFeature(feature=Feature.TEST)
+package preview;
+
+import jdk.internal.javac.PreviewFeature;
+import jdk.internal.javac.PreviewFeature.Feature;