Skip to content

Commit 7e8b0a6

Browse files
0xbakrynrmancuso
0xbakry
authored and
nrmancuso
committed
Issue #12864: Update Javadoc description to be optional
1 parent 4770064 commit 7e8b0a6

File tree

10 files changed

+74
-45
lines changed

10 files changed

+74
-45
lines changed

‎config/pitest-suppressions/pitest-javadoc-suppressions.xml

Lines changed: 0 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -837,33 +837,6 @@
837837
<lineContent>return (excludeScope == null</lineContent>
838838
</mutation>
839839

840-
<mutation unstable="false">
841-
<sourceFile>NonEmptyAtclauseDescriptionCheck.java</sourceFile>
842-
<mutatedClass>com.puppycrawl.tools.checkstyle.checks.javadoc.NonEmptyAtclauseDescriptionCheck</mutatedClass>
843-
<mutatedMethod>hasOnlyEmptyText</mutatedMethod>
844-
<mutator>org.pitest.mutationtest.engine.gregor.mutators.RemoveConditionalMutator_EQUAL_IF</mutator>
845-
<description>removed conditional - replaced equality check with true</description>
846-
<lineContent>if (child.getType() != JavadocTokenTypes.TEXT</lineContent>
847-
</mutation>
848-
849-
<mutation unstable="false">
850-
<sourceFile>NonEmptyAtclauseDescriptionCheck.java</sourceFile>
851-
<mutatedClass>com.puppycrawl.tools.checkstyle.checks.javadoc.NonEmptyAtclauseDescriptionCheck</mutatedClass>
852-
<mutatedMethod>hasOnlyEmptyText</mutatedMethod>
853-
<mutator>org.pitest.mutationtest.engine.gregor.mutators.NonVoidMethodCallMutator</mutator>
854-
<description>removed call to com/puppycrawl/tools/checkstyle/api/DetailNode::getText</description>
855-
<lineContent>|| !CommonUtil.isBlank(child.getText())) {</lineContent>
856-
</mutation>
857-
858-
<mutation unstable="false">
859-
<sourceFile>NonEmptyAtclauseDescriptionCheck.java</sourceFile>
860-
<mutatedClass>com.puppycrawl.tools.checkstyle.checks.javadoc.NonEmptyAtclauseDescriptionCheck</mutatedClass>
861-
<mutatedMethod>hasOnlyEmptyText</mutatedMethod>
862-
<mutator>org.pitest.mutationtest.engine.gregor.mutators.RemoveConditionalMutator_EQUAL_ELSE</mutator>
863-
<description>removed conditional - replaced equality check with false</description>
864-
<lineContent>|| !CommonUtil.isBlank(child.getText())) {</lineContent>
865-
</mutation>
866-
867840
<mutation unstable="false">
868841
<sourceFile>NonEmptyAtclauseDescriptionCheck.java</sourceFile>
869842
<mutatedClass>com.puppycrawl.tools.checkstyle.checks.javadoc.NonEmptyAtclauseDescriptionCheck</mutatedClass>

‎src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/NonEmptyAtclauseDescriptionCheck.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -181,8 +181,8 @@ private static boolean isEmptyTag(DetailNode tagNode) {
181181
private static boolean hasOnlyEmptyText(DetailNode description) {
182182
boolean result = true;
183183
for (DetailNode child : description.getChildren()) {
184-
if (child.getType() != JavadocTokenTypes.TEXT
185-
|| !CommonUtil.isBlank(child.getText())) {
184+
if (child.getType() != JavadocTokenTypes.LEADING_ASTERISK
185+
&& !CommonUtil.isBlank(child.getText())) {
186186
result = false;
187187
break;
188188
}

‎src/main/resources/com/puppycrawl/tools/checkstyle/grammar/javadoc/JavadocParser.g4

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1137,7 +1137,7 @@ reference: PACKAGE_CLASS (HASH MEMBER parameters?)?
11371137

11381138
parameters: LEFT_BRACE (ARGUMENT | COMMA | WS | NEWLINE | LEADING_ASTERISK)* RIGHT_BRACE;
11391139

1140-
javadocTag: AUTHOR_LITERAL (WS | NEWLINE)+ description
1140+
javadocTag: AUTHOR_LITERAL (WS | NEWLINE)* ((WS | NEWLINE) description)?
11411141

11421142
| DEPRECATED_LITERAL (WS | NEWLINE)* ((WS | NEWLINE) description)?
11431143

@@ -1147,7 +1147,7 @@ javadocTag: AUTHOR_LITERAL (WS | NEWLINE)+ description
11471147
| PARAM_LITERAL (WS | NEWLINE | {!isNextJavadocTag()}? LEADING_ASTERISK)+ PARAMETER_NAME
11481148
(WS | NEWLINE)* ((WS | NEWLINE) description)?
11491149

1150-
| RETURN_LITERAL (WS | NEWLINE)+ description
1150+
| RETURN_LITERAL (WS | NEWLINE)* ((WS | NEWLINE) description)?
11511151

11521152
| SEE_LITERAL (WS | NEWLINE | {!isNextJavadocTag()}? LEADING_ASTERISK)+
11531153
(reference | STRING | htmlElement) (WS | NEWLINE)* ((WS | NEWLINE) description)?
@@ -1160,12 +1160,12 @@ javadocTag: AUTHOR_LITERAL (WS | NEWLINE)+ description
11601160
| SERIAL_FIELD_LITERAL (WS | NEWLINE)* ((WS | NEWLINE) FIELD_NAME)? (WS | NEWLINE)*
11611161
((WS | NEWLINE) FIELD_TYPE)? (WS | NEWLINE)* ((WS | NEWLINE) description)?
11621162

1163-
| SINCE_LITERAL (WS | NEWLINE)+ description
1163+
| SINCE_LITERAL (WS | NEWLINE)* ((WS | NEWLINE) description)?
11641164

11651165
| THROWS_LITERAL (WS | NEWLINE | {!isNextJavadocTag()}? LEADING_ASTERISK)+ CLASS_NAME
11661166
(WS | NEWLINE)* ((WS | NEWLINE) description)?
11671167

1168-
| VERSION_LITERAL (WS | NEWLINE)+ description
1168+
| VERSION_LITERAL (WS | NEWLINE)* ((WS | NEWLINE) description)?
11691169

11701170
| CUSTOM_NAME (WS | NEWLINE)* ((WS | NEWLINE) description)?
11711171
;

‎src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheckTest.java

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -77,20 +77,12 @@ public void setUp(@SysErr Capturable systemErr) {
7777
public void testJavadocTagsWithoutArgs() throws Exception {
7878
final DefaultConfiguration checkconfig = createModuleConfig(TempCheck.class);
7979
final String[] expected = {
80-
"9: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 7,
81-
"mismatched input '<EOF>' expecting {WS, NEWLINE}", "JAVADOC_TAG"),
8280
"14: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 4,
8381
"no viable alternative at input '<EOF>'", "JAVADOC_TAG"),
84-
"17: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 6,
85-
"mismatched input '<EOF>' expecting {WS, NEWLINE}", "JAVADOC_TAG"),
86-
"20: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 8,
87-
"mismatched input '<EOF>' expecting {WS, NEWLINE}", "JAVADOC_TAG"),
8882
"26: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 10,
8983
"no viable alternative at input '<EOF>'", "JAVADOC_TAG"),
9084
"31: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 7,
9185
"no viable alternative at input '<EOF>'", "JAVADOC_TAG"),
92-
"36: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 7,
93-
"mismatched input '<EOF>' expecting {WS, NEWLINE}", "JAVADOC_TAG"),
9486
"41: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 6,
9587
"no viable alternative at input '<EOF>'", "JAVADOC_TAG"),
9688
"62: " + getCheckMessage(MSG_JAVADOC_PARSE_RULE_ERROR, 13,

‎src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/NonEmptyAtclauseDescriptionCheckTest.java

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,8 @@ public void testCheckTwo() throws Exception {
9090
"20: " + getCheckMessage(MSG_KEY),
9191
"51: " + getCheckMessage(MSG_KEY),
9292
"60: " + getCheckMessage(MSG_KEY),
93+
"75: " + getCheckMessage(MSG_KEY),
94+
"77: " + getCheckMessage(MSG_KEY),
9395
};
9496
verifyWithInlineConfigParser(getPath("InputNonEmptyAtclauseDescriptionTwo.java"), expected);
9597
}

‎src/test/java/com/puppycrawl/tools/checkstyle/grammar/javadoc/JavadocParseTreeTest.java

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -281,6 +281,12 @@ public void testSpaceBeforeDescriptionInBlockJavadocTags() throws Exception {
281281
getDocPath("InputSpaceBeforeDescriptionInBlockJavadocTags.javadoc"));
282282
}
283283

