8020664: doclint gives incorrect warnings on normal package statements

Reviewed-by: mcimadamore

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

@@ -30,9 +30,10 @@ import java.io.IOException;
 import java.io.PrintWriter;
 import java.util.ArrayList;
 import java.util.List;
-import java.util.regex.Pattern;
 
 import javax.lang.model.element.Name;
+import javax.tools.Diagnostic;
+import javax.tools.JavaFileObject;
 import javax.tools.StandardLocation;
 
 import com.sun.source.doctree.DocCommentTree;
@@ -151,6 +152,18 @@ 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);
             }
         };
@@ -166,8 +179,8 @@ public class DocLint implements Plugin {
     }
 
     void processArgs(String... args) throws BadArgs {
-        javacOpts = new ArrayList<String>();
+        javacOpts = new ArrayList<>();
-        javacFiles = new ArrayList<File>();
+        javacFiles = new ArrayList<>();
 
         if (args.length == 0)
             needHelp = true;
@@ -214,7 +227,7 @@ public class DocLint implements Plugin {
     }
 
     List<File> splitPath(String path) {
-        List<File> files = new ArrayList<File>();
+        List<File> files = new ArrayList<>();
         for (String f: path.split(File.pathSeparator)) {
             if (f.length() > 0)
                 files.add(new File(f));
@@ -279,7 +292,6 @@ public class DocLint implements Plugin {
             TaskListener tl = new TaskListener() {
                 @Override
                 public void started(TaskEvent e) {
-                    return;
                 }
 
                 @Override

langtools/src/share/classes/com/sun/tools/doclint/resources/doclint.properties

@@ -67,6 +67,7 @@ dc.tag.self.closing = self-closing element not allowed
 dc.tag.start.unmatched = end tag missing: </{0}>
 dc.tag.unknown = unknown tag: {0}
 dc.text.not.allowed = text not allowed in <{0}> element
+dc.unexpected.comment=documentation comment not expected here
 
 dc.main.ioerror=IO error: {0}
 dc.main.no.files.given=No files given

langtools/test/tools/doclint/BadPackageCommentTest.out

@@ -1,3 +1,6 @@
+BadPackageCommentTest.java:13: warning: documentation comment not expected here
+package p;
+^
 BadPackageCommentTest.java:11: error: no tag name after @
  * @@@
    ^
@@ -8,3 +11,4 @@ BadPackageCommentTest.java:11: error: no tag name after @
  * @@@
      ^
 3 errors
+1 warning

langtools/test/tools/doclint/DocLintTester.java

@@ -123,7 +123,7 @@ public class DocLintTester {
     private static final Pattern dirFileLine = Pattern.compile(
             "(?m)"                          // multi-line mode
             + "^(.*?)"                      // directory part of file name
-            + "([A-Za-z0-9.]+:[0-9]+:)");   // file name and line number
+            + "([-A-Za-z0-9.]+:[0-9]+:)");  // file name and line number
 
     String removeFileNames(String s) {
         Matcher m = dirFileLine.matcher(s);

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

@@ -0,0 +1,14 @@
+/*
+ * @test /nodynamiccopyright/
+ * @bug 8020664
+ * @summary doclint gives incorrect warnings on normal package statements
+ * @library ../..
+ * @build DocLintTester
+ * @run main DocLintTester -ref Test.out Test.java
+ */
+
+/** Unexpected comment */
+package bad;
+
+class Test { }
+

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

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

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

@@ -0,0 +1,11 @@
+/*
+ * @test /nodynamiccopyright/
+ * @bug 8020664
+ * @summary doclint gives incorrect warnings on normal package statements
+ * @library ../..
+ * @build DocLintTester
+ * @run main DocLintTester -ref package-info.out package-info.java
+ */
+
+// missing comment
+package bad;

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

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

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

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2012, 2013, 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.
+ */
+
+/*
+ * @test /nodynamiccopyright/
+ * @bug 8020664
+ * @summary doclint gives incorrect warnings on normal package statements
+ * @library ../..
+ * @build DocLintTester
+ * @run main DocLintTester Test.java
+ */
+
+// no doc comment
+package good;
+
+class Test { }
+

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

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2012, 2013, 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.
+ */
+
+/*
+ * @test /nodynamiccopyright/
+ * @bug 8020664
+ * @summary doclint gives incorrect warnings on normal package statements
+ * @library ../..
+ * @build DocLintTester
+ * @run main DocLintTester package-info.java
+ */
+
+/** Description. */
+package good;