From f8d8eecf8041a8baa76ba0091f2842dcb0275cb3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hannes=20Walln=C3=B6fer?= Date: Tue, 13 Feb 2024 11:21:03 +0000 Subject: [PATCH] 8325325: Breadcrumb navigation shows preview link for modules and packages Reviewed-by: jjg --- .../doclets/formats/html/ClassUseWriter.java | 17 +++---- .../doclets/formats/html/ClassWriter.java | 11 ++--- .../doclets/formats/html/DocFilesHandler.java | 10 +---- .../formats/html/HtmlDocletWriter.java | 26 +++++++++-- .../doclets/formats/html/ModuleWriter.java | 5 +-- .../formats/html/PackageUseWriter.java | 6 +-- .../doclets/formats/html/PackageWriter.java | 7 +-- .../testModules/TestModulePackages.java | 4 +- .../doclet/testNavigation/TestNavigation.java | 2 +- .../doclet/testPreview/TestPreview.java | 45 ++++++++++++++++--- .../testPreview/api/preview/package-info.java | 31 +++++++++++++ 11 files changed, 114 insertions(+), 50 deletions(-) create mode 100644 test/langtools/jdk/javadoc/doclet/testPreview/api/preview/package-info.java diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java index e0b126dfacf..ddc8710e517 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java +++ b/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 subnavLinks = new ArrayList<>(); if (configuration.showModules) { - ModuleElement mdle = utils.elementUtils.getModuleOf(typeElement); - subnavLinks.add(getModuleLink(mdle, Text.of(mdle.getQualifiedName()))); + subnavLinks.add(getBreadcrumbLink(utils.elementUtils.getModuleOf(typeElement), false)); + } + // 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); } diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriter.java index f74921464bb..b550b35e4d3 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriter.java +++ b/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 subnavLinks = new ArrayList<>(); if (configuration.showModules) { - ModuleElement mdle = configuration.docEnv.getElementUtils().getModuleOf(typeElement); - subnavLinks.add(getModuleLink(mdle, Text.of(mdle.getQualifiedName()))); + subnavLinks.add(getBreadcrumbLink(utils.elementUtils.getModuleOf(typeElement), false)); } - 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))); + subnavLinks.add(getBreadcrumbLink(utils.containingPackage(typeElement), false)); + subnavLinks.add(getBreadcrumbLink(typeElement, true)); return super.getNavBar(pageMode, element).setSubNavLinks(subnavLinks); } diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DocFilesHandler.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DocFilesHandler.java index 93fd296280b..47b2b6b41fe 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DocFilesHandler.java +++ b/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 subnavLinks = new ArrayList<>(); var pkg = dfElement.getPackageElement(); if (configuration.showModules) { - var mdle = utils.elementUtils.getModuleOf(element); - subnavLinks.add(links.createLink(pathToRoot.resolve(docPaths.moduleSummary(mdle)), - Text.of(mdle.getQualifiedName()), - pkg.isUnnamed() ? HtmlStyle.currentSelection : null, "")); + subnavLinks.add(getBreadcrumbLink(utils.elementUtils.getModuleOf(element), pkg.isUnnamed())); } if (!pkg.isUnnamed()) { - subnavLinks.add(links.createLink(pathString(pkg, DocPaths.PACKAGE_SUMMARY), - getLocalizedPackageName(pkg), HtmlStyle.currentSelection, "")); + subnavLinks.add(getBreadcrumbLink(pkg, true)); } return super.getNavBar(pageMode, element).setSubNavLinks(subnavLinks); } diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java index 73ce7bb784f..4eb05aeb695 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java +++ b/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} * diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriter.java index bf362e478ff..24718c089bc 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriter.java +++ b/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( - links.createLink(pathToRoot.resolve(docPaths.moduleSummary(mdle)), - Text.of(mdle.getQualifiedName()), - HtmlStyle.currentSelection, ""))); + .setSubNavLinks(List.of(getBreadcrumbLink(mdle, true))); } protected Content getContentHeader() { diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageUseWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageUseWriter.java index 75009ad2066..e8705923d94 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageUseWriter.java +++ b/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 subnavLinks = new ArrayList<>(); if (configuration.showModules) { - var mdle = utils.elementUtils.getModuleOf(packageElement); - subnavLinks.add(getModuleLink(mdle, Text.of(mdle.getQualifiedName()))); + subnavLinks.add(getBreadcrumbLink(utils.elementUtils.getModuleOf(packageElement), false)); } - subnavLinks.add(links.createLink(pathString(packageElement, DocPaths.PACKAGE_SUMMARY), - getLocalizedPackageName(packageElement), HtmlStyle.currentSelection, "")); + subnavLinks.add(getBreadcrumbLink(packageElement, true)); return super.getNavBar(pageMode, element).setSubNavLinks(subnavLinks); } } diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriter.java index f9d3164a1d5..2983eeaaf58 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriter.java +++ b/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 subnavLinks = new ArrayList<>(); if (configuration.showModules) { - ModuleElement mdle = configuration.docEnv.getElementUtils().getModuleOf(packageElement); - subnavLinks.add(links.createLink(pathToRoot.resolve(docPaths.moduleSummary(mdle)), - Text.of(mdle.getQualifiedName()))); + subnavLinks.add(getBreadcrumbLink(utils.elementUtils.getModuleOf(packageElement), false)); } - subnavLinks.add(links.createLink(pathString(packageElement, DocPaths.PACKAGE_SUMMARY), - getLocalizedPackageName(packageElement), HtmlStyle.currentSelection, "")); + subnavLinks.add(getBreadcrumbLink(packageElement, true)); return super.getNavBar(pageMode, element).setSubNavLinks(subnavLinks); } diff --git a/test/langtools/jdk/javadoc/doclet/testModules/TestModulePackages.java b/test/langtools/jdk/javadoc/doclet/testModules/TestModulePackages.java index 810d24c672e..b4367efa9f7 100644 --- a/test/langtools/jdk/javadoc/doclet/testModules/TestModulePackages.java +++ b/test/langtools/jdk/javadoc/doclet/testModules/TestModulePackages.java @@ -172,7 +172,7 @@ public class TestModulePackages extends JavadocTester {  > 
  • p
    •  >  -
  • C
    • +
  • C
    • """); checkOutput("o/p/C.html", true, @@ -182,7 +182,7 @@ public class TestModulePackages extends JavadocTester {  > 
  • p
    •  >  -
  • C
    • +
  • C
    • """); checkOutput("type-search-index.js", true, diff --git a/test/langtools/jdk/javadoc/doclet/testNavigation/TestNavigation.java b/test/langtools/jdk/javadoc/doclet/testNavigation/TestNavigation.java index 157bf956c53..53cd7e204eb 100644 --- a/test/langtools/jdk/javadoc/doclet/testNavigation/TestNavigation.java +++ b/test/langtools/jdk/javadoc/doclet/testNavigation/TestNavigation.java @@ -412,7 +412,7 @@ public class TestNavigation extends JavadocTester {
    1. Unnamed Package
      2.  >  -
    2. C
      3. +
    3. C
    """); } diff --git a/test/langtools/jdk/javadoc/doclet/testPreview/TestPreview.java b/test/langtools/jdk/javadoc/doclet/testPreview/TestPreview.java index f8f9d80e1e4..76d422eb5a9 100644 --- a/test/langtools/jdk/javadoc/doclet/testPreview/TestPreview.java +++ b/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, - """ + """

    Contents

    """, - """ + """ +
    +
    +
    Packages
    +
    +
    +
    +
    Package
    +
    Preview Feature
    +
    Description
    +
    previewPREVIEW
    +
    Test Feature
    +
    +
    Preview package.
    +
    + """, + """
    Record Classes
    @@ -105,7 +122,7 @@ public class TestPreview extends JavadocTester {
    """, - """ + """
    Methods
    @@ -121,6 +138,24 @@ public class TestPreview extends JavadocTester {
    Returns the value of the i record component.
    """); + + // 8325325: Breadcrumb navigation links should not contain PREVIEW link + checkOutput("java.base/preview/package-summary.html", true, + """ +
      +
    1. java.base
      2. +  >  +
    2. preview
      3. +
    """); + checkOutput("java.base/preview/Core.html", true, + """ +
      +
    1. java.base
      2. +  >  +
    2. preview
      3. +  >  +
    3. Core
      4. +
    """); } @Test diff --git a/test/langtools/jdk/javadoc/doclet/testPreview/api/preview/package-info.java b/test/langtools/jdk/javadoc/doclet/testPreview/api/preview/package-info.java new file mode 100644 index 00000000000..050d5512013 --- /dev/null +++ b/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;