284+
@Test
285+
public void testEmptyDescriptionBeforeTags() throws Exception {
286+
verifyJavadocTree(getDocPath("expectedEmptyDescriptionBeforeTags.txt"),
287+
getDocPath("InputEmptyDescriptionBeforeTags.javadoc"));
288+
}
289+
284290
@Test
285291
public void testSpaceBeforeDescriptionInInlineTags() throws Exception {
286292
verifyJavadocTree(getDocPath("expectedSpaceBeforeArgsInInlineTagsAst.txt"),

‎src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/abstractjavadoc/InputAbstractJavadocJavadocTagsWithoutArgs.java

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,18 @@
66
* Config: TempCheck
77
*/
88

9-
/**@author*/ // violation
9+
/**@author*/ // ok
1010
public class InputAbstractJavadocJavadocTagsWithoutArgs implements Serializable{
1111
/**@serial*/ // ok
1212
private static final long serialVersionUID = 7556448691029650757L;
1313

1414
/**@see*/ // violation
1515
private static int field2;
1616

17-
/**@since*/ // violation
17+
/**@since*/ // ok
1818
private static String field3;
1919

20-
/**@version*/ // violation
20+
/**@version*/ // ok
2121
private static Object field4;
2222

2323
/**serialField*/ // ok
@@ -33,7 +33,7 @@ public static void method2() {
3333

3434
}
3535

36-
/**@return*/ // violation
36+
/**@return*/ // ok
3737
public static int method3() {
3838
return -1;
3939
}

‎src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/nonemptyatclausedescription/InputNonEmptyAtclauseDescriptionTwo.java

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,4 +69,18 @@ int foo(int a) {
6969
int bar() {
7070
return 1;
7171
}
72+
73+
/**
74+
*
75+
* @return
76+
*
77+
* @throws Exception
78+
*
79+
*/ // violation 4 lines above
80+
// violation 3 lines above
81+
public int foo7() throws Exception
82+
{
83+
return 1;
84+
}
85+
7286
}

‎src/test/resources/com/puppycrawl/tools/checkstyle/grammar/javadoc/javadocTags/InputEmptyDescriptionBeforeTags.javadoc

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
* @param a
2+
* @return
3+
* @author
4+
* @since
5+
* @version
6+
* @param b

‎src/test/resources/com/puppycrawl/tools/checkstyle/grammar/javadoc/javadocTags/expectedEmptyDescriptionBeforeTags.txt

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
JAVADOC -> JAVADOC [0:0]
2+
|--LEADING_ASTERISK -> * [0:0]
3+
|--WS -> [0:1]
4+
|--JAVADOC_TAG -> JAVADOC_TAG [0:2]
5+
| |--PARAM_LITERAL -> @param [0:2]
6+
| |--WS -> [0:8]
7+
| |--PARAMETER_NAME -> a [0:9]
8+
| `--NEWLINE -> \n [0:10]
9+
|--LEADING_ASTERISK -> * [1:0]
10+
|--WS -> [1:1]
11+
|--JAVADOC_TAG -> JAVADOC_TAG [1:2]
12+
| |--RETURN_LITERAL -> @return [1:2]
13+
| `--NEWLINE -> \n [1:9]
14+
|--LEADING_ASTERISK -> * [2:0]
15+
|--WS -> [2:1]
16+
|--JAVADOC_TAG -> JAVADOC_TAG [2:2]
17+
| |--AUTHOR_LITERAL -> @author [2:2]
18+
| `--NEWLINE -> \n [2:9]
19+
|--LEADING_ASTERISK -> * [3:0]
20+
|--WS -> [3:1]
21+
|--JAVADOC_TAG -> JAVADOC_TAG [3:2]
22+
| |--SINCE_LITERAL -> @since [3:2]
23+
| `--NEWLINE -> \n [3:8]
24+
|--LEADING_ASTERISK -> * [4:0]
25+
|--WS -> [4:1]
26+
|--JAVADOC_TAG -> JAVADOC_TAG [4:2]
27+
| |--VERSION_LITERAL -> @version [4:2]
28+
| `--NEWLINE -> \n [4:10]
29+
|--LEADING_ASTERISK -> * [5:0]
30+
|--WS -> [5:1]
31+
|--JAVADOC_TAG -> JAVADOC_TAG [5:2]
32+
| |--PARAM_LITERAL -> @param [5:2]
33+
| |--WS -> [5:8]
34+
| |--PARAMETER_NAME -> b [5:9]
35+
| `--NEWLINE -> \n [5:10]
36+
`--EOF -> <EOF> [6:0]

0 commit comments

Comments
 (0)