Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Issue #6586: aligned javadoc/xdoc for VariableDeclarationUsageDistance #6662

Merged
merged 1 commit into from
Apr 14, 2019
Merged

Issue #6586: aligned javadoc/xdoc for VariableDeclarationUsageDistance #6662

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
209 changes: 117 additions & 92 deletions .../com/puppycrawl/tools/checkstyle/checks/coding/VariableDeclarationUsageDistanceCheck.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,113 +36,134 @@
* <p>
* Checks the distance between declaration of variable and its first usage.
* </p>
* <p>
* ATTENTION!! (Not supported cases)
* </p>
* <pre>
* Case #1:
* {
* int c;
* int a = 3;
* int b = 2;
* {
* a = a + b;
* c = b;
* }
* }
* </pre>
* <p>
* Distance for variable 'a' = 1;
* Distance for variable 'b' = 1;
* Distance for variable 'c' = 2.
* </p>
* <p>
* As distance by default is 1 the Check doesn't raise warning for variables 'a'
* and 'b' to move them into the block.
* </p>
* <p>
* Case #2:
* </p>
* <pre>
* int sum = 0;
* for (int i = 0; i &lt; 20; i++) {
* a++;
* b--;
* sum++;
* if (sum &gt; 10) {
* res = true;
* }
* }
* </pre>
* <p>
* Distance for variable 'sum' = 3.
* </p>
* <p>
* As the distance is more than the default one, the Check raises warning for variable
* 'sum' to move it into the 'for(...)' block. But there is situation when
* variable 'sum' hasn't to be 0 within each iteration. So, to avoid such
* warnings you can use Suppression Filter, provided by Checkstyle, for the
* whole class.
* </p>
* <ul>
* <li>
* Property {@code allowedDistance} - Specify distance between declaration
* of variable and its first usage. Values should be greater than 0.
* Default value is {@code 3}.
* </li>
* <li>
* Property {@code ignoreVariablePattern} - Define RegExp to ignore distance calculation
* for variables listed in this pattern.
* Default value is {@code ""}.
* </li>
* <li>
* Property {@code validateBetweenScopes} - Allow to calculate the distance between
* declaration of variable and its first usage in the different scopes.
* Default value is {@code false}.
* </li>
* <li>
* Property {@code ignoreFinal} - Allow to ignore variables with a 'final' modifier.
* Default value is {@code true}.
* </li>
* </ul>
* <p>
* Example #1:
* </p>
* <pre>
* {@code int count;
* a = a + b;
* b = a + a;
* count = b; // DECLARATION OF VARIABLE 'count'
* // SHOULD BE HERE (distance = 3)}
* int count;
* a = a + b;
* b = a + a;
* count = b; // DECLARATION OF VARIABLE 'count'
* // SHOULD BE HERE (distance = 3)
* </pre>
* <p>
* Example #2:
* </p>
* <pre>
* {@code int count;
* {
* a = a + b;
* count = b; // DECLARATION OF VARIABLE 'count'
* // SHOULD BE HERE (distance = 2)
* }}
* int count;
* {
* a = a + b;
* count = b; // DECLARATION OF VARIABLE 'count'
* // SHOULD BE HERE (distance = 2)
* }
* </pre>
*
* <p>
* Check can detect a block of initialization methods. If a variable is used in
* such a block and there is no other statements after this variable then distance=1.
* </p>
*
* <p><b>Case #1:</b>
* <p>Case #1:</p>
* <pre>
* int <b>minutes</b> = 5;
* int minutes = 5;
* Calendar cal = Calendar.getInstance();
* cal.setTimeInMillis(timeNow);
* cal.set(Calendar.SECOND, 0);
* cal.set(Calendar.MILLISECOND, 0);
* cal.set(Calendar.HOUR_OF_DAY, hh);
* cal.set(Calendar.MINUTE, <b>minutes</b>);
*
* The distance for the variable <b>minutes</b> is 1 even
* though this variable is used in the fifth method's call.
* cal.set(Calendar.MINUTE, minutes);
* </pre>
*
* <p><b>Case #2:</b>
* <p>
* The distance for the variable minutes is 1 even
* though this variable is used in the fifth method's call.
* </p>
* <p>Case #2:</p>
* <pre>
* int <b>minutes</b> = 5;
* int minutes = 5;
* Calendar cal = Calendar.getInstance();
* cal.setTimeInMillis(timeNow);
* cal.set(Calendar.SECOND, 0);
* cal.set(Calendar.MILLISECOND, 0);
* <i>System.out.println(cal);</i>
* cal.set(Calendar.HOUR_OF_DAY, hh);
* cal.set(Calendar.MINUTE, <b>minutes</b>);
*
* The distance for the variable <b>minutes</b> is 6 because there is one more expression
* (except the initialization block) between the declaration of this variable and its usage.
* </pre>
*
* <p>There are several additional options to configure the check:
* <pre>
* 1. allowedDistance - allows to set a distance
* between declaration of variable and its first usage.
* 2. ignoreVariablePattern - allows to set a RegEx pattern for
* ignoring the distance calculation for variables listed in this pattern.
* 3. validateBetweenScopes - allows to calculate the distance between
* declaration of variable and its first usage in the different scopes.
* 4. ignoreFinal - allows to ignore variables with a 'final' modifier.
* </pre>
* ATTENTION!! (Not supported cases)
* <pre>
* Case #1:
* {@code {
* int c;
* int a = 3;
* int b = 2;
* {
* a = a + b;
* c = b;
* }
* }}
*
* Distance for variable 'a' = 1;
* Distance for variable 'b' = 1;
* Distance for variable 'c' = 2.
* </pre>
* As distance by default is 1 the Check doesn't raise warning for variables 'a'
* and 'b' to move them into the block.
* <pre>
* Case #2:
* {@code int sum = 0;
* for (int i = 0; i &lt; 20; i++) {
* a++;
* b--;
* sum++;
* if (sum &gt; 10) {
* res = true;
* }
* }}
* Distance for variable 'sum' = 3.
* cal.set(Calendar.MINUTE, minutes);
* </pre>
* <p>
* As the distance is more than the default one, the Check raises warning for variable
* 'sum' to move it into the 'for(...)' block. But there is situation when
* variable 'sum' hasn't to be 0 within each iteration. So, to avoid such
* warnings you can use Suppression Filter, provided by Checkstyle, for the
* whole class.
* The distance for the variable minutes is 6 because there is one more expression
* (except the initialization block) between the declaration of this variable and its usage.
* </p>
*
* <p>
* An example how to configure this Check:
* </p>
* <pre>
* &lt;module name="VariableDeclarationUsageDistance"/&gt;
* &lt;module name=&quot;VariableDeclarationUsageDistance&quot;/&gt;
* </pre>
* <p>
* An example of how to configure this Check:
Expand All @@ -152,14 +173,15 @@
* - to check the final variables;
* </p>
* <pre>
* &lt;module name="VariableDeclarationUsageDistance"&gt;
* &lt;property name="allowedDistance" value="4"/&gt;
* &lt;property name="ignoreVariablePattern" value="^temp.*"/&gt;
* &lt;property name="validateBetweenScopes" value="true"/&gt;
* &lt;property name="ignoreFinal" value="false"/&gt;
* &lt;module name=&quot;VariableDeclarationUsageDistance&quot;&gt;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pbludov I believe you are doing these type of changes by hand, correct? I see the xdoc still uses " instead of &quot;.

Maybe consider enforcing the program to replace these for you so it won't be a manual process and future contributors will be forced to make this change too.
Doing something like this on xdoc will probably require something like XdocPagesTest.testAllXmlExamples (or a modification to it).

* &lt;property name=&quot;allowedDistance&quot; value=&quot;4&quot;/&gt;
* &lt;property name=&quot;ignoreVariablePattern&quot; value=&quot;^temp.*&quot;/&gt;
* &lt;property name=&quot;validateBetweenScopes&quot; value=&quot;true&quot;/&gt;
* &lt;property name=&quot;ignoreFinal&quot; value=&quot;false&quot;/&gt;
* &lt;/module&gt;
* </pre>
*
* @since 5.8
*/
@StatelessCheck
public class VariableDeclarationUsageDistanceCheck extends AbstractCheck {
Expand All @@ -180,27 +202,30 @@ public class VariableDeclarationUsageDistanceCheck extends AbstractCheck {
*/
private static final int DEFAULT_DISTANCE = 3;

/** Allowed distance between declaration of variable and its first usage. */
/**
* Specify distance between declaration of variable and its first usage.
* Values should be greater than 0.
*/
private int allowedDistance = DEFAULT_DISTANCE;

/**
* RegExp pattern to ignore distance calculation for variables listed in
* Define RegExp to ignore distance calculation for variables listed in
* this pattern.
*/
private Pattern ignoreVariablePattern = Pattern.compile("");

/**
* Allows to calculate distance between declaration of variable and its
* first usage in different scopes.
* Allow to calculate the distance between declaration of variable and its
* first usage in the different scopes.
*/
private boolean validateBetweenScopes;

/** Allows to ignore variables with 'final' modifier. */
/** Allow to ignore variables with a 'final' modifier. */
private boolean ignoreFinal = true;

/**
* Sets an allowed distance between declaration of variable and its first
* usage.
* Setter to specify distance between declaration of variable and its first usage.
* Values should be greater than 0.
* @param allowedDistance
* Allowed distance between declaration of variable and its first
* usage.
Expand All @@ -210,16 +235,16 @@ public void setAllowedDistance(int allowedDistance) {
}

/**
* Sets RegExp pattern to ignore distance calculation for variables listed in this pattern.
* Setter to define RegExp to ignore distance calculation for variables listed in this pattern.
* @param pattern a pattern.
*/
public void setIgnoreVariablePattern(Pattern pattern) {
ignoreVariablePattern = pattern;
}

/**
* Sets option which allows to calculate distance between declaration of
* variable and its first usage in different scopes.
* Setter to allow to calculate the distance between declaration of
* variable and its first usage in the different scopes.
* @param validateBetweenScopes
* Defines if allow to calculate distance between declaration of
* variable and its first usage in different scopes or not.
Expand All @@ -229,7 +254,7 @@ public void setValidateBetweenScopes(boolean validateBetweenScopes) {
}

/**
* Sets ignore option for variables with 'final' modifier.
* Setter to allow to ignore variables with a 'final' modifier.
* @param ignoreFinal
* Defines if ignore variables with 'final' modifier or not.
*/
Expand Down
1 change: 1 addition & 0 deletions src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,7 @@ public class XdocsJavaDocsTest extends AbstractModuleTestSupport {
"SuppressWarningsHolder",
"TypeName",
"UnnecessaryParentheses",
"VariableDeclarationUsageDistance",
};

private static Checker checker;
Expand Down
16 changes: 9 additions & 7 deletions src/xdocs/config_coding.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4800,8 +4800,8 @@ if (&quot;something&quot;.equals(x))
</section>

<section name="VariableDeclarationUsageDistance">
<p>Since Checkstyle 5.8</p>
<subsection name="Description" id="VariableDeclarationUsageDistance_Description">
<p>Since Checkstyle 5.8</p>
<p>
Checks the distance between declaration of variable and its first usage.
</p>
Expand All @@ -4819,24 +4819,26 @@ if (&quot;something&quot;.equals(x))

<tr>
<td>allowedDistance</td>
<td>A distance between declaration of variable and its first usage.
<td>Specify distance between declaration of variable and its first usage.
Values should be greater than 0.</td>
<td><a href="property_types.html#integer">Integer</a></td>
<td>3</td>
<td><code>3</code></td>
<td>5.8</td>
</tr>

<tr>
<td>ignoreVariablePattern</td>
<td>pattern for ignoring the distance calculation</td>
<td>
Define RegExp to ignore distance calculation for variables listed in this pattern.
</td>
<td><a href="property_types.html#regexp">Regular Expression</a></td>
<td><code>""</code></td>
<td>5.8</td>
</tr>

<tr>
<td>validateBetweenScopes</td>
<td>Allows to calculate the distance between declaration of variable and its
<td>Allow to calculate the distance between declaration of variable and its
first usage in the different scopes.</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td><code>false</code></td>
Expand All @@ -4845,7 +4847,7 @@ if (&quot;something&quot;.equals(x))

<tr>
<td>ignoreFinal</td>
<td>Allows to ignore variables with a 'final' modifier.</td>
<td>Allow to ignore variables with a 'final' modifier.</td>
<td><a href="property_types.html#boolean">Boolean</a></td>
<td><code>true</code></td>
<td>5.8</td>
Expand All @@ -4872,7 +4874,7 @@ int count;
{
a = a + b;
count = b; // DECLARATION OF VARIABLE 'count'
// SHOULD BE HERE (distance = 2)
// SHOULD BE HERE (distance = 2)
}
</source>
<p>
Expand Down