Issue #9745: Added JavadocMethod inline return tag support

Author: kkoutsilis

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

@@ -115,6 +115,11 @@
  * Default value is {@code public, protected, package, private}.
  * </li>
  * <li>
+ * Property {@code allowInlineReturn} - Control whether to allow inline return tags.
+ * Type is {@code boolean}.
+ * Default value is {@code false}.
+ * </li>
+ * <li>
  * Property {@code allowMissingParamTags} - Control whether to ignore violations
  * when a method has parameters but does not have matching {@code param} tags in the javadoc.
  * Type is {@code boolean}.
@@ -256,13 +261,21 @@ public class JavadocMethodCheck extends AbstractCheck {
     /** Compiled regexp to match Javadoc tags with no argument. */
     private static final Pattern MATCH_JAVADOC_NOARG =
             CommonUtil.createPattern("^\\s*(?>\\*|\\/\\*\\*)?\\s*@(return|see)\\s+\\S");
+    /** Compiled regexp to match Javadoc tags with no argument allowing inline return tag. */
+    private static final Pattern MATCH_JAVADOC_NOARG_INLINE_RETURN =
+            CommonUtil.createPattern("^\\s*(?>\\*|\\/\\*\\*)?\\s*\\{?@(return|see)\\s+\\S");
     /** Compiled regexp to match first part of multilineJavadoc tags. */
     private static final Pattern MATCH_JAVADOC_NOARG_MULTILINE_START =
             CommonUtil.createPattern("^\\s*(?>\\*|\\/\\*\\*)?\\s*@(return|see)\\s*$");
     /** Compiled regexp to match Javadoc tags with no argument and {}. */
     private static final Pattern MATCH_JAVADOC_NOARG_CURLY =
             CommonUtil.createPattern("\\{\\s*@(inheritDoc)\\s*\\}");
 
+    /**
+     * Control whether to allow inline return tags.
+     */
+    private boolean allowInlineReturn;
+
     /** Specify the access modifiers where Javadoc comments are checked. */
     private AccessModifierOption[] accessModifiers = {
         AccessModifierOption.PUBLIC,
@@ -291,6 +304,16 @@ public class JavadocMethodCheck extends AbstractCheck {
     /** Specify annotations that allow missed documentation. */
     private Set<String> allowedAnnotations = Set.of("Override");
 
+    /**
+     * Setter to control whether to allow inline return tags.
+     *
+     * @param value a {@code boolean} value
+     * @since 10.22.1
+     */
+    public void setAllowInlineReturn(boolean value) {
+        allowInlineReturn = value;
+    }
+
     /**
      * Setter to control whether to validate {@code throws} tags.
      *
@@ -511,7 +534,11 @@ private boolean hasShortCircuitTag(final DetailAST ast, final List<JavadocTag> t
      * @param comment the Javadoc comment
      * @return the tags found
      */
-    private static List<JavadocTag> getMethodTags(TextBlock comment) {
+    private List<JavadocTag> getMethodTags(TextBlock comment) {
+        Pattern matchJavadocNoArg = MATCH_JAVADOC_NOARG;
+        if (allowInlineReturn) {
+            matchJavadocNoArg = MATCH_JAVADOC_NOARG_INLINE_RETURN;
+        }
         final String[] lines = comment.getText();
         final List<JavadocTag> tags = new ArrayList<>();
         int currentLine = comment.getStartLineNo() - 1;
@@ -524,7 +551,7 @@ private static List<JavadocTag> getMethodTags(TextBlock comment) {
             final Matcher javadocArgMissingDescriptionMatcher =
                 MATCH_JAVADOC_ARG_MISSING_DESCRIPTION.matcher(lines[i]);
             final Matcher javadocNoargMatcher =
-                MATCH_JAVADOC_NOARG.matcher(lines[i]);
+                matchJavadocNoArg.matcher(lines[i]);
             final Matcher noargCurlyMatcher =
                 MATCH_JAVADOC_NOARG_CURLY.matcher(lines[i]);
             final Matcher noargMultilineStart =

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

@@ -74,6 +74,9 @@
                <description>Specify the access modifiers where Javadoc comments are
  checked.</description>
             </property>
+            <property default-value="false" name="allowInlineReturn" type="boolean">
+               <description>Control whether to allow inline return tags.</description>
+            </property>
             <property default-value="false" name="allowMissingParamTags" type="boolean">
                <description>Control whether to ignore violations
  when a method has parameters but does not have matching {@code param} tags in the javadoc.</description>

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

@@ -100,6 +100,13 @@ public int checkReturnTag(final int aTagIndex,
               <td><code>public, protected, package, private</code></td>
               <td>8.42</td>
             </tr>
+            <tr>
+              <td>allowInlineReturn</td>
+              <td>Control whether to allow inline return tags.</td>
+              <td><a href="../../property_types.html#boolean">boolean</a></td>
+              <td><code>false</code></td>
+              <td>10.22.1</td>
+            </tr>
             <tr>
               <td>allowMissingParamTags</td>
               <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 {
     };
   }
 }
+</code></pre></div>
+
+        <p id="Example8-config">
+          To configure the check to allow inline <code>return</code> tags,
+          you can use following config.
+        </p>
+        <div class="wrapper"><pre class="prettyprint"><code class="language-xml">
+&lt;module name="Checker"&gt;
+  &lt;module name="TreeWalker"&gt;
+    &lt;module name="JavadocMethod"&gt;
+        &lt;property name="allowInlineReturn" value="true"/&gt;
+    &lt;/module&gt;
+  &lt;/module&gt;
+&lt;/module&gt;
+</code></pre></div>
+        <p id="Example8-code"> Example:</p>
+        <div class="wrapper"><pre class="prettyprint"><code class="language-java">
+public class Example8 {
+
+  /**
+   * {@return the foo}
+   */
+  public int getFoo() { return 0; }
+
+  /**
+   * Returns the bar
+   * @return the bar
+   */
+  public int getBar() { return 0; }
+
+}
 </code></pre></div>
       </subsection>
       <subsection name="Example of Usage" id="Example_of_Usage">

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

@@ -195,6 +195,22 @@ public int checkReturnTag(final int aTagIndex,
                  value="resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/Example7.java"/>
           <param name="type" value="code"/>
         </macro>
+
+        <p id="Example8-config">
+          To configure the check to allow inline <code>return</code> tags,
+          you can use following config.
+        </p>
+        <macro name="example">
+          <param name="path"
+                 value="resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/Example8.java"/>
+          <param name="type" value="config"/>
+        </macro>
+        <p id="Example8-code"> Example:</p>
+        <macro name="example">
+          <param name="path"
+                 value="resources/com/puppycrawl/tools/checkstyle/checks/javadoc/javadocmethod/Example8.java"/>
+          <param name="type" value="code"/>
+        </macro>
       </subsection>
       <subsection name="Example of Usage" id="Example_of_Usage">
         <ul>

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

@@ -590,4 +590,25 @@ public void testJavadocMethodAboveComments() throws Exception {
         verifyWithInlineConfigParser(
                 getPath("InputJavadocMethodAboveComments.java"), expected);
     }
+
+    @Test
+    public void testJavadocMethodAllowInlineReturn() throws Exception {
+        final String[] expected = {
+            "32: " + getCheckMessage(MSG_RETURN_EXPECTED),
+            "39: " + getCheckMessage(MSG_RETURN_EXPECTED),
+        };
+        verifyWithInlineConfigParser(
+                getPath("InputJavadocMethodAllowInlineReturn.java"), expected);
+    }
+
+    @Test
+    public void testJavadocMethodDoNotAllowInlineReturn() throws Exception {
+        final String[] expected = {
+            "21: " + getCheckMessage(MSG_RETURN_EXPECTED),
+            "33: " + getCheckMessage(MSG_RETURN_EXPECTED),
+            "40: " + getCheckMessage(MSG_RETURN_EXPECTED),
+        };
+        verifyWithInlineConfigParser(
+                getPath("InputJavadocMethodDoNotAllowInlineReturn.java"), expected);
+    }
 }

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

@@ -0,0 +1,41 @@
+/*
+JavadocMethod
+allowInlineReturn = true
+allowedAnnotations = (default)Override
+validateThrows = (default)false
+accessModifiers = (default)public, protected, package, private
+allowMissingParamTags = (default)false
+allowMissingReturnTag = (default)false
+tokens = (default)METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF, COMPACT_CTOR_DEF
+
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
+
+public class InputJavadocMethodAllowInlineReturn {
+
+    /**
+     * {@return the foo}
+     */
+    public int getFoo() { return 0; }
+
+    /**
+     * Returns the bar
+     * @return the bar
+     */
+    public int getBar() { return 0; }
+
+    /**
+     * Returns the fiz
+     */
+    public int getFiz() { return 0; }
+    // violation above, '@return tag should be present and have description.'
+
+    /**
+     * Returns the baz
+     * @see "getFoo"
+     */
+    public int getBaz() { return 0; }
+    // violation above, '@return tag should be present and have description.'
+}

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

@@ -0,0 +1,42 @@
+/*
+JavadocMethod
+allowInlineReturn = (default)false
+allowedAnnotations = (default)Override
+validateThrows = (default)false
+accessModifiers = (default)public, protected, package, private
+allowMissingParamTags = (default)false
+allowMissingReturnTag = (default)false
+tokens = (default)METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF, COMPACT_CTOR_DEF
+
+
+*/
+
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
+
+public class InputJavadocMethodDoNotAllowInlineReturn {
+
+    /**
+     * {@return the foo}
+     */
+    public int getFoo() { return 0; }
+    // violation above, '@return tag should be present and have description.'
+
+    /**
+     * Returns the bar
+     * @return the bar
+     */
+    public int getBar() { return 0; }
+
+    /**
+     * Returns the fiz
+     */
+    public int getFiz() { return 0; }
+    // violation above, '@return tag should be present and have description.'
+
+    /**
+     * Returns the baz
+     * @see "getFoo"
+     */
+    public int getBaz() { return 0; }
+    // violation above, '@return tag should be present and have description.'
+}

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

@@ -0,0 +1,27 @@
+/*xml
+<module name="Checker">
+  <module name="TreeWalker">
+    <module name="JavadocMethod">
+        <property name="allowInlineReturn" value="true"/>
+    </module>
+  </module>
+</module>
+*/
+package com.puppycrawl.tools.checkstyle.checks.javadoc.javadocmethod;
+
+// xdoc section -- start
+public class Example8 {
+
+  /**
+   * {@return the foo}
+   */
+  public int getFoo() { return 0; }
+
+  /**
+   * Returns the bar
+   * @return the bar
+   */
+  public int getBar() { return 0; }
+
+}
+// xdoc section -- end