Issue checkstyle#12520: removes missing package-info Javadoc check in…

… JavadocStyle

config/jsoref-spellchecker/whitelist.words

@@ -864,6 +864,7 @@ missingjavadocmethod
 missingjavadocpackage
 missingjavadoctype
 missingoverride
+missingperiod
 missingswitchdefault
 missingtag
 mixin

src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocStyleCheck.java

@@ -66,8 +66,7 @@
  * a previous open tag.
  * </li>
  * <li>
- * Check that a package Javadoc comment is well-formed (as described above) and
- * NOT missing from any package-info.java files.
+ * Check that a package Javadoc comment is well-formed (as described above).
  * </li>
  * <li>
  * Check for allowed HTML tags. The list of allowed HTML tags is
@@ -288,9 +287,6 @@
  * {@code javadoc.incompleteTag}
  * </li>
  * <li>
- * {@code javadoc.missing}
- * </li>
- * <li>
  * {@code javadoc.noPeriod}
  * </li>
  * <li>
@@ -304,9 +300,6 @@
 public class JavadocStyleCheck
     extends AbstractCheck {
 
-    /** Message property key for the Missing Javadoc message. */
-    public static final String MSG_JAVADOC_MISSING = "javadoc.missing";
-
     /** Message property key for the Empty Javadoc message. */
     public static final String MSG_EMPTY = "javadoc.empty";
 
@@ -447,16 +440,7 @@ else if (!ScopeUtil.isInCodeBlock(ast)) {
      * @see #checkHtmlTags(DetailAST, TextBlock)
      */
     private void checkComment(final DetailAST ast, final TextBlock comment) {
-        if (comment == null) {
-            // checking for missing docs in JavadocStyleCheck is not consistent
-            // with the rest of CheckStyle...  Even though, I didn't think it
-            // made sense to make another check just to ensure that the
-            // package-info.java file actually contains package Javadocs.
-            if (CheckUtil.isPackageInfo(getFilePath())) {
-                log(ast, MSG_JAVADOC_MISSING);
-            }
-        }
-        else {
+        if (comment != null) {
             if (checkFirstSentence) {
                 checkFirstSentenceEnding(ast, comment);
             }

src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/MissingJavadocPackageCheck.java

@@ -30,7 +30,7 @@
 
 /**
  * <p>
- * Checks for missing Javadoc comments in package-info.java files.
+ * Checks for missing package definition Javadoc comments in package-info.java files.
  * </p>
  * <p>
  * Rationale: description and other related documentation for a package can be written up
@@ -40,6 +40,10 @@
  * >link</a> for more info.
  * </p>
  * <p>
+ * This check specifically only validates package definitions. It will not validate any methods or
+ * interfaces declared in the package-info.java file.
+ * </p>
+ * <p>
  * To configure the check:
  * </p>
  * <pre>

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/javadoc/JavadocStyleCheck.xml

@@ -31,8 +31,7 @@
  a previous open tag.
  </li>
  <li>
- Check that a package Javadoc comment is well-formed (as described above) and
- NOT missing from any package-info.java files.
+ Check that a package Javadoc comment is well-formed (as described above).
  </li>
  <li>
  Check for allowed HTML tags. The list of allowed HTML tags is
@@ -87,7 +86,6 @@
             <message-key key="javadoc.empty"/>
             <message-key key="javadoc.extraHtml"/>
             <message-key key="javadoc.incompleteTag"/>
-            <message-key key="javadoc.missing"/>
             <message-key key="javadoc.noPeriod"/>
             <message-key key="javadoc.unclosedHtml"/>
          </message-keys>

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/javadoc/MissingJavadocPackageCheck.xml

@@ -5,14 +5,18 @@
               name="MissingJavadocPackage"
               parent="com.puppycrawl.tools.checkstyle.TreeWalker">
          <description>&lt;p&gt;
- Checks for missing Javadoc comments in package-info.java files.
+ Checks for missing package definition Javadoc comments in package-info.java files.
  &lt;/p&gt;
  &lt;p&gt;
  Rationale: description and other related documentation for a package can be written up
  in the package-info.java file and it gets used in the production of the Javadocs.
  See &lt;a
  href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#packagecomment"
  &gt;link&lt;/a&gt; for more info.
+ &lt;/p&gt;
+ &lt;p&gt;
+ This check specifically only validates package definitions. It will not validate any methods or
+ interfaces declared in the package-info.java file.
  &lt;/p&gt;</description>
          <message-keys>
             <message-key key="package.javadoc.missing"/>

src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocStyleCheckTest.java

@@ -23,7 +23,6 @@
 import static com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocStyleCheck.MSG_EMPTY;
 import static com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocStyleCheck.MSG_EXTRA_HTML;
 import static com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocStyleCheck.MSG_INCOMPLETE_TAG;
-import static com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocStyleCheck.MSG_JAVADOC_MISSING;
 import static com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocStyleCheck.MSG_NO_PERIOD;
 import static com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocStyleCheck.MSG_UNCLOSED_HTML;
 
@@ -485,12 +484,30 @@ public void packageInfoAnnotation() throws Exception {
 
     @Test
     public void packageInfoMissing() throws Exception {
+        final String[] expected = CommonUtil.EMPTY_STRING_ARRAY;
+
+        verifyWithInlineConfigParser(
+                getPath("bothfiles" + File.separator + "package-info.java"),
+               expected);
+    }
+
+    @Test
+    public void packageInfoMissingPeriod() throws Exception {
         final String[] expected = {
-            "16:1: " + getCheckMessage(MSG_JAVADOC_MISSING),
+            "16: " + getCheckMessage(MSG_NO_PERIOD),
         };
 
         verifyWithInlineConfigParser(
-                getPath("bothfiles" + File.separator + "package-info.java"),
+                getPath("missingperiod" + File.separator + "package-info.java"),
+               expected);
+    }
+
+    @Test
+    public void testNothing() throws Exception {
+        final String[] expected = CommonUtil.EMPTY_STRING_ARRAY;
+
+        verifyWithInlineConfigParser(
+                getPath("InputJavadocStyleNothing.java"),
                expected);
     }
 

src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocstyle/InputJavadocStyleNothing.java

@@ -0,0 +1,20 @@
+/*
+JavadocStyle
+scope = nothing
+excludeScope = (default)null
+checkFirstSentence = (default)true
+endOfSentenceFormat = (default)([.?!][ \t\n\r\f<])|([.?!]$)
+checkEmptyJavadoc = (default)false
+checkHtml = (default)true
+tokens = (default)ANNOTATION_DEF, ANNOTATION_FIELD_DEF, CLASS_DEF, CTOR_DEF, \
+         ENUM_CONSTANT_DEF, ENUM_DEF, INTERFACE_DEF, METHOD_DEF, PACKAGE_DEF, \
+         VARIABLE_DEF, RECORD_DEF, COMPACT_CTOR_DEF
+
+
+*/
+
+/** Desc but no period */ // ok
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocstyle;
+
+public class InputJavadocStyleNothing {
+}

src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocstyle/bothfiles/package-info.java

@@ -13,4 +13,4 @@
 
 */
 
-package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocstyle.bothfiles; // violation
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocstyle.bothfiles;

src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocstyle/missingperiod/package-info.java

@@ -0,0 +1,28 @@
+/*
+JavadocStyle
+scope = (default)private
+excludeScope = (default)null
+checkFirstSentence = (default)true
+endOfSentenceFormat = (default)([.?!][ \t\n\r\f<])|([.?!]$)
+checkEmptyJavadoc = (default)false
+checkHtml = (default)true
+tokens = (default)ANNOTATION_DEF, ANNOTATION_FIELD_DEF, CLASS_DEF, CTOR_DEF, \
+         ENUM_CONSTANT_DEF, ENUM_DEF, INTERFACE_DEF, METHOD_DEF, PACKAGE_DEF, \
+         VARIABLE_DEF, RECORD_DEF, COMPACT_CTOR_DEF
+
+
+*/
+
+/** Example */ // violation 'First sentence should end with a period.'
+@Example
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocstyle.missingperiod;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.PACKAGE)
+@interface Example {
+}

src/test/resources/com/puppycrawl/tools/checkstyle/utils/checkutil/InputCheckUtilPackage.java

@@ -0,0 +1,4 @@
+package com.puppycrawl.tools.checkstyle.utils.checkutil; // ok
+
+public class InputCheckUtilPackage {
+}

src/test/resources/com/puppycrawl/tools/checkstyle/utils/checkutil/package-info.java

@@ -0,0 +1 @@
+package com.puppycrawl.tools.checkstyle.utils.checkutil; // ok

src/xdocs/checks.xml

@@ -553,7 +553,9 @@
           </tr>
           <tr>
             <td><a href="config_javadoc.html#MissingJavadocPackage">MissingJavadocPackage</a></td>
-            <td>Checks for missing Javadoc comments in package-info.java files.</td>
+            <td>
+              Checks for missing package definition Javadoc comments in package-info.java files.
+            </td>
           </tr>
           <tr>
             <td><a href="config_javadoc.html#MissingJavadocType">MissingJavadocType</a></td>

src/xdocs/config_javadoc.xml

@@ -1519,7 +1519,7 @@ public class TestClass {
           </li>
           <li>
            Check that a package Javadoc comment is well-formed (as
-           described above) and NOT missing from any package-info.java files.
+           described above).
           </li>
           <li>
             Check for allowed HTML tags. The list of allowed HTML tags
@@ -1824,10 +1824,6 @@ public class Test {
             <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.incompleteTag%22">
             javadoc.incompleteTag</a>
           </li>
-          <li>
-            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.missing%22">
-            javadoc.missing</a>
-          </li>
           <li>
             <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.noPeriod%22">
             javadoc.noPeriod</a>
@@ -2779,7 +2775,7 @@ public class Test {
       <p>Since Checkstyle 8.22</p>
       <subsection name="Description" id="MissingJavadocPackage_Description">
         <p>
-            Checks for missing Javadoc comments in package-info.java files.
+            Checks for missing package definition Javadoc comments in package-info.java files.
         </p>
 
         <p>
@@ -2788,6 +2784,11 @@ public class Test {
           See <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#packagecomment">
           link</a> for more info.
         </p>
+
+        <p>
+          This check specifically only validates package definitions. It will not validate any
+          methods or interfaces declared in the package-info.java file.
+        </p>
       </subsection>
 
       <subsection name="Examples" id="MissingJavadocPackage_Examples">