8021215: javac gives incorrect doclint warnings on normal package statements

Reviewed-by: darcy

langtools/src/share/classes/com/sun/tools/doclint/Checker.java

@@ -141,11 +141,28 @@ public class Checker extends DocTreePathScanner<Void, Void> {
 
         boolean isOverridingMethod = !env.currOverriddenMethods.isEmpty();
 
+        if (p.getLeaf() == p.getCompilationUnit()) {
+            // If p points to a compilation unit, the implied declaration is the
+            // package declaration (if any) for the compilation unit.
+            // Handle this case specially, because doc comments are only
+            // expected in package-info files.
+            JavaFileObject fo = p.getCompilationUnit().getSourceFile();
+            boolean isPkgInfo = fo.isNameCompatible("package-info", JavaFileObject.Kind.SOURCE);
+            if (tree == null) {
+                if (isPkgInfo)
+                    reportMissing("dc.missing.comment");
+                return null;
+            } else {
+                if (!isPkgInfo)
+                    reportReference("dc.unexpected.comment");
+            }
+        } else {
             if (tree == null) {
                 if (!isSynthetic() && !isOverridingMethod)
                     reportMissing("dc.missing.comment");
                 return null;
             }
+        }
 
         tagStack.clear();
         currHeaderTag = null;
@@ -187,6 +204,10 @@ public class Checker extends DocTreePathScanner<Void, Void> {
         env.messages.report(MISSING, Kind.WARNING, env.currPath.getLeaf(), code, args);
     }
 
+    private void reportReference(String code, Object... args) {
+        env.messages.report(REFERENCE, Kind.WARNING, env.currPath.getLeaf(), code, args);
+    }
+
     @Override
     public Void visitDocComment(DocCommentTree tree, Void ignore) {
         super.visitDocComment(tree, ignore);

langtools/src/share/classes/com/sun/tools/doclint/DocLint.java

@@ -32,8 +32,6 @@ import java.util.ArrayList;
 import java.util.List;
 
 import javax.lang.model.element.Name;
-import javax.tools.Diagnostic;
-import javax.tools.JavaFileObject;
 import javax.tools.StandardLocation;
 
 import com.sun.source.doctree.DocCommentTree;
@@ -152,18 +150,6 @@ public class DocLint implements Plugin {
                 TreePath p = getCurrentPath();
                 DocCommentTree dc = env.trees.getDocCommentTree(p);
 
-                if (p.getLeaf() == p.getCompilationUnit()) {
-                    JavaFileObject fo = p.getCompilationUnit().getSourceFile();
-                    boolean pkgInfo = fo.isNameCompatible("package-info", JavaFileObject.Kind.SOURCE);
-                    if (!pkgInfo) {
-                        if (dc == null)
-                            return;
-                        env.setCurrent(p, dc);
-                        env.messages.report(Messages.Group.REFERENCE, Diagnostic.Kind.WARNING, p.getLeaf(),
-                                "dc.unexpected.comment");
-                    }
-                }
-
                 checker.scan(dc, p);
             }
         };

langtools/test/tools/doclint/packageTests/bad/Test.java

@@ -1,14 +1,16 @@
 /*
  * @test /nodynamiccopyright/
- * @bug 8020664
+ * @bug 8020664 8021215
  * @summary doclint gives incorrect warnings on normal package statements
  * @library ../..
  * @build DocLintTester
  * @run main DocLintTester -ref Test.out Test.java
+ * @compile/fail/ref=Test.javac.out -XDrawDiagnostics -Werror -Xdoclint:all Test.java
  */
 
 /** Unexpected comment */
 package bad;
 
+/** */
 class Test { }
 

langtools/test/tools/doclint/packageTests/bad/Test.javac.out

@@ -0,0 +1,4 @@
+Test.java:12:1: compiler.warn.proc.messager: documentation comment not expected here
+- compiler.err.warnings.and.werror
+1 error
+1 warning

langtools/test/tools/doclint/packageTests/bad/Test.out

@@ -1,4 +1,4 @@
-Test.java:11: warning: documentation comment not expected here
+Test.java:12: warning: documentation comment not expected here
 package bad;
 ^
 1 warning

langtools/test/tools/doclint/packageTests/bad/package-info.java

@@ -1,10 +1,11 @@
 /*
  * @test /nodynamiccopyright/
- * @bug 8020664
+ * @bug 8020664 8021215
  * @summary doclint gives incorrect warnings on normal package statements
  * @library ../..
  * @build DocLintTester
  * @run main DocLintTester -ref package-info.out package-info.java
+ * @compile/fail/ref=package-info.javac.out -XDrawDiagnostics -Werror -Xdoclint:all package-info.java
  */
 
 // missing comment

langtools/test/tools/doclint/packageTests/bad/package-info.javac.out

@@ -0,0 +1,4 @@
+package-info.java:12:1: compiler.warn.proc.messager: no comment
+- compiler.err.warnings.and.werror
+1 error
+1 warning

langtools/test/tools/doclint/packageTests/bad/package-info.out

@@ -1,4 +1,4 @@
-package-info.java:11: warning: no comment
+package-info.java:12: warning: no comment
 package bad;
 ^
 1 warning

langtools/test/tools/doclint/packageTests/good/Test.java

@@ -23,15 +23,17 @@
 
 /*
  * @test /nodynamiccopyright/
- * @bug 8020664
+ * @bug 8020664 8021215
  * @summary doclint gives incorrect warnings on normal package statements
  * @library ../..
  * @build DocLintTester
  * @run main DocLintTester Test.java
+ * @compile -Xdoclint:all Test.java
  */
 
 // no doc comment
 package good;
 
+/** */
 class Test { }
 

langtools/test/tools/doclint/packageTests/good/package-info.java

@@ -23,11 +23,12 @@
 
 /*
  * @test /nodynamiccopyright/
- * @bug 8020664
+ * @bug 8020664 8021215
  * @summary doclint gives incorrect warnings on normal package statements
  * @library ../..
  * @build DocLintTester
  * @run main DocLintTester package-info.java
+ * @compile -Xdoclint:all package-info.java
  */
 
 /** Description. */