8129909: Add -Xdoclint/package: to javadoc
Summary: Adding -Xdoclint/package: command line option, similar to the javac -Xdoclint/package: option, to javadoc.
Reviewed-by: darcy, jjg, ksrini
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/doclint/DocLint.java Mon Jul 13 16:57:52 2015 +0400
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/doclint/DocLint.java Mon Jul 13 16:33:42 2015 +0200
@@ -344,6 +344,10 @@
checker.scan(dc, p);
}
+ public boolean shouldCheck(CompilationUnitTree unit) {
+ return env.shouldCheck(unit);
+ }
+
public void reportStats(PrintWriter out) {
env.messages.reportStats(out);
}
@@ -406,26 +410,8 @@
@Override @DefinedBy(Api.COMPILER_TREE)
public Void visitCompilationUnit(CompilationUnitTree node, Void p) {
- if (env.includePackages != null) {
- String packageName = node.getPackageName() != null
- ? node.getPackageName().toString()
- : "";
- if (!env.includePackages.isEmpty()) {
- boolean included = false;
- for (Pattern pack : env.includePackages) {
- if (pack.matcher(packageName).matches()) {
- included = true;
- break;
- }
- }
- if (!included)
- return null;
- }
- for (Pattern pack : env.excludePackages) {
- if (pack.matcher(packageName).matches()) {
- return null;
- }
- }
+ if (!env.shouldCheck(node)) {
+ return null;
}
return super.visitCompilationUnit(node, p);
}
--- a/langtools/src/jdk.compiler/share/classes/com/sun/tools/doclint/Env.java Mon Jul 13 16:57:52 2015 +0400
+++ b/langtools/src/jdk.compiler/share/classes/com/sun/tools/doclint/Env.java Mon Jul 13 16:33:42 2015 +0200
@@ -43,6 +43,7 @@
import javax.tools.Diagnostic.Kind;
import com.sun.source.doctree.DocCommentTree;
+import com.sun.source.tree.CompilationUnitTree;
import com.sun.source.util.DocTrees;
import com.sun.source.util.JavacTask;
import com.sun.source.util.SourcePositions;
@@ -229,6 +230,35 @@
return sp.getStartPosition(p.getCompilationUnit(), p.getLeaf());
}
+ boolean shouldCheck(CompilationUnitTree unit) {
+ if (includePackages == null)
+ return true;
+
+ String packageName = unit.getPackageName() != null
+ ? unit.getPackageName().toString()
+ : "";
+
+ if (!includePackages.isEmpty()) {
+ boolean included = false;
+ for (Pattern pack : includePackages) {
+ if (pack.matcher(packageName).matches()) {
+ included = true;
+ break;
+ }
+ }
+ if (!included)
+ return false;
+ }
+
+ for (Pattern pack : excludePackages) {
+ if (pack.matcher(packageName).matches()) {
+ return false;
+ }
+ }
+
+ return true;
+ }
+
private <T extends Comparable<T>> T min(T item1, T item2) {
return (item1 == null) ? item2
: (item2 == null) ? item1
--- a/langtools/src/jdk.javadoc/share/classes/com/sun/tools/doclets/formats/html/ConfigurationImpl.java Mon Jul 13 16:57:52 2015 +0400
+++ b/langtools/src/jdk.javadoc/share/classes/com/sun/tools/doclets/formats/html/ConfigurationImpl.java Mon Jul 13 16:33:42 2015 +0200
@@ -289,9 +289,11 @@
} else if (opt.equals("-html5")) {
htmlVersion = HtmlVersion.HTML5;
} else if (opt.equals("-xdoclint")) {
- doclintOpts.add(null);
+ doclintOpts.add(DocLint.XMSGS_OPTION);
} else if (opt.startsWith("-xdoclint:")) {
- doclintOpts.add(opt.substring(opt.indexOf(":") + 1));
+ doclintOpts.add(DocLint.XMSGS_CUSTOM_PREFIX + opt.substring(opt.indexOf(":") + 1));
+ } else if (opt.startsWith("-xdoclint/package:")) {
+ doclintOpts.add(DocLint.XCHECK_PACKAGE + opt.substring(opt.indexOf(":") + 1));
}
}
if (root.specifiedClasses().length > 0) {
@@ -348,7 +350,8 @@
option.equals("-html4") ||
option.equals("-html5") ||
option.equals("-xdoclint") ||
- option.startsWith("-xdoclint:")) {
+ option.startsWith("-xdoclint:") ||
+ option.startsWith("-xdoclint/package:")) {
return 1;
} else if (option.equals("-help")) {
// Uugh: first, this should not be hidden inside optionLength,
@@ -476,6 +479,12 @@
reporter.printError(getText("doclet.Option_doclint_invalid_arg"));
return false;
}
+ } else if (opt.startsWith("-xdoclint/package:")) {
+ if (!DocLint.isValidOption(
+ opt.replace("-xdoclint/package:", DocLint.XCHECK_PACKAGE))) {
+ reporter.printError(getText("doclet.Option_doclint_package_invalid_arg"));
+ return false;
+ }
}
}
return true;
--- a/langtools/src/jdk.javadoc/share/classes/com/sun/tools/doclets/formats/html/resources/standard.properties Mon Jul 13 16:57:52 2015 +0400
+++ b/langtools/src/jdk.javadoc/share/classes/com/sun/tools/doclets/formats/html/resources/standard.properties Mon Jul 13 16:33:42 2015 +0200
@@ -231,4 +231,10 @@
\ -Xdoclint Enable recommended checks for problems in javadoc comments\n\
\ -Xdoclint:(all|none|[-]<group>) \n\
\ Enable or disable specific checks for problems in javadoc comments,\n\
-\ where <group> is one of accessibility, html, missing, reference, or syntax.\n
+\ where <group> is one of accessibility, html, missing, reference, or syntax.\n\
+\ -Xdoclint/package:([-]<packages>)\n\
+\ Enable or disable checks in specific packages. <packages> is a comma separated\n\
+\ list of package specifiers. Package specifier is either a qualified name of a package\n\
+\ or a package name prefix followed by .*, which expands to all sub-packages of\n\
+\ the given package. Prefix the package specifier with - to disable checks for\n\
+\ the specified packages.\n
--- a/langtools/src/jdk.javadoc/share/classes/com/sun/tools/doclets/internal/toolkit/resources/doclets.properties Mon Jul 13 16:57:52 2015 +0400
+++ b/langtools/src/jdk.javadoc/share/classes/com/sun/tools/doclets/internal/toolkit/resources/doclets.properties Mon Jul 13 16:33:42 2015 +0200
@@ -13,6 +13,7 @@
doclet.Option_reuse=Option reused: {0}
doclet.Option_doclint_no_qualifiers=Access qualifiers not permitted for -Xdoclint arguments
doclet.Option_doclint_invalid_arg=Invalid argument for -Xdoclint option
+doclet.Option_doclint_package_invalid_arg=Invalid argument for -Xdoclint/package option
doclet.exception_encountered= {0} encountered \n\
\twhile attempting to create file: {1}
doclet.perform_copy_exception_encountered= {0} encountered while \n\
--- a/langtools/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/DocEnv.java Mon Jul 13 16:57:52 2015 +0400
+++ b/langtools/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/DocEnv.java Mon Jul 13 16:33:42 2015 +0200
@@ -31,6 +31,7 @@
import javax.tools.JavaFileManager;
import com.sun.javadoc.*;
+import com.sun.source.tree.CompilationUnitTree;
import com.sun.source.util.JavacTask;
import com.sun.source.util.TreePath;
import com.sun.tools.doclint.DocLint;
@@ -816,16 +817,19 @@
void initDoclint(Collection<String> opts, Collection<String> customTagNames, String htmlVersion) {
ArrayList<String> doclintOpts = new ArrayList<>();
+ boolean msgOptionSeen = false;
- for (String opt: opts) {
- doclintOpts.add(opt == null ? DocLint.XMSGS_OPTION : DocLint.XMSGS_CUSTOM_PREFIX + opt);
+ for (String opt : opts) {
+ if (opt.startsWith(DocLint.XMSGS_OPTION)) {
+ if (opt.equals(DocLint.XMSGS_CUSTOM_PREFIX + "none"))
+ return;
+ msgOptionSeen = true;
+ }
+ doclintOpts.add(opt);
}
- if (doclintOpts.isEmpty()) {
+ if (!msgOptionSeen) {
doclintOpts.add(DocLint.XMSGS_OPTION);
- } else if (doclintOpts.size() == 1
- && doclintOpts.get(0).equals(DocLint.XMSGS_CUSTOM_PREFIX + "none")) {
- return;
}
String sep = "";
@@ -848,4 +852,10 @@
boolean showTagMessages() {
return (doclint == null);
}
+
+ Map<CompilationUnitTree, Boolean> shouldCheck = new HashMap<>();
+
+ boolean shouldCheck(CompilationUnitTree unit) {
+ return shouldCheck.computeIfAbsent(unit, doclint :: shouldCheck);
+ }
}
--- a/langtools/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/DocImpl.java Mon Jul 13 16:57:52 2015 +0400
+++ b/langtools/src/jdk.javadoc/share/classes/com/sun/tools/javadoc/DocImpl.java Mon Jul 13 16:33:42 2015 +0200
@@ -129,6 +129,7 @@
String d = documentation();
if (env.doclint != null
&& treePath != null
+ && env.shouldCheck(treePath.getCompilationUnit())
&& d.equals(getCommentText(treePath))) {
env.doclint.scan(treePath);
}
--- a/langtools/test/tools/javadoc/doclint/DocLintTest.java Mon Jul 13 16:57:52 2015 +0400
+++ b/langtools/test/tools/javadoc/doclint/DocLintTest.java Mon Jul 13 16:33:42 2015 +0200
@@ -23,7 +23,7 @@
/*
* @test
- * @bug 8004834 8007610
+ * @bug 8004834 8007610 8129909
* @summary Add doclint support into javadoc
* @modules jdk.compiler/com.sun.tools.javac.main
*/
@@ -59,7 +59,7 @@
DocumentationTool javadoc;
StandardJavaFileManager fm;
- JavaFileObject file;
+ Iterable<? extends JavaFileObject> files;
final String code =
/* 01 */ "/** Class comment. */\n" +
@@ -77,6 +77,20 @@
/* 13 */ " public int emptyReturn() { return 0; }\n" +
/* 14 */ "}\n";
+ final String p1Code =
+ /* 01 */ "package p1;\n" +
+ /* 02 */ "public class P1Test {\n" +
+ /* 03 */ " /** Syntax < error. */\n" +
+ /* 04 */ " public void method() { }\n" +
+ /* 05 */ "}\n";
+
+ final String p2Code =
+ /* 01 */ "package p2;\n" +
+ /* 02 */ "public class P2Test {\n" +
+ /* 03 */ " /** Syntax < error. */\n" +
+ /* 04 */ " public void method() { }\n" +
+ /* 05 */ "}\n";
+
private final String rawDiags = "-XDrawDiagnostics";
private enum Message {
@@ -85,6 +99,9 @@
DL_ERR9(ERROR, "Test.java:9:14: compiler.err.proc.messager: reference not found"),
DL_WRN12(WARNING, "Test.java:12:9: compiler.warn.proc.messager: no description for @return"),
+ DL_ERR_P1TEST(ERROR, "P1Test.java:3:16: compiler.err.proc.messager: malformed HTML"),
+ DL_ERR_P2TEST(ERROR, "P2Test.java:3:16: compiler.err.proc.messager: malformed HTML"),
+
// doclint messages when -XDrawDiagnostics is not in effect
DL_ERR9A(ERROR, "Test.java:9: error: reference not found"),
DL_WRN12A(WARNING, "Test.java:12: warning: no description for @return"),
@@ -95,7 +112,8 @@
// javadoc messages for bad options
OPT_BADARG(ERROR, "javadoc: error - Invalid argument for -Xdoclint option"),
- OPT_BADQUAL(ERROR, "javadoc: error - Access qualifiers not permitted for -Xdoclint arguments");
+ OPT_BADQUAL(ERROR, "javadoc: error - Access qualifiers not permitted for -Xdoclint arguments"),
+ OPT_BADPACKAGEARG(ERROR, "javadoc: error - Invalid argument for -Xdoclint/package option");
final Diagnostic.Kind kind;
final String text;
@@ -124,12 +142,7 @@
fm = javadoc.getStandardFileManager(null, null, null);
try {
fm.setLocation(StandardLocation.CLASS_OUTPUT, Arrays.asList(new File(".")));
- file = new SimpleJavaFileObject(URI.create("Test.java"), JavaFileObject.Kind.SOURCE) {
- @Override
- public CharSequence getCharContent(boolean ignoreEncoding) {
- return code;
- }
- };
+ files = Arrays.asList(new TestJFO("Test.java", code));
test(Collections.<String>emptyList(),
Main.Result.ERROR,
@@ -175,6 +188,21 @@
Main.Result.ERROR,
EnumSet.of(Message.OPT_BADARG));
+ files = Arrays.asList(new TestJFO("p1/P1Test.java", p1Code),
+ new TestJFO("p2/P2Test.java", p2Code));
+
+ test(Arrays.asList(rawDiags),
+ Main.Result.ERROR,
+ EnumSet.of(Message.DL_ERR_P1TEST, Message.DL_ERR_P2TEST));
+
+ test(Arrays.asList(rawDiags, "-Xdoclint/package:p1"),
+ Main.Result.ERROR,
+ EnumSet.of(Message.DL_ERR_P1TEST));
+
+ test(Arrays.asList(rawDiags, "-Xdoclint/package:*p"),
+ Main.Result.ERROR,
+ EnumSet.of(Message.OPT_BADPACKAGEARG));
+
if (errors > 0)
throw new Exception(errors + " errors occurred");
} finally {
@@ -186,7 +214,6 @@
System.err.println("test: " + opts);
StringWriter sw = new StringWriter();
PrintWriter pw = new PrintWriter(sw);
- List<JavaFileObject> files = Arrays.asList(file);
try {
DocumentationTask t = javadoc.getTask(pw, fm, null, null, opts, files);
boolean ok = t.call();
@@ -257,4 +284,19 @@
}
int errors;
+
+ class TestJFO extends SimpleJavaFileObject {
+
+ private final String content;
+
+ public TestJFO(String fileName, String content) {
+ super(URI.create(fileName), JavaFileObject.Kind.SOURCE);
+ this.content = content;
+ }
+
+ @Override
+ public CharSequence getCharContent(boolean ignoreEncoding) {
+ return content;
+ }
+ };
}