8343752: The javadoc should contain a note about usages of requires transitive java.base;
Co-authored-by: Mark Reinhold <mr@openjdk.org> Co-authored-by: Alex Buckley <abuckley@openjdk.org> Reviewed-by: hannesw, asotona
This commit is contained in:
Jan Lahoda
parent
8523880f06
commit
81342acdae
@ -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,11 +584,56 @@ public class ModuleWriter extends HtmlDocletWriter {
|
||||
TableHeader indirectPackagesHeader =
|
||||
new TableHeader(contents.fromLabel, contents.packagesLabel);
|
||||
if (display(indirectPackages)) {
|
||||
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<ModuleElement, SortedSet<PackageElement>> 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");
|
||||
var aopTable = getTable2(Text.of(aopText), indirectPackagesHeader);
|
||||
|
||||
@ -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 <code>java.base</code> module are associated \
|
||||
with the <code>requires transitive java.base</code> directive, which is \
|
||||
a preview feature of the Java language.<br>\
|
||||
Programs can only use <code>requires transitive java.base</code> when \
|
||||
preview features are enabled.<br>\
|
||||
Preview features may be removed in a future release, or upgraded \
|
||||
to permanent features of the Java Platform.<br>
|
||||
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.
|
||||
|
||||
@ -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 <code>java.base</code> module are");
|
||||
}
|
||||
}
|
||||
|
||||
@ -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;
|
||||
}
|
||||
Loading…
Reference in New Issue
Block a user