stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8325325: Breadcrumb navigation shows preview link for modules and packages

Browse Source 
Reviewed-by: jjg
This commit is contained in:
Hannes Wallnöfer 2024-02-13 11:21:03 +00:00
parent 088e54f560
commit f8d8eecf80
11 changed files with 114 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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(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);
}

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

@ -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(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);
}

10
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DocFilesHandler.java
View File

@ -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(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);
}

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

@ -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}
*

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

@ -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() {

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

@ -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(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);
}
}

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

@ -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(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);
}

4
test/langtools/jdk/javadoc/doclet/testModules/TestModulePackages.java
View File

@ -172,7 +172,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("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,

2
test/langtools/jdk/javadoc/doclet/testNavigation/TestNavigation.java
View File

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

39
test/langtools/jdk/javadoc/doclet/testPreview/TestPreview.java
View File

@ -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
@ -85,11 +85,28 @@ 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">
@ -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

31
test/langtools/jdk/javadoc/doclet/testPreview/api/preview/package-info.java Normal file
View File

@ -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;