<?xml version="1.0" encoding="ISO-8859-1"?>

<document xmlns="http://maven.apache.org/XDOC/2.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">

  <properties>
    <title>Block Checks</title>
    <author>Checkstyle Development Team</author>
  </properties>

  <body>

    <section name="EmptyBlock">
      <subsection name="Description">
        <p> Checks for empty blocks. </p>
      </subsection>

      <subsection name="Properties">
        <table>
          <tr>
            <th>name</th>
            <th>description</th>
            <th>type</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>option</td>
            <td>policy on block contents</td>
            <td><a href="property_types.html#block">block policy</a></td>
            <td><code>stmt</code></td>
          </tr>
          <tr>
            <td>tokens</td>
            <td>blocks to check</td>

            <td>
              subset of tokens <a
              href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_CATCH">LITERAL_CATCH</a>,
              <a
               href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_DO">LITERAL_DO</a>,
               <a
                href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_ELSE">LITERAL_ELSE</a>,
                <a
                 href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FINALLY">LITERAL_FINALLY</a>,
                 <a
                  href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_IF">LITERAL_IF</a>,
                  <a
                   href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FOR">LITERAL_FOR</a>,
                   <a
                    href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_TRY">LITERAL_TRY</a>,
                    <a
                     href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_WHILE">LITERAL_WHILE</a>,
                     <a
                     href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INSTANCE_INIT">INSTANCE_INIT</a>
                     <a
                     href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#STATIC_INIT">STATIC_INIT</a>
            </td>

            <td>all tokens</td>
          </tr>
        </table>
      </subsection>

      <subsection name="Examples">
        <p> To configure the check: </p>
        <source>
&lt;module name=&quot;EmptyBlock&quot;/&gt;
        </source>

        <p>
          To configure the check for the <code>text</code>
          policy and only <code> catch</code> blocks:
        </p>
        <source>
&lt;module name=&quot;EmptyBlock&quot;&gt;
    &lt;property name=&quot;option&quot; value=&quot;text&quot;/&gt;
    &lt;property name=&quot;tokens&quot; value=&quot;LITERAL_CATCH&quot;/&gt;
&lt;/module&gt;
        </source>
      </subsection>

      <subsection name="Package">
        <p> com.puppycrawl.tools.checkstyle.checks.blocks </p>
      </subsection>

      <subsection name="Parent Module">
        <p> <a href="config.html#TreeWalker">TreeWalker</a> </p>
      </subsection>
    </section>

    <section name="LeftCurly">
      <subsection name="Description">
        <p>
          Checks for the placement of left curly braces
          (<code>'{'</code>) for code blocks.  The policy to verify is
          specified using property <code>option</code>.  Policies
          <code>eol</code> and <code> nlow</code> take into account
          property <code>maxLineLength</code>.
        </p>
      </subsection>

      <subsection name="Properties">
        <table>
          <tr>
            <th>name</th>
            <th>description</th>
            <th>type</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>option</td>
            <td>policy on placement of a left curly brace (<code>'{'</code>)</td>
            <td><a href="property_types.html#lcurly">left curly brace policy</a></td>
            <td><code>eol</code></td>
          </tr>
          <tr>
            <td>maxLineLength</td>
            <td>maximum number of characters in a line</td>
            <td><a href="property_types.html#integer">integer</a></td>
            <td><code>80</code></td>
          </tr>
          <tr>
            <td>tokens</td>
            <td>blocks to check</td>

            <td>subset of tokens <a
            href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">CLASS_DEF</a>,
            <a
             href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">CTOR_DEF</a>,
             <a
              href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF">INTERFACE_DEF</a>,
              <a
               href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_CATCH">LITERAL_CATCH</a>,
               <a
                href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_DO">LITERAL_DO</a>,
                <a
                 href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_ELSE">LITERAL_ELSE</a>,
                 <a
                  href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FINALLY">LITERAL_FINALLY</a>,
                  <a
                   href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FOR">LITERAL_FOR</a>,
                   <a
                    href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_IF">LITERAL_IF</a>,
                    <a
                     href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_SWITCH">LITERAL_SWITCH</a>,
                     <a
                      href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_SYNCHRONIZED">LITERAL_SYNCHRONIZED</a>,
                      <a
                       href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_TRY">LITERAL_TRY</a>,
                       <a
                        href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_WHILE">LITERAL_WHILE</a>,
                        <a
                        href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">METHOD_DEF</a>
            </td>

            <td>all tokens</td>
          </tr>
        </table>
      </subsection>

      <subsection name="Examples">
        <p> To configure the check: </p>
        <source>
