8252717: Integrate/merge legacy standard doclet diagnostics and doclint

jonathan-gibbons · jonathan-gibbons · commit 59e9700c4e0a · 2022-06-03T16:17:23.000Z
Reviewed-by: erikj, prappo
diff --git a/make/Docs.gmk b/make/Docs.gmk
@@ -104,14 +104,14 @@ JAVADOC_DISABLED_DOCLINT_PACKAGES := org.w3c.* javax.smartcardio
 
 # The initial set of options for javadoc
 JAVADOC_OPTIONS := -use -keywords -notimestamp \
-    -serialwarn -encoding ISO-8859-1 -docencoding UTF-8 -breakiterator \
+    -encoding ISO-8859-1 -docencoding UTF-8 -breakiterator \
     -splitIndex --system none -javafx --expand-requires transitive \
     --override-methods=summary
 
 # The reference options must stay stable to allow for comparisons across the
 # development cycle.
 REFERENCE_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \
-    -serialwarn -encoding ISO-8859-1 -breakiterator -splitIndex --system none \
+    -encoding ISO-8859-1 -breakiterator -splitIndex --system none \
     -html5 -javafx --expand-requires transitive
 
 # Should we add DRAFT stamps to the generated javadoc?
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java
@@ -403,16 +403,6 @@ public JavaFileManager getFileManager() {
         return docEnv.getJavaFileManager();
     }
 
