Skip to content

Commit

Permalink
Issue checkstyle#6532: aligned javadoc/xdoc for NeedBraces
Browse files Browse the repository at this point in the history
  • Loading branch information
@pbludov
pbludov committed Mar 9, 2019
1 parent a2a13dc commit 7318eb5
Show file tree
Hide file tree
Showing 3 changed files with 65 additions and 74 deletions.
125 changes: 58 additions & 67 deletions src/main/java/com/puppycrawl/tools/checkstyle/checks/blocks/NeedBracesCheck.java
View file
Expand Up @@ -29,107 +29,98 @@
* <p>
* Checks for braces around code blocks.
* </p>
* <p> By default the check will check the following blocks:
* {@link TokenTypes#LITERAL_DO LITERAL_DO},
* {@link TokenTypes#LITERAL_ELSE LITERAL_ELSE},
* {@link TokenTypes#LITERAL_FOR LITERAL_FOR},
* {@link TokenTypes#LITERAL_IF LITERAL_IF},
* {@link TokenTypes#LITERAL_WHILE LITERAL_WHILE}.
* </p>
* <ul>
* <li>
* Property {@code allowSingleLineStatement} - allow single-line statements without braces.
* Default value is {@code false}.
* </li>
* <li>
* Property {@code allowEmptyLoopBody} - allow loops with empty bodies.
* Default value is {@code false}.
* </li>
* <li>
* Property {@code tokens} - tokens to check.
* Default value is:
* <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_DO">
* LITERAL_DO</a>,
* <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_ELSE">
* LITERAL_ELSE</a>,
* <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FOR">
* LITERAL_FOR</a>,
* <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_IF">
* LITERAL_IF</a>,
* <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_WHILE">
* LITERAL_WHILE</a>.
* </li>
* </ul>
* <p>
* An example of how to configure the check is:
* To configure the check:
* </p>
* <pre>
* &lt;module name="NeedBraces"/&gt;
* </pre>
* <p> An example of how to configure the check for {@code if} and
* {@code else} blocks is:
* <p>
* To configure the check for {@code if} and {@code else} blocks:
* </p>
* <pre>
* &lt;module name="NeedBraces"&gt;
* &lt;property name="tokens" value="LITERAL_IF, LITERAL_ELSE"/&gt;
* &lt;module name=&quot;NeedBraces&quot;&gt;
* &lt;property name=&quot;tokens&quot; value=&quot;LITERAL_IF, LITERAL_ELSE&quot;/&gt;
* &lt;/module&gt;
* </pre>
* Check has the following options:
* <p><b>allowSingleLineStatement</b> which allows single-line statements without braces, e.g.:</p>
* <p>
* {@code
* if (obj.isValid()) return true;
* }
* </p>
* <p>
* {@code
* while (obj.isValid()) return true;
* }
* </p>
* <p>
* {@code
* do this.notify(); while (o != null);
* }
* </p>
* <p>
* {@code
* for (int i = 0; ; ) this.notify();
* }
* </p>
* <p><b>allowEmptyLoopBody</b> which allows loops with empty bodies, e.g.:</p>
* <p>
* {@code
* while (value.incrementValue() < 5);
* }
* To configure the check to allow single-line statements
* ({@code if, while, do-while, for}) without braces:
* </p>
* <pre>
* &lt;module name=&quot;NeedBraces&quot;&gt;
* &lt;property name=&quot;allowSingleLineStatement&quot; value=&quot;true&quot;/&gt;
* &lt;/module&gt;
* </pre>
* <p>
* {@code
* for(int i = 0; i < 10; value.incrementValue());
* }
* Next statements won't be violated by Check:
* </p>
* <p>Default value for allowEmptyLoopBody option is <b>false</b>.</p>
* <pre>
* if (obj.isValid()) return true; // OK
* while (obj.isValid()) return true; // OK
* do this.notify(); while (o != null); // OK
* for (int i = 0; ; ) this.notify(); // OK
* </pre>
* <p>
* To configure the Check to allow {@code case, default} single-line statements
* without braces:
* To configure the Check to allow {@code case, default} single-line statements without braces:
* </p>
*
* <pre>
* &lt;module name=&quot;NeedBraces&quot;&gt;
* &lt;property name=&quot;tokens&quot; value=&quot;LITERAL_CASE, LITERAL_DEFAULT&quot;/&gt;
* &lt;property name=&quot;allowSingleLineStatement&quot; value=&quot;true&quot;/&gt;
* &lt;property name=&quot;tokens&quot; value=&quot;LITERAL_CASE, LITERAL_DEFAULT&quot;/&gt;
* &lt;property name=&quot;allowSingleLineStatement&quot; value=&quot;true&quot;/&gt;
* &lt;/module&gt;
* </pre>
*
* <p>
* Such statements would be allowed:
* Next statements won't be violated by Check:
* </p>
*
* <pre>
* {@code
* switch (num) {
* case 1: counter++; break; // OK
* case 6: counter += 10; break; // OK
* default: counter = 100; break; // OK
* }
* case 1: counter++; break; // OK
* case 6: counter += 10; break; // OK
* default: counter = 100; break; // OK
* }
* </pre>
* <p>
* To configure the Check to allow {@code while, for} loops with empty bodies:
* To configure the check to allow loops ({@code while, for}) with empty bodies:
* </p>
*
* <pre>
* &lt;module name=&quot;NeedBraces&quot;&gt;
* &lt;property name=&quot;allowEmptyLoopBody&quot; value=&quot;true&quot;/&gt;
* &lt;property name=&quot;allowEmptyLoopBody&quot; value=&quot;true&quot;/&gt;
* &lt;/module&gt;
* </pre>
*
* <p>
* Such statements would be allowed:
* Next statements won't be violated by Check:
* </p>
*
* <pre>
* {@code
* while (value.incrementValue() &lt; 5); // OK
* for(int i = 0; i &lt; 10; value.incrementValue()); // OK
* }
* </pre>
*
* @since 3.0
*/
@StatelessCheck
public class NeedBracesCheck extends AbstractCheck {
Expand All @@ -141,25 +132,25 @@ public class NeedBracesCheck extends AbstractCheck {
public static final String MSG_KEY_NEED_BRACES = "needBraces";

/**
* Check's option for skipping single-line statements.
* Allow single-line statements without braces.
*/
private boolean allowSingleLineStatement;

/**
* Check's option for allowing loops with empty body.
* Allow loops with empty bodies.
*/
private boolean allowEmptyLoopBody;

/**
* Setter.
* Setter to allow single-line statements without braces.
* @param allowSingleLineStatement Check's option for skipping single-line statements
*/
public void setAllowSingleLineStatement(boolean allowSingleLineStatement) {
this.allowSingleLineStatement = allowSingleLineStatement;
}

/**
* Sets whether to allow empty loop body.
* Setter to allow loops with empty bodies.
* @param allowEmptyLoopBody Check's option for allowing loops with empty body.
*/
public void setAllowEmptyLoopBody(boolean allowEmptyLoopBody) {
Expand Down
1 change: 1 addition & 0 deletions src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java
View file
Expand Up @@ -88,6 +88,7 @@ public class XdocsJavaDocsTest extends AbstractModuleTestSupport {
"MethodTypeParameterName",
"MissingDeprecated",
"MissingOverride",
"NeedBraces",
"PackageName",
"ParameterName",
"StaticVariableName",
Expand Down
13 changes: 6 additions & 7 deletions src/xdocs/config_blocks.xml
View file
Expand Up @@ -683,8 +683,8 @@ try {
</section>

<section name="NeedBraces">
<p>Since Checkstyle 3.0</p>
<subsection name="Description" id="NeedBraces_Description">
<p>Since Checkstyle 3.0</p>
<p> Checks for braces around code blocks. </p>
</subsection>

Expand All @@ -699,22 +699,21 @@ try {
</tr>
<tr>
<td>allowSingleLineStatement</td>
<td>allows single-line statements without braces</td>
<td>allow single-line statements without braces.</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td>false</td>
<td><code>false</code></td>
<td>6.5</td>
</tr>
<tr>
<td>allowEmptyLoopBody</td>
<td>allows loops with empty bodies</td>
<td>allow loops with empty bodies.</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td>false</td>
<td><code>false</code></td>
<td>6.12.1</td>
</tr>
<tr>
<td>tokens</td>
<td>tokens to check</td>

<td>tokens to check.</td>
<td>subset of tokens
<a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_DO">
LITERAL_DO</a>,
Expand Down

0 comments on commit 7318eb5

Please sign in to comment.