Issue #12864: Update Javadoc description to be optional

checkstyle · May 5, 2023 · 7e8b0a6 · 7e8b0a6
1 parent 4770064
commit 7e8b0a6
Show file tree

Hide file tree

Showing 10 changed files with 74 additions and 45 deletions.
diff --git a/config/pitest-suppressions/pitest-javadoc-suppressions.xml b/config/pitest-suppressions/pitest-javadoc-suppressions.xml
@@ -837,33 +837,6 @@
     <lineContent>return (excludeScope == null</lineContent>
   </mutation>
 
-  <mutation unstable="false">
-    <sourceFile>NonEmptyAtclauseDescriptionCheck.java</sourceFile>
-    <mutatedClass>com.puppycrawl.tools.checkstyle.checks.javadoc.NonEmptyAtclauseDescriptionCheck</mutatedClass>
-    <mutatedMethod>hasOnlyEmptyText</mutatedMethod>
-    <mutator>org.pitest.mutationtest.engine.gregor.mutators.RemoveConditionalMutator_EQUAL_IF</mutator>
-    <description>removed conditional - replaced equality check with true</description>
-    <lineContent>if (child.getType() != JavadocTokenTypes.TEXT</lineContent>
-  </mutation>
-
-  <mutation unstable="false">
-    <sourceFile>NonEmptyAtclauseDescriptionCheck.java</sourceFile>
-    <mutatedClass>com.puppycrawl.tools.checkstyle.checks.javadoc.NonEmptyAtclauseDescriptionCheck</mutatedClass>
-    <mutatedMethod>hasOnlyEmptyText</mutatedMethod>
-    <mutator>org.pitest.mutationtest.engine.gregor.mutators.NonVoidMethodCallMutator</mutator>
-    <description>removed call to com/puppycrawl/tools/checkstyle/api/DetailNode::getText</description>
-    <lineContent>|| !CommonUtil.isBlank(child.getText())) {</lineContent>
-  </mutation>
-
-  <mutation unstable="false">
-    <sourceFile>NonEmptyAtclauseDescriptionCheck.java</sourceFile>
-    <mutatedClass>com.puppycrawl.tools.checkstyle.checks.javadoc.NonEmptyAtclauseDescriptionCheck</mutatedClass>
-    <mutatedMethod>hasOnlyEmptyText</mutatedMethod>
-    <mutator>org.pitest.mutationtest.engine.gregor.mutators.RemoveConditionalMutator_EQUAL_ELSE</mutator>
-    <description>removed conditional - replaced equality check with false</description>
-    <lineContent>|| !CommonUtil.isBlank(child.getText())) {</lineContent>
-  </mutation>
-
   <mutation unstable="false">
     <sourceFile>NonEmptyAtclauseDescriptionCheck.java</sourceFile>
     <mutatedClass>com.puppycrawl.tools.checkstyle.checks.javadoc.NonEmptyAtclauseDescriptionCheck</mutatedClass>

diff --git a/...java/com/puppycrawl/tools/checkstyle/checks/javadoc/NonEmptyAtclauseDescriptionCheck.java b/...java/com/puppycrawl/tools/checkstyle/checks/javadoc/NonEmptyAtclauseDescriptionCheck.java
@@ -181,8 +181,8 @@ private static boolean isEmptyTag(DetailNode tagNode) {
     private static boolean hasOnlyEmptyText(DetailNode description) {
         boolean result = true;
         for (DetailNode child : description.getChildren()) {
-            if (child.getType() != JavadocTokenTypes.TEXT
-                    || !CommonUtil.isBlank(child.getText())) {
+            if (child.getType() != JavadocTokenTypes.LEADING_ASTERISK
+                    && !CommonUtil.isBlank(child.getText())) {
                 result = false;
                 break;
             }

diff --git a/src/main/resources/com/puppycrawl/tools/checkstyle/grammar/javadoc/JavadocParser.g4 b/src/main/resources/com/puppycrawl/tools/checkstyle/grammar/javadoc/JavadocParser.g4
@@ -1137,7 +1137,7 @@ reference:  PACKAGE_CLASS (HASH MEMBER parameters?)?
 
 parameters: LEFT_BRACE (ARGUMENT | COMMA | WS | NEWLINE | LEADING_ASTERISK)* RIGHT_BRACE;
 
-javadocTag: AUTHOR_LITERAL (WS | NEWLINE)+ description
+javadocTag: AUTHOR_LITERAL (WS | NEWLINE)* ((WS | NEWLINE) description)?
 
     | DEPRECATED_LITERAL (WS | NEWLINE)* ((WS | NEWLINE) description)?
 
@@ -1147,7 +1147,7 @@ javadocTag: AUTHOR_LITERAL (WS | NEWLINE)+ description
       | PARAM_LITERAL (WS | NEWLINE | {!isNextJavadocTag()}? LEADING_ASTERISK)+ PARAMETER_NAME
           (WS | NEWLINE)* ((WS | NEWLINE) description)?
 
-      | RETURN_LITERAL (WS | NEWLINE)+ description
+      | RETURN_LITERAL (WS | NEWLINE)* ((WS | NEWLINE) description)?
 
       | SEE_LITERAL (WS | NEWLINE | {!isNextJavadocTag()}? LEADING_ASTERISK)+
           (reference | STRING | htmlElement) (WS | NEWLINE)* ((WS | NEWLINE) description)?
@@ -1160,12 +1160,12 @@ javadocTag: AUTHOR_LITERAL (WS | NEWLINE)+ description
       | SERIAL_FIELD_LITERAL (WS | NEWLINE)* ((WS | NEWLINE) FIELD_NAME)? (WS | NEWLINE)*
           ((WS | NEWLINE) FIELD_TYPE)? (WS | NEWLINE)* ((WS | NEWLINE) description)?
 
-      | SINCE_LITERAL (WS | NEWLINE)+ description
+      | SINCE_LITERAL (WS | NEWLINE)* ((WS | NEWLINE) description)?
 
       | THROWS_LITERAL (WS | NEWLINE | {!isNextJavadocTag()}? LEADING_ASTERISK)+ CLASS_NAME
           (WS | NEWLINE)* ((WS | NEWLINE) description)?
 
-      | VERSION_LITERAL (WS | NEWLINE)+ description
+      | VERSION_LITERAL (WS | NEWLINE)* ((WS | NEWLINE) description)?
 
       | CUSTOM_NAME (WS | NEWLINE)* ((WS | NEWLINE) description)?
     ;

diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheckTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheckTest.java
@@ -77,20 +77,12 @@ public void setUp(@SysErr Capturable systemErr) {
     public void testJavadocTagsWithoutArgs() throws Exception {
         final DefaultConfiguration checkconfig = createModuleConfig(TempCheck.class);
         final String[] expected = {
-            "9: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 7,
-                    "mismatched input '<EOF>' expecting {WS, NEWLINE}", "JAVADOC_TAG"),
             "14: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 4,
                     "no viable alternative at input '<EOF>'", "JAVADOC_TAG"),
-            "17: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 6,
-                    "mismatched input '<EOF>' expecting {WS, NEWLINE}", "JAVADOC_TAG"),
-            "20: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 8,
-                    "mismatched input '<EOF>' expecting {WS, NEWLINE}", "JAVADOC_TAG"),
             "26: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 10,
                     "no viable alternative at input '<EOF>'", "JAVADOC_TAG"),
             "31: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 7,
                     "no viable alternative at input '<EOF>'", "JAVADOC_TAG"),
-            "36: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 7,
-                    "mismatched input '<EOF>' expecting {WS, NEWLINE}", "JAVADOC_TAG"),
             "41: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 6,
                     "no viable alternative at input '<EOF>'", "JAVADOC_TAG"),
             "62: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 13,

diff --git a/.../com/puppycrawl/tools/checkstyle/checks/javadoc/NonEmptyAtclauseDescriptionCheckTest.java b/.../com/puppycrawl/tools/checkstyle/checks/javadoc/NonEmptyAtclauseDescriptionCheckTest.java
@@ -90,6 +90,8 @@ public void testCheckTwo() throws Exception {
             "20: " + getCheckMessage(MSG_KEY),
             "51: " + getCheckMessage(MSG_KEY),
             "60: " + getCheckMessage(MSG_KEY),
+            "75: " + getCheckMessage(MSG_KEY),
+            "77: " + getCheckMessage(MSG_KEY),
         };
         verifyWithInlineConfigParser(getPath("InputNonEmptyAtclauseDescriptionTwo.java"), expected);
     }

diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/grammar/javadoc/JavadocParseTreeTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/grammar/javadoc/JavadocParseTreeTest.java
@@ -281,6 +281,12 @@ public void testSpaceBeforeDescriptionInBlockJavadocTags() throws Exception {
                 getDocPath("InputSpaceBeforeDescriptionInBlockJavadocTags.javadoc"));
     }
 
+    @Test
+    public void testEmptyDescriptionBeforeTags() throws Exception {
+        verifyJavadocTree(getDocPath("expectedEmptyDescriptionBeforeTags.txt"),
+                getDocPath("InputEmptyDescriptionBeforeTags.javadoc"));
+    }
+
     @Test
     public void testSpaceBeforeDescriptionInInlineTags() throws Exception {
         verifyJavadocTree(getDocPath("expectedSpaceBeforeArgsInInlineTagsAst.txt"),

diff --git a/...checkstyle/checks/javadoc/abstractjavadoc/InputAbstractJavadocJavadocTagsWithoutArgs.java b/...checkstyle/checks/javadoc/abstractjavadoc/InputAbstractJavadocJavadocTagsWithoutArgs.java
@@ -6,18 +6,18 @@
  * Config: TempCheck
  */
 
-/**@author*/ // violation
+/**@author*/ // ok
 public class InputAbstractJavadocJavadocTagsWithoutArgs implements Serializable{
     /**@serial*/ // ok
     private static final long serialVersionUID = 7556448691029650757L;
 
     /**@see*/ // violation
     private static int field2;
 
-    /**@since*/ // violation
+    /**@since*/ // ok
     private static String field3;
 
-    /**@version*/ // violation
+    /**@version*/ // ok
     private static Object field4;
 
     /**serialField*/ // ok
@@ -33,7 +33,7 @@ public static void method2() {
 
     }
 
-    /**@return*/ // violation
+    /**@return*/ // ok
     public static int method3() {
         return -1;
     }

diff --git a/...style/checks/javadoc/nonemptyatclausedescription/InputNonEmptyAtclauseDescriptionTwo.java b/...style/checks/javadoc/nonemptyatclausedescription/InputNonEmptyAtclauseDescriptionTwo.java
@@ -69,4 +69,18 @@ int foo(int a) {
     int bar() {
         return 1;
     }
+
+    /**
+     *
+     * @return
+     *
+     * @throws Exception
+     *
+     */ // violation 4 lines above
+    // violation 3 lines above
+        public int foo7() throws Exception
+        {
+                return 1;
+        }
+
 }
diff --git a/...rawl/tools/checkstyle/grammar/javadoc/javadocTags/InputEmptyDescriptionBeforeTags.javadoc b/...rawl/tools/checkstyle/grammar/javadoc/javadocTags/InputEmptyDescriptionBeforeTags.javadoc
@@ -0,0 +1,6 @@
+* @param a
+* @return
+* @author
+* @since
+* @version
+* @param b
diff --git a/...crawl/tools/checkstyle/grammar/javadoc/javadocTags/expectedEmptyDescriptionBeforeTags.txt b/...crawl/tools/checkstyle/grammar/javadoc/javadocTags/expectedEmptyDescriptionBeforeTags.txt
@@ -0,0 +1,36 @@
+JAVADOC -> JAVADOC [0:0]
+|--LEADING_ASTERISK -> * [0:0]
+|--WS ->   [0:1]
+|--JAVADOC_TAG -> JAVADOC_TAG [0:2]
+|   |--PARAM_LITERAL -> @param [0:2]
+|   |--WS ->   [0:8]
+|   |--PARAMETER_NAME -> a [0:9]
+|   `--NEWLINE -> \n [0:10]
+|--LEADING_ASTERISK -> * [1:0]
+|--WS ->   [1:1]
+|--JAVADOC_TAG -> JAVADOC_TAG [1:2]
+|   |--RETURN_LITERAL -> @return [1:2]
+|   `--NEWLINE -> \n [1:9]
+|--LEADING_ASTERISK -> * [2:0]
+|--WS ->   [2:1]
+|--JAVADOC_TAG -> JAVADOC_TAG [2:2]
+|   |--AUTHOR_LITERAL -> @author [2:2]
+|   `--NEWLINE -> \n [2:9]
+|--LEADING_ASTERISK -> * [3:0]
+|--WS ->   [3:1]
+|--JAVADOC_TAG -> JAVADOC_TAG [3:2]
+|   |--SINCE_LITERAL -> @since [3:2]
+|   `--NEWLINE -> \n [3:8]
+|--LEADING_ASTERISK -> * [4:0]
+|--WS ->   [4:1]
+|--JAVADOC_TAG -> JAVADOC_TAG [4:2]
+|   |--VERSION_LITERAL -> @version [4:2]
+|   `--NEWLINE -> \n [4:10]
+|--LEADING_ASTERISK -> * [5:0]
+|--WS ->   [5:1]
+|--JAVADOC_TAG -> JAVADOC_TAG [5:2]
+|   |--PARAM_LITERAL -> @param [5:2]
+|   |--WS ->   [5:8]
+|   |--PARAMETER_NAME -> b [5:9]
+|   `--NEWLINE -> \n [5:10]
+`--EOF -> <EOF> [6:0]