&lt;module name=&quot;LeftCurly&quot;/&gt;
        </source>
        <p>
          To configure the check to apply the <code>nl</code> policy to
          type blocks:
        </p>
        <source>
&lt;module name=&quot;LeftCurly&quot;&gt;
    &lt;property name=&quot;option&quot; value=&quot;nl&quot;/&gt;
    &lt;property name=&quot;tokens&quot; value=&quot;CLASS_DEF,INTERFACE_DEF&quot;/&gt;
&lt;/module&gt;
        </source>
      </subsection>

      <subsection name="Package">
        <p> com.puppycrawl.tools.checkstyle.checks.blocks </p>
      </subsection>

      <subsection name="Parent Module">
        <p> <a href="config.html#TreeWalker">TreeWalker</a> </p>
      </subsection>
    </section>

    <section name="NeedBraces">
      <subsection name="Description">
        <p> Checks for braces around code blocks. </p>
      </subsection>

      <subsection name="Properties">
        <table>
          <tr>
            <th>name</th>
            <th>description</th>
            <th>type</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>tokens</td>
            <td>blocks to check</td>

            <td>subset of tokens <a
            href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_DO">LITERAL_DO</a>,
            <a
             href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_ELSE">LITERAL_ELSE</a>,
             <a
              href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_IF">LITERAL_IF</a>,
              <a
               href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FOR">LITERAL_FOR</a>,
               <a
            href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_WHILE">LITERAL_WHILE</a></td>

            <td>all tokens</td>
          </tr>
        </table>
      </subsection>

      <subsection name="Examples">
        <p> To configure the check: </p>
        <source>
&lt;module name=&quot;NeedBraces&quot;/&gt;
        </source>

        <p>
          To configure the check for <code>if</code> and
          <code> else</code> blocks:
        </p>
        <source>
&lt;module name=&quot;NeedBraces&quot;&gt;
    &lt;property name=&quot;tokens&quot; value=&quot;LITERAL_IF, LITERAL_ELSE&quot;/&gt;
&lt;/module&gt;
        </source>
      </subsection>

      <subsection name="Package">
        <p> com.puppycrawl.tools.checkstyle.checks.blocks </p>
      </subsection>

      <subsection name="Parent Module">
        <p> <a href="config.html#TreeWalker">TreeWalker</a> </p>
      </subsection>
    </section>

    <section name="RightCurly">
      <subsection name="Description">
        <p>
          Checks the placement of right curly braces (<code>'}'</code>)
          for <code> else</code>, <code>try</code>, and
          <code>catch</code> tokens. The policy to verify is specified
          using property <code> option</code>.
        </p>
      </subsection>

      <subsection name="Properties">
        <table>
          <tr>
            <th>name</th>
            <th>description</th>
            <th>type</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>option</td>
            <td>policy on placement of a right curly brace (<code>'}'</code>)</td>
            <td><a href="property_types.html#rcurly">right curly brace policy</a></td>
            <td><code>same</code></td>
          </tr>
          <tr>
            <td>tokens</td>
            <td>blocks to check</td>

            <td>subset of tokens <a
             href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_TRY">LITERAL_TRY</a>,
            <a
             href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_CATCH">LITERAL_CATCH</a>,
            <a
             href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FINALLY">LITERAL_FINALLY</a>,
            <a
             href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_IF">LITERAL_IF</a>,
            <a
             href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_ELSE">LITERAL_ELSE</a></td>

            <td><a
             href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_TRY">LITERAL_TRY</a>,
            <a
             href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_CATCH">LITERAL_CATCH</a>,
            <a
             href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_FINALLY">LITERAL_FINALLY</a>,
            <a
             href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_IF">LITERAL_IF</a>,
            <a
             href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_ELSE">LITERAL_ELSE</a></td>

          </tr>
          <tr>
            <td>shouldStartLine</td>
            <td>should we check if <code>'}'</code>
            starts line.</td>
            <td><a href="property_types.html#boolean">boolean</a></td>
            <td><code>true</code></td>
          </tr>
        </table>
      </subsection>

      <subsection name="Examples">
        <p> To configure the check: </p>
        <source>
