Skip to content

Commit

Permalink
Issue checkstyle#13007: Update doc for UnusedImports
Browse files Browse the repository at this point in the history
  • Loading branch information
@TanayMorakhia
TanayMorakhia committed May 16, 2023
1 parent 1c09350 commit cf86d59
Show file tree
Hide file tree
Showing 3 changed files with 121 additions and 65 deletions.
79 changes: 58 additions & 21 deletions src/main/java/com/puppycrawl/tools/checkstyle/checks/imports/UnusedImportsCheck.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,7 @@

/**
* <p>
* Checks for unused import statements. Checkstyle uses a simple but very
* reliable algorithm to report on unused import statements. An import statement
* Checks for unused import statements. An import statement
* is considered unused if:
* </p>
* <ul>
Expand All @@ -52,10 +51,6 @@
* checks for imports that handle wild-card imports.
* </li>
* <li>
* It is a duplicate of another import. This is when a class is imported more
* than once.
* </li>
* <li>
* The class imported is from the {@code java.lang} package. For example
* importing {@code java.lang.String}.
* </li>
Expand All @@ -79,23 +74,11 @@
* An imported type has the same name as a declaration, such as a member variable.
* </li>
* <li>
* There are two or more imports with the same name.
* There are two or more static imports with the same method name
* (javac can distinguish imports with same name but different parameters, but checkstyle can not
* due to <a href="https://checkstyle.org/writingchecks.html#Limitations">limitation.</a>)
* </li>
* </ul>
* <p>
* For example, in the following case all imports will not be flagged as unused:
* </p>
* <pre>
* import java.awt.Component;
* import static AstTreeStringPrinter.printFileAst;
* import static DetailNodeTreeStringPrinter.printFileAst;
* class FooBar {
* private Object Component; // a bad practice in my opinion
* void method() {
* printFileAst(file); // two imports with the same name
* }
* }
* </pre>
* <ul>
* <li>
* Property {@code processJavadoc} - Control whether to process Javadoc comments.
Expand All @@ -109,6 +92,60 @@
* <pre>
* &lt;module name="UnusedImports"/&gt;
* </pre>
* <p>Example:</p>
* <pre>
* import java.awt.Component; // limitation as it match field name in code
*
* // no ability to recognize what import is not used
* import static AstTreeStringPrinter.printFileAst;
* import static DetailNodeTreeStringPrinter.printFileAst;
*
* import java.lang.String; // violation
*
* import java.util.Stack; // OK
* import java.util.Map; // violation
*
* import java.util.List; // OK
*
* &#47;&#42;&#42;
* &#42; &#64;link List
* &#42;&#47;
* class MyClass{
* Stack stack = new Stack();
* private Object Component;
* }
* </pre>
* <p>
* To configure the check so that it ignores the imports referenced in Javadoc comments:
* </p>
* <pre>
* &lt;module name=&quot;UnusedImports&quot;&gt;
* &lt;property name=&quot;processJavadoc&quot; value=&quot;false&quot;/&gt;
* &lt;/module&gt;
* </pre>
* <p>Example:</p>
* <pre>
* import java.awt.Component; // limitation as it match field name in code
*
* // no ability to recognize what import is not used
* import static AstTreeStringPrinter.printFileAst;
* import static DetailNodeTreeStringPrinter.printFileAst;
*
* import java.lang.String; // violation
*
* import java.util.Stack; // OK
* import java.util.Map; // violation
*
* import java.util.List; // violation
*
* &#47;&#42;&#42;
* &#42; &#64;link List
* &#42;&#47;
* class MyClass{
* Stack stack = new Stack();
* private Object Component;
* }
* </pre>
* <p>
* Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
* </p>
Expand Down
27 changes: 5 additions & 22 deletions ...main/resources/com/puppycrawl/tools/checkstyle/meta/checks/imports/UnusedImportsCheck.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,7 @@
name="UnusedImports"
parent="com.puppycrawl.tools.checkstyle.TreeWalker">
<description>&lt;p&gt;
Checks for unused import statements. Checkstyle uses a simple but very
reliable algorithm to report on unused import statements. An import statement
Checks for unused import statements. An import statement
is considered unused if:
&lt;/p&gt;
&lt;ul&gt;
Expand All @@ -16,10 +15,6 @@
checks for imports that handle wild-card imports.
&lt;/li&gt;
&lt;li&gt;
It is a duplicate of another import. This is when a class is imported more
than once.
&lt;/li&gt;
&lt;li&gt;
The class imported is from the {@code java.lang} package. For example
importing {@code java.lang.String}.
&lt;/li&gt;
Expand All @@ -43,23 +38,11 @@
An imported type has the same name as a declaration, such as a member variable.
&lt;/li&gt;
&lt;li&gt;
There are two or more imports with the same name.
There are two or more static imports with the same method name
(javac can distinguish imports with same name but different parameters, but checkstyle can not
due to &lt;a href="https://checkstyle.org/writingchecks.html#Limitations"&gt;limitation.&lt;/a&gt;)
&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;
For example, in the following case all imports will not be flagged as unused:
&lt;/p&gt;
&lt;pre&gt;
import java.awt.Component;
import static AstTreeStringPrinter.printFileAst;
import static DetailNodeTreeStringPrinter.printFileAst;
class FooBar {
private Object Component; // a bad practice in my opinion
void method() {
printFileAst(file); // two imports with the same name
}
}
&lt;/pre&gt;</description>
&lt;/ul&gt;</description>
<properties>
<property default-value="true" name="processJavadoc" type="boolean">
<description>Control whether to process Javadoc comments.</description>
Expand Down
80 changes: 58 additions & 22 deletions src/xdocs/config_imports.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2454,8 +2454,7 @@ public class MyClass{ };
<p>Since Checkstyle 3.0</p>
<subsection name="Description" id="UnusedImports_Description">
<p>
Checks for unused import statements. Checkstyle uses a simple but
very reliable algorithm to report on unused import statements. An
Checks for unused import statements. An
import statement is considered unused if:
</p>

Expand All @@ -2467,11 +2466,6 @@ public class MyClass{ };
for imports that handle wild-card imports.
</li>

<li>
It is a duplicate of another import. This is when a class is
imported more than once.
</li>

<li>
The class imported is from the <code>java.lang</code>
package. For example importing <code>java.lang.String</code>.
Expand Down Expand Up @@ -2499,23 +2493,12 @@ public class MyClass{ };
An imported type has the same name as a declaration, such as a member variable.
</li>
<li>
There are two or more imports with the same name.
There are two or more static imports with the same method name
(javac can distinguish imports with same name but different parameters, but checkstyle
can not due to <a href="https://checkstyle.org/writingchecks.html#Limitations">
limitation.</a>)
</li>
</ul>
<p>
For example, in the following case all imports will not be flagged as unused:
</p>
<source>
import java.awt.Component;
import static AstTreeStringPrinter.printFileAst;
import static DetailNodeTreeStringPrinter.printFileAst;
class FooBar {
private Object Component; // a bad practice in my opinion
void method() {
printFileAst(file); // two imports with the same name
}
}
</source>
</subsection>

<subsection name="Properties" id="UnusedImports_Properties">
Expand Down Expand Up @@ -2546,6 +2529,59 @@ class FooBar {
<source>
&lt;module name=&quot;UnusedImports&quot;/&gt;
</source>
<p>Example:</p>
<source>
import java.awt.Component; // limitation as it match field name in code

// no ability to recognize what import is not used
import static AstTreeStringPrinter.printFileAst;
import static DetailNodeTreeStringPrinter.printFileAst;

import java.lang.String; // violation

import java.util.Stack; // OK
import java.util.Map; // violation

import java.util.List; // OK

&#47;&#42;&#42;
&#42; &#64;link List
&#42;&#47;
class MyClass{
Stack stack = new Stack();
private Object Component;
}
</source>
<p>
To configure the check so that it ignores the imports referenced in Javadoc comments:
</p>
<source>
&lt;module name=&quot;UnusedImports&quot;&gt;
&lt;property name=&quot;processJavadoc&quot; value=&quot;false&quot;/&gt;
&lt;/module&gt;
</source>
<p>Example:</p>
<source>
import java.awt.Component; // limitation as it match field name in code

// no ability to recognize what import is not used
import static AstTreeStringPrinter.printFileAst;
import static DetailNodeTreeStringPrinter.printFileAst;
import java.lang.String; // violation

import java.util.Stack; // OK
import java.util.Map; // violation

import java.util.List; // violation

&#47;&#42;&#42;
&#42; &#64;link List
&#42;&#47;
class MyClass{
Stack stack = new Stack();
private Object Component;
}
</source>
</subsection>

<subsection name="Example of Usage" id="UnusedImports_Example_of_Usage">
Expand Down

0 comments on commit cf86d59

Please sign in to comment.