Skip to content

Commit 103da8f

Browse files
hnshns
committed
8274639: Provide a way to disable warnings for cross-modular links
Reviewed-by: jjg
1 parent 088b244 commit 103da8f

File tree

4 files changed

+124
-23
lines changed

4 files changed

+124
-23
lines changed

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -457,6 +457,14 @@ doclet.usage.linkoffline.parameters=\
457457
doclet.usage.linkoffline.description=\
458458
Link to docs at <url1> using package list at <url2>
459459

460+
# L10N: do not localize the option parameters: warn info
461+
doclet.usage.link-modularity-mismatch.parameters=\
462+
(warn|info)
463+
doclet.usage.link-modularity-mismatch.description=\
464+
Report external documentation with wrong modularity with either\n\
465+
a warning or informational message. The default behaviour is to\n\
466+
report a warning.
467+
460468
doclet.usage.link-platform-properties.parameters=\
461469
<url>
462470
doclet.usage.link-platform-properties.description=\

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseOptions.java‎

Lines changed: 44 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@
3636
import java.util.HashSet;
3737
import java.util.LinkedHashSet;
3838
import java.util.List;
39+
import java.util.Locale;
3940
import java.util.MissingResourceException;
4041
import java.util.Set;
4142
import java.util.StringTokenizer;
@@ -165,6 +166,20 @@ public abstract class BaseOptions {
165166
// A list of pairs containing urls and package list
166167
private final List<Utils.Pair<String, String>> linkOfflineList = new ArrayList<>();
167168

169+
/**
170+
* An enum of policies for handling modularity mismatches in external documentation.
171+
*/
172+
public enum ModularityMismatchPolicy {
173+
INFO,
174+
WARN
175+
}
176+
177+
/**
178+
* Argument for command-line option {@code --link-modularity-mismatch}.
179+
* Describes how to handle external documentation with non-matching modularity.
180+
*/
181+
private ModularityMismatchPolicy linkModularityMismatch = ModularityMismatchPolicy.WARN;
182+
168183
/**
169184
* Location of alternative platform link properties file.
170185
*/
@@ -403,6 +418,23 @@ public boolean process(String opt, List<String> args) {
403418
}
404419
},
405420