&lt;module name=&quot;RightCurly&quot;/&gt;
        </source>

        <p>
          To configure the check with policy <code>alone</code> for <code> else</code>
          tokens:
        </p>
        <source>
&lt;module name=&quot;RightCurly&quot;&gt;
    &lt;property name=&quot;option&quot; value=&quot;alone&quot;/&gt;
    &lt;property name=&quot;tokens&quot; value=&quot;LITERAL_ELSE&quot;/&gt;
&lt;/module&gt;
        </source>
      </subsection>

      <subsection name="Package">
        <p> com.puppycrawl.tools.checkstyle.checks.blocks </p>
      </subsection>

      <subsection name="Parent Module">
        <p> <a href="config.html#TreeWalker">TreeWalker</a> </p>
      </subsection>
    </section>

    <section name="AvoidNestedBlocks">
      <subsection name="Description">
        <p>
          Finds nested blocks, i.e. blocks that are used freely in the code.
        </p>

        <p>
          Rationale: Nested blocks are often leftovers from the
          debugging process, they confuse the reader.
        </p>

        <p>
          For example this Check finds the obsolete braces in
        </p>
        <source>
public void guessTheOutput()
{
    int whichIsWich = 0;
    {
        int whichIsWhich = 2;
    }
    System.out.println("value = " + whichIsWhich);
}
        </source>

        <p> and debugging / refactoring leftovers such as </p>
        <source>
// if (conditionThatIsNotUsedAnyLonger)
{
    System.out.println("unconditional");
}
        </source>

        <p>
          A case in a switch statement does not implicitly form a block.
          Thus to be able to introduce local variables that have case
          scope it is necessary to open a nested block. This is
          supported, set the allowInSwitchCase property to true and
          include all statements of the case in the block.
        </p>
        <source>
switch (a)
{
    case 0:
        // Never OK, break outside block
        {
            x = 1;
        }
        break;
    case 1:
        // Never OK, statement outside block
        System.out.println("Hello");
        {
            x = 2;
            break;
        }
    case 1:
        // OK if allowInSwitchCase is true
        {
            System.out.println("Hello");
            x = 2;
            break;
        }
}
        </source>
      </subsection>

      <subsection name="Properties">
        <table>
          <tr>
            <th>name</th>
            <th>description</th>
            <th>type</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>allowInSwitchCase</td>
            <td>Allow nested blocks in case statements</td>
            <td><a href="property_types.html#boolean">boolean</a></td>
            <td><code>false</code></td>
          </tr>
        </table>
      </subsection>

      <subsection name="Examples">
        <p> To configure the check: </p>
        <source>
&lt;module name=&quot;AvoidNestedBlocks&quot;/&gt;
        </source>
      </subsection>

      <subsection name="Package">
        <p> com.puppycrawl.tools.checkstyle.checks.blocks </p>
      </subsection>

      <subsection name="Parent Module">
        <p> <a href="config.html#TreeWalker">TreeWalker</a> </p>
      </subsection>
    </section>
  </body>
</document>
