Issue #6586: aligned javadoc/xdoc for ReturnCount

src/main/java/com/puppycrawl/tools/checkstyle/checks/coding/ReturnCountCheck.java

@@ -46,10 +46,92 @@
  * of 0.
  * </p>
  * <p>
- * Rationale: Too many return points can be indication that code is
+ * Rationale: Too many return points can mean that code is
  * attempting to do too much or may be difficult to understand.
  * </p>
+ * <ul>
+ * <li>
+ * Property {@code max} - Specify maximum allowed number of return statements
+ * in non-void methods/lambdas.
+ * Default value is {@code 2}.
+ * </li>
+ * <li>
+ * Property {@code maxForVoid} - Specify maximum allowed number of return statements
+ * in void methods/constructors/lambdas.
+ * Default value is {@code 1}.
+ * </li>
+ * <li>
+ * Property {@code format} - Specify method names to ignore.
+ * Default value is {@code "^equals$"}.
+ * </li>
+ * <li>
+ * Property {@code tokens} - tokens to check Default value is:
+ * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">
+ * CTOR_DEF</a>,
+ * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">
+ * METHOD_DEF</a>,
+ * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LAMBDA">
+ * LAMBDA</a>.
+ * </li>
+ * </ul>
+ * <p>
+ * To configure the check so that it doesn't allow more than three return statements per method
+ * (ignoring the {@code equals()} method):
+ * </p>
+ * <pre>
+ * &lt;module name=&quot;ReturnCount&quot;&gt;
+ *   &lt;property name=&quot;max&quot; value=&quot;3&quot;/&gt;
+ * &lt;/module&gt;
+ * </pre>
+ * <p>
+ * To configure the check so that it doesn't allow any return statements per void method:
+ * </p>
+ * <pre>
+ * &lt;module name=&quot;ReturnCount&quot;&gt;
+ *   &lt;property name=&quot;maxForVoid&quot; value=&quot;0&quot;/&gt;
+ * &lt;/module&gt;
+ * </pre>
+ * <p>
+ * To configure the check so that it doesn't allow more than 2 return statements per method
+ * (ignoring the {@code equals()} method) and more than 1 return statements per void method:
+ * </p>
+ * <pre>
+ * &lt;module name=&quot;ReturnCount&quot;&gt;
+ *   &lt;property name=&quot;max&quot; value=&quot;2&quot;/&gt;
+ *   &lt;property name=&quot;maxForVoid&quot; value=&quot;1&quot;/&gt;
+ * &lt;/module&gt;
+ * </pre>
+ * <p>
+ * To configure the check so that it doesn't allow more than three
+ * return statements per method for all methods:
+ * </p>
+ * <pre>
+ * &lt;module name=&quot;ReturnCount&quot;&gt;
+ *   &lt;property name=&quot;max&quot; value=&quot;3&quot;/&gt;
+ *   &lt;property name=&quot;format&quot; value=&quot;^$&quot;/&gt;
+ * &lt;/module&gt;
+ * </pre>
+ * <p>
+ * To configure the check so that it doesn't allow any return statements in constructors,
+ * more than one return statement in all lambda expressions and more than two return
+ * statements in methods:
+ * </p>
+ * <pre>
+ * &lt;module name=&quot;ReturnCount&quot;&gt;
+ *   &lt;property name=&quot;max&quot; value=&quot;0&quot;/&gt;
+ *   &lt;property name=&quot;tokens&quot; value=&quot;CTOR_DEF&quot;/&gt;
+ * &lt;/module&gt;
+ * &lt;module name=&quot;ReturnCount&quot;&gt;
+ *   &lt;property name=&quot;max&quot; value=&quot;1&quot;/&gt;
+ *   &lt;property name=&quot;tokens&quot; value=&quot;LAMBDA&quot;/&gt;
+ * &lt;/module&gt;
+ * &lt;module name=&quot;ReturnCount&quot;&gt;
+ *   &lt;property name=&quot;max&quot; value=&quot;2&quot;/&gt;
+ *   &lt;property name=&quot;tokens&quot; value=&quot;METHOD_DEF&quot;/&gt;
+ * &lt;/module&gt;
+ * </pre>
  *
+ * @since 3.2
  */
 @FileStatefulCheck
 public final class ReturnCountCheck extends AbstractCheck {
@@ -68,12 +150,12 @@ public final class ReturnCountCheck extends AbstractCheck {
     /** Stack of method contexts. */
     private final Deque<Context> contextStack = new ArrayDeque<>();
 
-    /** The regexp to match against. */
+    /** Specify method names to ignore. */
     private Pattern format = Pattern.compile("^equals$");
 
-    /** Maximum allowed number of return statements. */
+    /** Specify maximum allowed number of return statements in non-void methods/lambdas. */
     private int max = 2;
-    /** Maximum allowed number of return statements for void methods. */
+    /** Specify maximum allowed number of return statements in void methods/constructors/lambdas. */
     private int maxForVoid = 1;
     /** Current method context. */
     private Context context;
@@ -104,23 +186,25 @@ public int[] getAcceptableTokens() {
     }
 
     /**
-     * Set the format for the specified regular expression.
+     * Setter to specify method names to ignore.
      * @param pattern a pattern.
      */
     public void setFormat(Pattern pattern) {
         format = pattern;
     }
 
     /**
-     * Setter for max property.
+     * Setter to specify maximum allowed number of return statements
+     * in non-void methods/lambdas.
      * @param max maximum allowed number of return statements.
      */
     public void setMax(int max) {
         this.max = max;
     }
 
     /**
-     * Setter for maxForVoid property.
+     * Setter to specify maximum allowed number of return statements
+     * in void methods/constructors/lambdas.
      * @param maxForVoid maximum allowed number of return statements for void methods.
      */
     public void setMaxForVoid(int maxForVoid) {

src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java

@@ -128,6 +128,7 @@ public class XdocsJavaDocsTest extends AbstractModuleTestSupport {
         "ParameterAssignment",
         "ParameterName",
         "RequireThis",
+        "ReturnCount",
         "RightCurly",
         "SimplifyBooleanExpression",
         "SimplifyBooleanReturn",

src/xdocs/config_coding.xml

@@ -4125,8 +4125,8 @@ class C {
     </section>
 
     <section name="ReturnCount">
+      <p>Since Checkstyle 3.2</p>
       <subsection name="Description" id="ReturnCount_Description">
-        <p>Since Checkstyle 3.2</p>
         <p>
           Restricts the number of return statements in methods, constructors and lambda expressions
           (2 by default). Ignores specified methods (<code>equals()</code> by default).
@@ -4162,22 +4162,24 @@ class C {
           </tr>
           <tr>
             <td>max</td>
-            <td>maximum allowed number of return statements in non-void methods/lambdas</td>
+            <td>
+              Specify maximum allowed number of return statements in non-void methods/lambdas.
+            </td>
             <td><a href="property_types.html#integer">Integer</a></td>
             <td><code>2</code></td>
             <td>3.2</td>
           </tr>
           <tr>
             <td>maxForVoid</td>
-            <td>maximum allowed number of return statements in void
-                methods/constructors/lambdas</td>
+            <td>Specify maximum allowed number of return statements in void
+                methods/constructors/lambdas.</td>
             <td><a href="property_types.html#integer">Integer</a></td>
             <td><code>1</code></td>
             <td>6.19</td>
           </tr>
           <tr>
             <td>format</td>
-            <td>method names to ignore</td>
+            <td>Specify method names to ignore.</td>
             <td><a href="property_types.html#regexp">Regular Expression</a></td>
             <td><code>"^equals$"</code></td>
             <td>3.4</td>