-    @Override
-    public boolean showMessage(DocTreePath path, String key) {
-        return (path == null || !haveDocLint());
-    }
-
-    @Override
-    public boolean showMessage(Element e, String key) {
-        return (e == null || !haveDocLint());
-    }
-
     @Override
     protected boolean finishOptionSettings0() throws DocletException {
         if (options.docEncoding() == null) {
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
@@ -1054,10 +1054,12 @@ public Content seeTagToContent(Element element, DocTree see, TagletWriterImpl.Co
                             (labelContent.isEmpty() ? text : labelContent));
                 } else {
                     // No cross link found so print warning
-                    messages.warning(ch.getDocTreePath(see),
-                            "doclet.see.class_or_package_not_found",
-                            "@" + tagName,
-                            seeText);
+                    if (!configuration.isDocLintReferenceGroupEnabled()) {
+                        messages.warning(ch.getDocTreePath(see),
+                                "doclet.see.class_or_package_not_found",
+                                "@" + tagName,
+                                seeText);
+                    }
                     return invalidTagOutput(resources.getText("doclet.tag.invalid", tagName),
                             Optional.of(labelContent.isEmpty() ? text: labelContent));
                 }
@@ -1107,9 +1109,11 @@ public Content seeTagToContent(Element element, DocTree see, TagletWriterImpl.Co
                         ch.getDocTreePath(see), "doclet.see.class_or_package_not_accessible",
                         tagName, utils.getFullyQualifiedName(containing));
                 } else {
-                    messages.warning(
-                        ch.getDocTreePath(see), "doclet.see.class_or_package_not_found",
-                        tagName, seeText);
+                    if (!configuration.isDocLintReferenceGroupEnabled()) {
+                        messages.warning(
+                                ch.getDocTreePath(see), "doclet.see.class_or_package_not_found",
+                                tagName, seeText);
+                    }
                 }
             }
             if (configuration.currentTypeElement != containing) {
@@ -1599,7 +1603,9 @@ public Boolean visitErroneous(ErroneousTree node, Content c) {
                         Matcher m = Pattern.compile("(?i)\\{@([a-z]+).*").matcher(body);
                         String tagName = m.matches() ? m.group(1) : null;
                         if (tagName == null) {
-                            messages.warning(dtp, "doclet.tag.invalid_input", body);
+                            if (!configuration.isDocLintSyntaxGroupEnabled()) {
+                                messages.warning(dtp, "doclet.tag.invalid_input", body);
+                            }
                             result.add(invalidTagOutput(resources.getText("doclet.tag.invalid_input", body),
                                     Optional.empty()));
                         } else {
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseConfiguration.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/BaseConfiguration.java
@@ -28,7 +28,6 @@
 
 import java.io.File;
 import java.io.IOException;
-import java.io.InputStream;
 import java.nio.file.InvalidPathException;
 import java.nio.file.Path;
 import java.util.ArrayList;
@@ -60,7 +59,6 @@
 import javax.tools.StandardJavaFileManager;
 
 import com.sun.source.tree.CompilationUnitTree;
-import com.sun.source.util.DocTreePath;
 import com.sun.source.util.TreePath;
 import com.sun.tools.javac.util.DefinedBy;
 import com.sun.tools.javac.util.DefinedBy.Api;
@@ -74,7 +72,6 @@
 import jdk.javadoc.internal.doclets.toolkit.util.Comparators;
 import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
 import jdk.javadoc.internal.doclets.toolkit.util.DocFileFactory;
-import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
 import jdk.javadoc.internal.doclets.toolkit.util.Extern;
 import jdk.javadoc.internal.doclets.toolkit.util.Group;
 import jdk.javadoc.internal.doclets.toolkit.util.MetaKeywords;
@@ -85,6 +82,7 @@
 import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberCache;
 import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable;
 import jdk.javadoc.internal.doclint.DocLint;
+import jdk.javadoc.internal.doclint.Env;
 
 /**
  * Configure the output based on the options. Doclets should subclass
@@ -640,10 +638,6 @@ public boolean isGeneratedDoc(TypeElement te) {
      */
     public abstract JavaFileManager getFileManager();
 
-    public abstract boolean showMessage(DocTreePath path, String key);
-
-    public abstract boolean showMessage(Element e, String key);
-
     /*
      * Splits the elements in a collection to its individual
      * collection.
@@ -803,8 +797,20 @@ public void initDocLint(List<String> opts, Set<String> customTagNames) {
                 doclintOpts.toArray(new String[0]));
     }
 
-    public boolean haveDocLint() {
-        return (doclint != null);
+    public boolean isDocLintReferenceGroupEnabled() {
+        return isDocLintGroupEnabled(jdk.javadoc.internal.doclint.Messages.Group.REFERENCE);
+    }
+
+    public boolean isDocLintSyntaxGroupEnabled() {
+        return isDocLintGroupEnabled(jdk.javadoc.internal.doclint.Messages.Group.SYNTAX);
+    }
+
+    private boolean isDocLintGroupEnabled(jdk.javadoc.internal.doclint.Messages.Group group) {
+        // Use AccessKind.PUBLIC as a stand-in, since it is not common to
+        // set DocLint options per access kind (as is common with javac.)
+        // A more sophisticated solution might be to derive the access kind from the
+        // element owning the comment, and its enclosing elements.
+        return doclint != null && doclint.isGroupEnabled(group, Env.AccessKind.PUBLIC);
     }
     //</editor-fold>
 }
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Messages.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Messages.java
@@ -143,9 +143,7 @@ public void warning(String key, Object... args) {
      * @param args optional arguments to be replaced in the message
      */
     public void warning(DocTreePath path, String key, Object... args) {
-        if (configuration.showMessage(path, key)) {
-            report(WARNING, path, resources.getText(key, args));
-        }
+        report(WARNING, path, resources.getText(key, args));
     }
 
     /**
@@ -170,9 +168,7 @@ public void warning(DocTreePath path, int start, int pos, int end, String key, O
      * @param args optional arguments to be replaced in the message
      */
     public void warning(Element e, String key, Object... args) {
-        if (configuration.showMessage(e, key)) {
-            report(WARNING, e, resources.getText(key, args));
-        }
+        report(WARNING, e, resources.getText(key, args));
     }
 
     /**
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java
@@ -222,7 +222,9 @@ private Content processParamTags(Element e,
                         case TYPE_PARAMETER -> "doclet.TypeParameters_warn";
                         case RECORD_COMPONENT -> "doclet.RecordComponents_warn";
                     };
-                    messages.warning(ch.getDocTreePath(dt), key, paramName);
+                    if (!writer.configuration().isDocLintReferenceGroupEnabled()) {
+                        messages.warning(ch.getDocTreePath(dt), key, paramName);
+                    }
                 }
                 String rank = rankMap.get(name);
                 if (rank != null) {
@@ -232,7 +234,9 @@ private Content processParamTags(Element e,
                             case TYPE_PARAMETER -> "doclet.TypeParameters_dup_warn";
                             case RECORD_COMPONENT -> "doclet.RecordComponents_dup_warn";
                         };
-                        messages.warning(ch.getDocTreePath(dt), key, paramName);
+                        if (!writer.configuration().isDocLintReferenceGroupEnabled()) {
+                            messages.warning(ch.getDocTreePath(dt), key, paramName);
+                        }
                     } else {
                         documented.put(rank, dt);
                     }
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ReturnTaglet.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ReturnTaglet.java
@@ -96,7 +96,7 @@ public Content getAllBlockTagOutput(Element holder, TagletWriter writer) {
         // Make sure we are not using @return tag on method with void return type.
         TypeMirror returnType = utils.getReturnType(writer.getCurrentPageElement(), (ExecutableElement) holder);
         if (returnType != null && utils.isVoid(returnType)) {
-            if (!tags.isEmpty()) {
+            if (!tags.isEmpty() && !writer.configuration().isDocLintReferenceGroupEnabled()) {
                 messages.warning(holder, "doclet.Return_tag_on_void_method");
             }
             return null;
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/DocLint.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/DocLint.java
@@ -384,6 +384,10 @@ public boolean isValidOption(String opt) {
         return false;
     }
 
+    public boolean isGroupEnabled(Messages.Group group, Env.AccessKind accessKind) {
+        return env.messages.isEnabled(group, accessKind);
+    }
+
     private String localize(String code, Object... args) {
         Messages m = (env != null) ? env.messages : new Messages(null);
         return m.localize(code, args);
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Messages.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Messages.java
@@ -104,6 +104,10 @@ void setStatsEnabled(boolean b) {
         stats.setEnabled(b);
     }
 
+    boolean isEnabled(Group group, Env.AccessKind ak) {
+        return options.isEnabled(group, ak);
+    }
+
     void reportStats(PrintWriter out) {
         stats.report(out);
     }
diff --git a/test/langtools/jdk/javadoc/doclet/testDoclintDocletMessages/TestDocLintDocletMessages.java b/test/langtools/jdk/javadoc/doclet/testDoclintDocletMessages/TestDocLintDocletMessages.java
diff --git a/test/langtools/jdk/javadoc/tool/doclint/DocLintTest.java b/test/langtools/jdk/javadoc/tool/doclint/DocLintTest.java

Original file line number	Diff line number	Diff line change
`@@ -96,7 +96,7 @@ public Content getAllBlockTagOutput(Element holder, TagletWriter writer) {`
`96`	`96`	`// Make sure we are not using @return tag on method with void return type.`
`97`	`97`	`TypeMirror returnType = utils.getReturnType(writer.getCurrentPageElement(), (ExecutableElement) holder);`
`98`	`98`	`if (returnType != null && utils.isVoid(returnType)) {`
`99`		`- if (!tags.isEmpty()) {`
	`99`	`+ if (!tags.isEmpty() && !writer.configuration().isDocLintReferenceGroupEnabled()) {`
`100`	`100`	`messages.warning(holder, "doclet.Return_tag_on_void_method");`
`101`	`101`	`}`
`102`	`102`	`return null;`
Original file line number	Diff line number	Diff line change
`@@ -104,6 +104,10 @@ void setStatsEnabled(boolean b) {`
`104`	`104`	`stats.setEnabled(b);`
`105`	`105`	`}`
`106`	`106`
	`107`	`+ boolean isEnabled(Group group, Env.AccessKind ak) {`
	`108`	`+ return options.isEnabled(group, ak);`
	`109`	`+ }`
	`110`	`+`
`107`	`111`	`void reportStats(PrintWriter out) {`
`108`	`112`	`stats.report(out);`
`109`	`113`	`}`