Skip to content

Commit

Permalink
Issue #6726: aligned javadoc/xdoc for SuppressionFilter
Browse files Browse the repository at this point in the history
  • Loading branch information
@pbludov @rnveach
pbludov authored and rnveach committed Jun 17, 2019
1 parent 1f48ff9 commit 61e2ff5
Show file tree
Hide file tree
Showing 3 changed files with 277 additions and 97 deletions.
194 changes: 188 additions & 6 deletions src/main/java/com/puppycrawl/tools/checkstyle/filters/SuppressionFilter.java
View file
Expand Up @@ -32,29 +32,211 @@

/**
* <p>
* This filter accepts AuditEvents according to file, check, line, and
* column, as specified in a suppression file.
* Filter {@code SuppressionFilter} rejects audit events for Check errors according to a
* <a href="https://checkstyle.org/dtds/suppressions_1_2.dtd">suppressions XML document</a>
* in a file. If there is no configured suppressions file or the optional is set to true and
* suppressions file was not found the Filter accepts all audit events.
* </p>
* <p>
* A <a href="https://checkstyle.org/dtds/suppressions_1_2.dtd">suppressions XML document</a>
* contains a set of {@code suppress} elements, where each {@code suppress}
* element can have the following attributes:
* </p>
* <ul>
* <li>
* {@code files} - a <a href="https://checkstyle.org/property_types.html#regexp">
* Regular Expression</a> matched against the file name associated with an audit event.
* It is optional.
* </li>
* <li>
* {@code checks} - a <a href="https://checkstyle.org/property_types.html#regexp">
* Regular Expression</a> matched against the name of the check associated with an audit event.
* Optional as long as {@code id} or {@code message} is specified.
* </li>
* <li>
* {@code message} - a <a href="https://checkstyle.org/property_types.html#regexp">
* Regular Expression</a> matched against the message of the check associated with an audit event.
* Optional as long as {@code checks} or {@code id} is specified.
* </li>
* <li>
* {@code id} - a <a href="https://checkstyle.org/property_types.html#string">string</a>
* matched against the <a href="config.html#Id">check id</a> associated with an audit event.
* Optional as long as {@code checks} or {@code message} is specified.
* </li>
* <li>
* {@code lines} - a comma-separated list of values, where each value is an
* <a href="https://checkstyle.org/property_types.html#integer">integer</a>
* or a range of integers denoted by integer-integer.
* It is optional.
* </li>
* <li>
* {@code columns} - a comma-separated list of values, where each value is an
* <a href="https://checkstyle.org/property_types.html#integer">integer</a>
* or a range of integers denoted by integer-integer.
* It is optional.
* </li>
* </ul>
* <p>
* Each audit event is checked against each {@code suppress} element.
* It is suppressed if all specified attributes match against the audit event.
* </p>
* <p>
* ATTENTION: filtering by message is dependant on runtime locale.
* If project is running in different languages it is better to avoid filtering by message.
* </p>
* <p>
* You can download template of empty suppression filter
* <a href="https://checkstyle.org/files/suppressions_none.xml">here</a>.
* </p>
* <p>
* Location of the file defined in {@code file} property is checked in the following order:
* </p>
* <ol>
* <li>
* as a filesystem location
* </li>
* <li>
* if no file found, and the location starts with either {@code http://} or {@code https://},
* then it is interpreted as a URL
* </li>
* <li>
* if no file found, then passed to the {@code ClassLoader.getResource()} method.
* </li>
* </ol>
* <ul>
* <li>
* Property {@code file} - Specify the location of the <em>suppressions XML document</em> file.
* Default value is {@code null}.
* </li>
* <li>
* Property {@code optional} - Control what to do when the file is not existing.
* If {@code optional} is set to {@code false} the file must exist, or else it
* ends with error. On the other hand if optional is {@code true} and file is
* not found, the filter accept all audit events.
* Default value is {@code false}.
* </li>
* </ul>
* <p>
* For example, the following configuration fragment directs the Checker to use
* a {@code SuppressionFilter} with suppressions file {@code config/suppressions.xml}:
* </p>
* <pre>
* &lt;module name=&quot;SuppressionFilter&quot;&gt;
* &lt;property name=&quot;file&quot; value=&quot;config/suppressions.xml&quot;/&gt;
* &lt;property name=&quot;optional&quot; value=&quot;false&quot;/&gt;
* &lt;/module&gt;
* </pre>
* <p>
* The following suppressions XML document directs a {@code SuppressionFilter} to
* reject {@code JavadocStyleCheck} errors for lines 82 and 108 to 122 of file
* {@code AbstractComplexityCheck.java}, and {@code MagicNumberCheck} errors for
* line 221 of file {@code JavadocStyleCheck.java}, and
* {@code 'Missing a Javadoc comment'} errors for all lines and files:
* </p>
* <pre>
* &lt;?xml version=&quot;1.0&quot;?&gt;
*
* &lt;!DOCTYPE suppressions PUBLIC
* &quot;-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN&quot;
* &quot;https://checkstyle.org/dtds/suppressions_1_2.dtd&quot;&gt;
*
* &lt;suppressions&gt;
* &lt;suppress checks=&quot;JavadocStyleCheck&quot;
* files=&quot;AbstractComplexityCheck.java&quot;
* lines=&quot;82,108-122&quot;/&gt;
* &lt;suppress checks=&quot;MagicNumberCheck&quot;
* files=&quot;JavadocStyleCheck.java&quot;
* lines=&quot;221&quot;/&gt;
* &lt;suppress message=&quot;Missing a Javadoc comment&quot;/&gt;
* &lt;/suppressions&gt;
* </pre>
* <p>
* Suppress check by <a href="https://checkstyle.org/config.html#Id">module id</a>
* when config have two instances on the same check:
* </p>
* <pre>
* &lt;suppress id=&quot;stringEqual&quot; files=&quot;SomeTestCode.java&quot;/&gt;
* </pre>
* <p>
* Suppress all checks for hidden files and folders:
* </p>
* <pre>
* &lt;suppress files=&quot;[/\\]\..+&quot; checks=&quot;.*&quot;/&gt;
* </pre>
* <p>
* Suppress all checks for Maven-generated code:
* </p>
* <pre>
* &lt;suppress files=&quot;[/\\]target[/\\]&quot; checks=&quot;.*&quot;/&gt;
* </pre>
* <p>
* Suppress all checks for archives, classes and other binary files:
* </p>
* <pre>
* &lt;suppress files=&quot;.+\.(?:jar|zip|war|class|tar|bin)$&quot; checks=&quot;.*&quot;/&gt;
* </pre>
* <p>
* Suppress all checks for image files:
* </p>
* <pre>
* &lt;suppress files=".+\.(?:png|gif|jpg|jpeg)$" checks=".*"/&gt;
* </pre>
* <p>
* Suppress all checks for non-java files:
* </p>
* <pre>
* &lt;suppress files=&quot;.+\.(?:txt|xml|csv|sh|thrift|html|sql|eot|ttf|woff|css|png)$&quot;
* checks=&quot;.*&quot;/&gt;
* </pre>
* <p>
* Suppress all checks in generated sources:
* </p>
* <pre>
* &lt;suppress checks=&quot;.*&quot; files=&quot;com[\\/]mycompany[\\/]app[\\/]gen[\\/]&quot;/&gt;
* </pre>
* <p>
* Suppress FileLength check on integration tests in certain folder:
* </p>
* <pre>
* &lt;suppress checks=&quot;FileLength&quot;
* files=&quot;com[\\/]mycompany[\\/]app[\\/].*IT.java&quot;/&gt;
* </pre>
* <p>
* Suppress naming errors on variable named 'log' in all files:
* </p>
* <pre>
* &lt;suppress message=&quot;Name 'log' must match pattern&quot;/&gt;
* </pre>
*
* @since 3.2
*/
public class SuppressionFilter extends AutomaticBean implements Filter, ExternalResourceHolder {

/** Filename of suppression file. */
/** Specify the location of the <em>suppressions XML document</em> file. */
private String file;
/** Tells whether config file existence is optional. */
/**
* Control what to do when the file is not existing. If {@code optional} is
* set to {@code false} the file must exist, or else it ends with error.
* On the other hand if optional is {@code true} and file is not found,
* the filter accept all audit events.
*/
private boolean optional;
/** Set of individual suppresses. */
private FilterSet filters = new FilterSet();

/**
* Sets name of the suppression file.
* Setter to specify the location of the <em>suppressions XML document</em> file.
* @param fileName name of the suppressions file.
*/
public void setFile(String fileName) {
file = fileName;
}

/**
* Sets whether config file existence is optional.
* Setter to control what to do when the file is not existing.
* If {@code optional} is set to {@code false} the file must exist, or else
* it ends with error. On the other hand if optional is {@code true}
* and file is not found, the filter accept all audit events.
* @param optional tells if config file existence is optional.
*/
public void setOptional(boolean optional) {
Expand Down
1 change: 0 additions & 1 deletion src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java
View file
Expand Up @@ -72,7 +72,6 @@ public class XdocsJavaDocsTest extends AbstractModuleTestSupport {
// filters
"SeverityMatchFilter",
"SuppressionCommentFilter",
"SuppressionFilter",
"SuppressionXpathFilter",
"SuppressionXpathSingleFilter",
"SuppressWarningsFilter",
Expand Down

0 comments on commit 61e2ff5

Please sign in to comment.