Skip to content

Commit 3f0fec8

Browse files
kkoutsilisnrmancuso
kkoutsilis
authored and
nrmancuso
committed
Issue #9745: Added JavadocMethod inline return tag support
1 parent 381a852 commit 3f0fec8

File tree

8 files changed

+217
-2
lines changed

8 files changed

+217
-2
lines changed

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

+29-2
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,11 @@
115115
* Default value is {@code public, protected, package, private}.
116116
* </li>
117117
* <li>
118+
* Property {@code allowInlineReturn} - Control whether to allow inline return tags.
119+
* Type is {@code boolean}.
120+
* Default value is {@code false}.
121+
* </li>
122+
* <li>
118123
* Property {@code allowMissingParamTags} - Control whether to ignore violations
119124
* when a method has parameters but does not have matching {@code param} tags in the javadoc.
120125
* Type is {@code boolean}.
@@ -256,13 +261,21 @@ public class JavadocMethodCheck extends AbstractCheck {
256261
/** Compiled regexp to match Javadoc tags with no argument. */
257262
private static final Pattern MATCH_JAVADOC_NOARG =
258263
CommonUtil.createPattern("^\\s*(?>\\*|\\/\\*\\*)?\\s*@(return|see)\\s+\\S");
264+
/** Compiled regexp to match Javadoc tags with no argument allowing inline return tag. */
265+
private static final Pattern MATCH_JAVADOC_NOARG_INLINE_RETURN =
266+
CommonUtil.createPattern("^\\s*(?>\\*|\\/\\*\\*)?\\s*\\{?@(return|see)\\s+\\S");
259267
/** Compiled regexp to match first part of multilineJavadoc tags. */
260268
private static final Pattern MATCH_JAVADOC_NOARG_MULTILINE_START =
261269
CommonUtil.createPattern("^\\s*(?>\\*|\\/\\*\\*)?\\s*@(return|see)\\s*$");
262270
/** Compiled regexp to match Javadoc tags with no argument and {}. */
263271
private static final Pattern MATCH_JAVADOC_NOARG_CURLY =
264272
CommonUtil.createPattern("\\{\\s*@(inheritDoc)\\s*\\}");
265273

274+
/**
275+
* Control whether to allow inline return tags.
276+
*/
277+
private boolean allowInlineReturn;
278+
266279
/** Specify the access modifiers where Javadoc comments are checked. */
267280
private AccessModifierOption[] accessModifiers = {
268281
AccessModifierOption.PUBLIC,
@@ -291,6 +304,16 @@ public class JavadocMethodCheck extends AbstractCheck {
291304
/** Specify annotations that allow missed documentation. */
292305
private Set<String> allowedAnnotations = Set.of("Override");
293306

307+
/**
308+
* Setter to control whether to allow inline return tags.
309+
*
310+
* @param value a {@code boolean} value
311+
* @since 10.22.1
312+
*/
313+
public void setAllowInlineReturn(boolean value) {
314+
allowInlineReturn = value;
315+
}
316+
294317
/**
295318
* Setter to control whether to validate {@code throws} tags.
296319
*
@@ -511,7 +534,11 @@ private boolean hasShortCircuitTag(final DetailAST ast, final List<JavadocTag> t
511534
* @param comment the Javadoc comment
512535
* @return the tags found
513536
*/
514-
private static List<JavadocTag> getMethodTags(TextBlock comment) {
537+
private List<JavadocTag> getMethodTags(TextBlock comment) {
538+
Pattern matchJavadocNoArg = MATCH_JAVADOC_NOARG;
539+
if (allowInlineReturn) {
540+
matchJavadocNoArg = MATCH_JAVADOC_NOARG_INLINE_RETURN;
541+
}
515542
final String[] lines = comment.getText();
516543
final List<JavadocTag> tags = new ArrayList<>();
517544
int currentLine = comment.getStartLineNo() - 1;
@@ -524,7 +551,7 @@ private static List<JavadocTag> getMethodTags(TextBlock comment) {
524551
final Matcher javadocArgMissingDescriptionMatcher =
525552
MATCH_JAVADOC_ARG_MISSING_DESCRIPTION.matcher(lines[i]);
526553
final Matcher javadocNoargMatcher =
527-
MATCH_JAVADOC_NOARG.matcher(lines[i]);
554+
matchJavadocNoArg.matcher(lines[i]);
528555
final Matcher noargCurlyMatcher =
529556
MATCH_JAVADOC_NOARG_CURLY.matcher(lines[i]);
530557
final Matcher noargMultilineStart =

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

+3
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,9 @@
7474
<description>Specify the access modifiers where Javadoc comments are
7575
checked.</description>
7676
</property>
77+
<property default-value="false" name="allowInlineReturn" type="boolean">
78+
<description>Control whether to allow inline return tags.</description>
79+
</property>
7780
<property default-value="false" name="allowMissingParamTags" type="boolean">
7881
<description>Control whether to ignore violations
7982
when a method has parameters but does not have matching {@code param} tags in the javadoc.</description>

‎src/site/xdoc/checks/javadoc/javadocmethod.xml

+38
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,13 @@ public int checkReturnTag(final int aTagIndex,
100100
<td><code>public, protected, package, private</code></td>
101101
<td>8.42</td>
102102
</tr>
103+
<tr>
104+
<td>allowInlineReturn</td>
105+
<td>Control whether to allow inline return tags.</td>
106+
<td><a href="../../property_types.html#boolean">boolean</a></td>
107+
<td><code>false</code></td>
108+
<td>10.22.1</td>
109+
</tr>
103110
<tr>
104111
<td>allowMissingParamTags</td>
105112
<td>Control whether to ignore violations when a method has parameters but does not have matching <code>param</code> tags in the javadoc.</td>
@@ -482,6 +489,37 @@ public class Example7 {
482489
};
483490
}
484491
}
492+
</code></pre></div>
493+
494+
<p id="Example8-config">
495+
To configure the check to allow inline <code>return</code> tags,
496+
you can use following config.
497+
</p>
498+
<div class="wrapper"><pre class="prettyprint"><code class="language-xml">
499+
&lt;module name="Checker"&gt;
500+
&lt;module name="TreeWalker"&gt;
501+
&lt;module name="JavadocMethod"&gt;
502+
&lt;property name="allowInlineReturn" value="true"/&gt;
503+
&lt;/module&gt;
504+
&lt;/module&gt;
505+
&lt;/module&gt;
506+
</code></pre></div>
507+
<p id="Example8-code"> Example:</p>
508+
<div class="wrapper"><pre class="prettyprint"><code class="language-java">
509+
public class Example8 {
510+
511+
/**
512+
* {@return the foo}
513+
*/
514+
public int getFoo() { return 0; }
515+
516+
/**
517+
* Returns the bar
518+
* @return the bar
519+
*/
520+
public int getBar() { return 0; }
521+
522+
}
485523
</code></pre></div>
486524
</subsection>
487525
<subsection name="Example of Usage" id="Example_of_Usage">

‎src/site/xdoc/checks/javadoc/javadocmethod.xml.template

+16
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,22 @@ public int checkReturnTag(final int aTagIndex,
195195
value="resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/Example7.java"/>
196196
<param name="type" value="code"/>
197197
</macro>
198+
199+
<p id="Example8-config">
200+
To configure the check to allow inline <code>return</code> tags,
201+
you can use following config.
202+
</p>
203+
<macro name="example">
204+
<param name="path"
205+
value="resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/Example8.java"/>
206+
<param name="type" value="config"/>
207+
</macro>
208+
<p id="Example8-code"> Example:</p>
209+
<macro name="example">
210+
<param name="path"
211+
value="resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/Example8.java"/>
212+
<param name="type" value="code"/>
213+
</macro>
198214
</subsection>
199215
<subsection name="Example of Usage" id="Example_of_Usage">
200216
<ul>

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

+21
Original file line numberDiff line numberDiff line change
@@ -590,4 +590,25 @@ public void testJavadocMethodAboveComments() throws Exception {
590590
verifyWithInlineConfigParser(
591591
getPath("InputJavadocMethodAboveComments.java"), expected);
592592
}
593+
594+
@Test
595+
public void testJavadocMethodAllowInlineReturn() throws Exception {
596+
final String[] expected = {
597+
"32: " + getCheckMessage(MSG_RETURN_EXPECTED),
598+
"39: " + getCheckMessage(MSG_RETURN_EXPECTED),
599+
};
600+
verifyWithInlineConfigParser(
601+
getPath("InputJavadocMethodAllowInlineReturn.java"), expected);
602+
}
603+
604+
@Test
605+
public void testJavadocMethodDoNotAllowInlineReturn() throws Exception {
606+
final String[] expected = {
607+
"21: " + getCheckMessage(MSG_RETURN_EXPECTED),
608+
"33: " + getCheckMessage(MSG_RETURN_EXPECTED),
609+
"40: " + getCheckMessage(MSG_RETURN_EXPECTED),
610+
};
611+
verifyWithInlineConfigParser(
612+
getPath("InputJavadocMethodDoNotAllowInlineReturn.java"), expected);
613+
}
593614
}

‎src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodAllowInlineReturn.java

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
/*
2+
JavadocMethod
3+
allowInlineReturn = true
4+
allowedAnnotations = (default)Override
5+
validateThrows = (default)false
6+
accessModifiers = (default)public, protected, package, private
7+
allowMissingParamTags = (default)false
8+
allowMissingReturnTag = (default)false
9+
tokens = (default)METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF, COMPACT_CTOR_DEF
10+
11+
12+
*/
13+
14+
package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
15+
16+
public class InputJavadocMethodAllowInlineReturn {
17+
18+
/**
19+
* {@return the foo}
20+
*/
21+
public int getFoo() { return 0; }
22+
23+
/**
24+
* Returns the bar
25+
* @return the bar
26+
*/
27+
public int getBar() { return 0; }
28+
29+
/**
30+
* Returns the fiz
31+
*/
32+
public int getFiz() { return 0; }
33+
// violation above, '@return tag should be present and have description.'
34+
35+
/**
36+
* Returns the baz
37+
* @see "getFoo"
38+
*/
39+
public int getBaz() { return 0; }
40+
// violation above, '@return tag should be present and have description.'
41+
}

‎src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/InputJavadocMethodDoNotAllowInlineReturn.java

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
/*
2+
JavadocMethod
3+
allowInlineReturn = (default)false
4+
allowedAnnotations = (default)Override
5+
validateThrows = (default)false
6+
accessModifiers = (default)public, protected, package, private
7+
allowMissingParamTags = (default)false
8+
allowMissingReturnTag = (default)false
9+
tokens = (default)METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF, COMPACT_CTOR_DEF
10+
11+
12+
*/
13+
14+
package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
15+
16+
public class InputJavadocMethodDoNotAllowInlineReturn {
17+
18+
/**
19+
* {@return the foo}
20+
*/
21+
public int getFoo() { return 0; }
22+
// violation above, '@return tag should be present and have description.'
23+
24+
/**
25+
* Returns the bar
26+
* @return the bar
27+
*/
28+
public int getBar() { return 0; }
29+
30+
/**
31+
* Returns the fiz
32+
*/
33+
public int getFiz() { return 0; }
34+
// violation above, '@return tag should be present and have description.'
35+
36+
/**
37+
* Returns the baz
38+
* @see "getFoo"
39+
*/
40+
public int getBaz() { return 0; }
41+
// violation above, '@return tag should be present and have description.'
42+
}

‎src/xdocs-examples/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/Example8.java

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
/*xml
2+
<module name="Checker">
3+
<module name="TreeWalker">
4+
<module name="JavadocMethod">
5+
<property name="allowInlineReturn" value="true"/>
6+
</module>
7+
</module>
8+
</module>
9+
*/
10+
package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
11+
12+
// xdoc section -- start
13+
public class Example8 {
14+
15+
/**
16+
* {@return the foo}
17+
*/
18+
public int getFoo() { return 0; }
19+
20+
/**
21+
* Returns the bar
22+
* @return the bar
23+
*/
24+
public int getBar() { return 0; }
25+
26+
}
27+
// xdoc section -- end

0 commit comments

Comments
 (0)