From 81342acdae82262815e04e1ade7deb2d0f24094a Mon Sep 17 00:00:00 2001 From: Jan Lahoda Date: Thu, 14 Nov 2024 11:29:54 +0000 Subject: [PATCH] 8343752: The javadoc should contain a note about usages of requires transitive java.base; Co-authored-by: Mark Reinhold Co-authored-by: Alex Buckley Reviewed-by: hannesw, asotona --- .../doclets/formats/html/ModuleWriter.java | 57 +++++++++++++++++-- .../html/resources/standard.properties | 8 +++ .../doclet/testPreview/TestPreview.java | 15 +++++ .../m/module-info.java | 25 ++++++++ 4 files changed, 100 insertions(+), 5 deletions(-) create mode 100644 test/langtools/jdk/javadoc/doclet/testPreview/requiresTransitiveJavaBase/m/module-info.java 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 b688420681f..30de66b46a6 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 @@ -41,6 +41,7 @@ import javax.lang.model.util.ElementFilter; import com.sun.source.doctree.DeprecatedTree; import com.sun.source.doctree.DocTree; +import java.util.stream.Collectors; import jdk.javadoc.doclet.DocletEnvironment.ModuleMode; import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode; @@ -52,9 +53,10 @@ import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.html.Content; import jdk.javadoc.internal.html.ContentBuilder; import jdk.javadoc.internal.html.Entity; +import jdk.javadoc.internal.html.HtmlId; import jdk.javadoc.internal.html.HtmlStyle; -import jdk.javadoc.internal.html.HtmlTag; import jdk.javadoc.internal.html.HtmlTree; +import jdk.javadoc.internal.html.RawHtml; import jdk.javadoc.internal.html.Text; /** @@ -582,10 +584,55 @@ public class ModuleWriter extends HtmlDocletWriter { TableHeader indirectPackagesHeader = new TableHeader(contents.fromLabel, contents.packagesLabel); if (display(indirectPackages)) { - String aepText = resources.getText("doclet.Indirect_Exports_Summary"); - var aepTable = getTable2(Text.of(aepText), indirectPackagesHeader); - addIndirectPackages(aepTable, indirectPackages); - section.add(aepTable); + ModuleElement javaBase = this.utils.elementUtils.getModuleElement("java.base"); + boolean hasRequiresTransitiveJavaBase = + ElementFilter.requiresIn(mdle.getDirectives()) + .stream() + .anyMatch(rd -> rd.isTransitive() && + javaBase.equals(rd.getDependency())); + if (hasRequiresTransitiveJavaBase) { + Map> filteredIndirectPackages = + indirectPackages.entrySet() + .stream() + .filter(e -> !e.getKey().equals(javaBase)) + .collect(Collectors.toMap(e -> e.getKey(), e -> e.getValue())); + String aepText = resources.getText("doclet.Indirect_Exports_Summary"); + var aepTable = getTable2(Text.of(aepText), indirectPackagesHeader); + addIndirectPackages(aepTable, filteredIndirectPackages); + section.add(aepTable); + //add the preview box: + section.add(HtmlTree.BR()); + section.add(HtmlTree.BR()); + HtmlId previewRequiresTransitiveId = HtmlId.of("preview-requires-transitive-java.base"); + var previewDiv = HtmlTree.DIV(HtmlStyles.previewBlock); + previewDiv.setId(previewRequiresTransitiveId); + + Content note = + RawHtml.of(resources.getText("doclet.PreviewJavaSERequiresTransitiveJavaBase")); + + previewDiv.add(HtmlTree.DIV(HtmlStyles.previewComment, note)); + section.add(previewDiv); + + //add the Indirect Exports + filteredIndirectPackages = + indirectPackages.entrySet() + .stream() + .filter(e -> e.getKey().equals(javaBase)) + .collect(Collectors.toMap(e -> e.getKey(), e -> e.getValue())); + String aepPreviewText = resources.getText("doclet.Indirect_Exports_Summary"); + ContentBuilder tableCaption = new ContentBuilder( + Text.of(aepPreviewText), + HtmlTree.SUP(links.createLink(previewRequiresTransitiveId, + contents.previewMark))); + var aepPreviewTable = getTable2(tableCaption, indirectPackagesHeader); + addIndirectPackages(aepPreviewTable, filteredIndirectPackages); + section.add(aepPreviewTable); + } else { + String aepText = resources.getText("doclet.Indirect_Exports_Summary"); + var aepTable = getTable2(Text.of(aepText), indirectPackagesHeader); + addIndirectPackages(aepTable, indirectPackages); + section.add(aepTable); + } } if (display(indirectOpenPackages)) { String aopText = resources.getText("doclet.Indirect_Opens_Summary"); diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties index e6faa7bbe19..44f285f21db 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties @@ -431,6 +431,14 @@ doclet.ReflectivePreviewAPI={0} refers to one or more reflective preview APIs: doclet.UsesDeclaredUsingPreview={0} refers to one or more types which are declared using a preview feature of the Java language: {1}. doclet.PreviewTrailingNote1=Programs can only use {0} when preview features are enabled. doclet.PreviewTrailingNote2=Preview features may be removed in a future release, or upgraded to permanent features of the Java platform. +doclet.PreviewJavaSERequiresTransitiveJavaBase=\ +Indirect exports from the java.base module are associated \ +with the requires transitive java.base directive, which is \ +a preview feature of the Java language.
\ +Programs can only use requires transitive java.base when \ +preview features are enabled.
\ +Preview features may be removed in a future release, or upgraded \ +to permanent features of the Java Platform.
doclet.RestrictedMethod=restricted method doclet.RestrictedLeadingNote={0} is a {1} of the Java platform. doclet.RestrictedTrailingNote1=Programs can only use {0} when access to restricted methods is enabled. diff --git a/test/langtools/jdk/javadoc/doclet/testPreview/TestPreview.java b/test/langtools/jdk/javadoc/doclet/testPreview/TestPreview.java index 369312d690a..79658e4c606 100644 --- a/test/langtools/jdk/javadoc/doclet/testPreview/TestPreview.java +++ b/test/langtools/jdk/javadoc/doclet/testPreview/TestPreview.java @@ -33,6 +33,7 @@ * @run main TestPreview */ +import java.nio.file.Path; import java.nio.file.Paths; import javadoc.tester.JavadocTester; @@ -209,4 +210,18 @@ public class TestPreview extends JavadocTester { checkOutput("java.base/preview/NoPreview.html", false, "refers to one or more preview"); } + + @Test + public void testRequiresTransitiveJavaBase() { + Path src = Paths.get(testSrc, "requiresTransitiveJavaBase"); + javadoc("-d", "out-requires-transitive-java-base", + "-XDforcePreview", "--enable-preview", "-source", System.getProperty("java.specification.version"), + "--module-source-path", src.toString(), + "--module", "m", + "--expand-requires", "transitive"); + checkExit(Exit.OK); + + checkOutput("m/module-summary.html", true, + "Indirect exports from the java.base module are"); + } } diff --git a/test/langtools/jdk/javadoc/doclet/testPreview/requiresTransitiveJavaBase/m/module-info.java b/test/langtools/jdk/javadoc/doclet/testPreview/requiresTransitiveJavaBase/m/module-info.java new file mode 100644 index 00000000000..d1576ff8c3e --- /dev/null +++ b/test/langtools/jdk/javadoc/doclet/testPreview/requiresTransitiveJavaBase/m/module-info.java @@ -0,0 +1,25 @@ +/* + * 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. + */ +module m { + requires transitive java.base; +}