421+
new Option(resources, "--link-modularity-mismatch", 1) {
422+
@Override
423+
public boolean process(String opt, List<String> args) {
424+
String s = args.get(0);
425+
switch (s) {
426+
case "warn", "info" ->
427+
linkModularityMismatch = ModularityMismatchPolicy.valueOf(s.toUpperCase(Locale.ROOT));
428+
default -> {
429+
reporter.print(ERROR, resources.getText(
430+
"doclet.Option_invalid", s, "--link-modularity-mismatch"));
431+
return false;
432+
}
433+
}
434+
return true;
435+
}
436+
},
437+
406438
new Option(resources, "--link-platform-properties", 1) {
407439
@Override
408440
public boolean process(String opt, List<String> args) {
@@ -464,16 +496,13 @@ public boolean process(String opt, List<String> args) {
464496
public boolean process(String opt, List<String> args) {
465497
String o = args.get(0);
466498
switch (o) {
467-
case "summary":
468-
summarizeOverriddenMethods = true;
469-
break;
470-
case "detail":
471-
summarizeOverriddenMethods = false;
472-
break;
473-
default:
499+
case "summary" -> summarizeOverriddenMethods = true;
500+
case "detail" -> summarizeOverriddenMethods = false;
501+
default -> {
474502
reporter.print(ERROR,
475503
resources.getText("doclet.Option_invalid",o, "--override-methods"));
476504
return false;
505+
}
477506
}
478507
return true;
479508
}
@@ -827,6 +856,14 @@ List<Utils.Pair<String, String>> linkOfflineList() {
827856
return linkOfflineList;
828857
}
829858

859+
/**
860+
* Argument for command-line option {@code --link-modularity-mismatch}.
861+
* Describes how to handle external documentation with non-matching modularity.
862+
*/
863+
public ModularityMismatchPolicy linkModularityMismatch() {
864+
return linkModularityMismatch;
865+
}
866+
830867
/**
831868
* Argument for command-line option {@code --link-platform-properties}.
832869
*/

‎src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java‎

Lines changed: 17 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -514,7 +514,7 @@ private void readElementList(InputStream input, String path, boolean relative, i
514514
DocPath elempath;
515515
String moduleName = null;
516516
DocPath basePath = DocPath.create(path);
517-
boolean issueWarning = true;
517+
boolean showDiagnostic = true;
518518
while ((elemname = in.readLine()) != null) {
519519
if (elemname.length() > 0) {
520520
elempath = basePath;
@@ -534,14 +534,14 @@ private void readElementList(InputStream input, String path, boolean relative, i
534534
// For user provided libraries we check whether modularity matches the actual library.
535535
// We trust modularity to be correct for platform library element lists.
536536
if (platformVersion == 0) {
537-
actualModuleName = checkLinkCompatibility(elemname, moduleName, path, issueWarning);
537+
actualModuleName = checkLinkCompatibility(elemname, moduleName, path, showDiagnostic);
538538
} else {
539539
actualModuleName = moduleName == null ? DocletConstants.DEFAULT_ELEMENT_NAME : moduleName;
540540
}
541541
Item item = new Item(elemname, elempath, relative);
542542
packageItems.computeIfAbsent(actualModuleName, k -> new TreeMap<>())
543543
.putIfAbsent(elemname, item); // first-one-wins semantics
544-
issueWarning = false;
544+
showDiagnostic = false;
545545
}
546546
}
547547
}
@@ -556,25 +556,23 @@ private void readElementList(InputStream input, String path, boolean relative, i
556556
* @param packageName the package name
557557
* @param moduleName the module name or null
558558
* @param path the documentation path
559-
* @param issueWarning whether to print a warning in case of modularity mismatch
559+
* @param showDiagnostic whether to print a diagnostic message in case of modularity mismatch
560560
* @return the module name to use according to actual modularity of the package
561561
*/
562-
private String checkLinkCompatibility(String packageName, String moduleName, String path, boolean issueWarning) {
562+
private String checkLinkCompatibility(String packageName, String moduleName, String path, boolean showDiagnostic) {
563563
PackageElement pe = utils.elementUtils.getPackageElement(packageName);
564564
if (pe != null) {
565565
ModuleElement me = (ModuleElement)pe.getEnclosingElement();
566566
if (me == null || me.isUnnamed()) {
567-
if (moduleName != null && issueWarning) {
568-
configuration.getReporter().print(Kind.WARNING,
569-
resources.getText("doclet.linkMismatch_PackagedLinkedtoModule", path));
567+
if (moduleName != null && showDiagnostic) {
568+
printModularityMismatchDiagnostic("doclet.linkMismatch_PackagedLinkedtoModule", path);
570569
}
571570
// library is not modular, ignore module name even if documentation is modular
572571
return DocletConstants.DEFAULT_ELEMENT_NAME;
573572
} else if (moduleName == null) {
574-
// suppress the warning message in the case of automatic modules
575-
if (!utils.elementUtils.isAutomaticModule(me) && issueWarning) {
576-
configuration.getReporter().print(Kind.WARNING,
577-
resources.getText("doclet.linkMismatch_ModuleLinkedtoPackage", path));
573+
// suppress the diagnostic message in the case of automatic modules
574+
if (!utils.elementUtils.isAutomaticModule(me) && showDiagnostic) {
575+
printModularityMismatchDiagnostic("doclet.linkMismatch_ModuleLinkedtoPackage", path);
578576
}
579577
// library is modular, use module name for lookup even though documentation is not
580578
return utils.getModuleName(me);
@@ -659,4 +657,11 @@ private InputStream open(URL url) throws IOException {
659657

660658
return in;
661659
}
660+
661+
private void printModularityMismatchDiagnostic(String key, Object arg) {
662+
switch (configuration.getOptions().linkModularityMismatch()) {
663+
case INFO -> configuration.getMessages().notice(key, arg);
664+
case WARN -> configuration.getMessages().warning(key, arg);
665+
}
666+
}
662667
}

‎test/langtools/jdk/javadoc/doclet/testLinkOption/TestLinkOptionWithModule.java‎

Lines changed: 55 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright (c) 2018, 2020, Oracle and/or its affiliates. All rights reserved.
2+
* Copyright (c) 2018, 2021, Oracle and/or its affiliates. All rights reserved.
33
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
44
*
55
* This code is free software; you can redistribute it and/or modify it
@@ -23,7 +23,7 @@
2323

2424
/*
2525
* @test
26-
* @bug 8205593 8240169
26+
* @bug 8205593 8240169 8274639
2727
* @summary Javadoc -link makes broken links if module name matches package name
2828
* @library /tools/lib ../../lib
2929
* @modules
@@ -71,6 +71,7 @@ public void testModuleLinkedToModule(Path base) throws Exception {
7171
"--module", "com.ex1");
7272

7373
javadoc("-d", out2.toString(),
74+
"-Werror", "-Xdoclint:-missing",
7475
"--module-source-path", moduleSrc.toString(),
7576
"--module", "com.ex2",
7677
"-link", "../" + out1.getFileName());
@@ -109,13 +110,14 @@ public void testModuleLinkedToPackage(Path base) throws Exception {
109110
"-subpackages", "com.ex1");
110111

111112
javadoc("-d", out2.toString(),
113+
"--link-modularity-mismatch", "warn",
112114
"--module-source-path", moduleSrc.toString(),
113115
"--module", "com.ex2",
114116
"-link", "../" + out1.getFileName());
115117

116118
checkExit(Exit.OK);
117119
checkOutput(Output.OUT, true,
118-
"The code being documented uses modules but the packages defined "
120+
"warning: The code being documented uses modules but the packages defined "
119121
+ "in ../out3a/ are in the unnamed module");
120122
checkOutput("com.ex2/com/ex2/B.html", true,
121123
"""
@@ -137,13 +139,62 @@ public void testPackageLinkedToModule(Path base) throws Exception {
137139

138140
checkExit(Exit.OK);
139141
checkOutput(Output.OUT, true,
140-
"The code being documented uses packages in the unnamed module, but the packages defined "
142+
"warning: The code being documented uses packages in the unnamed module, but the packages defined "
141143
+ "in ../out4a/ are in named modules");
142144
checkOutput("com/ex2/B.html", true,
143145
"""
144146
<a href="../../../out4a/com.ex1/com/ex1/A.html" title="class or interface in com.ex1" class="external-link">A</a>""");
145147
}
146148

149+
@Test
150+
public void testModuleLinkedToPackageNoWarning(Path base) throws Exception {
151+
Path out1 = base.resolve("out5a"), out2 = base.resolve("out5b");
152+
153+
javadoc("-d", out1.toString(),
154+
"-sourcepath", packageSrc.toString(),
155+
"-subpackages", "com.ex1");
156+
157+
javadoc("-d", out2.toString(),
158+
"--link-modularity-mismatch", "info",
159+
"-Werror", "-Xdoclint:-missing",
160+
"--module-source-path", moduleSrc.toString(),
161+
"--module", "com.ex2",
162+
"-link", "../" + out1.getFileName());
163+
164+
checkExit(Exit.OK);
165+
checkOutput(Output.OUT, true,
166+
"The code being documented uses modules but the packages defined "
167+
+ "in ../out5a/ are in the unnamed module");
168+
checkOutput("com.ex2/com/ex2/B.html", true,
169+
"""
170+
<a href="../../../../out5a/com/ex1/A.html" title="class or interface in com.ex1" class="external-link">A</a>""");
171+
}
172+
173+
@Test
174+
public void testPackageLinkedToModuleNoWarning(Path base) throws Exception {
175+
Path out1 = base.resolve("out6a"), out2 = base.resolve("out6b");
176+
177+
javadoc("-d", out1.toString(),
178+
"--module-source-path", moduleSrc.toString(),
179+
"--module", "com.ex1");
180+
181+
javadoc("-d", out2.toString(),
182+
"--link-modularity-mismatch", "info",
183+
"-quiet", // should not print modularity mismatch info
184+
"-Werror", "-Xdoclint:-missing",
185+
"-sourcepath", packageSrc.toString(),
186+
"-subpackages", "com.ex2",
187+
"-link", "../" + out1.getFileName());
188+
189+
checkExit(Exit.OK);
190+
// Modularity mismatch diagnostic should not be printed because we're runnning with -quiet option
191+
checkOutput(Output.OUT, false,
192+
"The code being documented uses packages in the unnamed module, but the packages defined "
193+
+ "in ../out6a/ are in named modules");
194+
checkOutput("com/ex2/B.html", true,
195+
"""
196+
<a href="../../../out6a/com.ex1/com/ex1/A.html" title="class or interface in com.ex1" class="external-link">A</a>""");
197+
}
147198

148199
void initModulesAndPackages() throws Exception{
149200
new ModuleBuilder(tb, "com.ex1")

0 commit comments

Comments
 (0)