You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by el...@apache.org on 2026/10/12 12:26:21 UTC
(maven-checkstyle-plugin) branch site-simplified-english created (now 8c1ba38)
This is an automated email from the ASF dual-hosted git repository.
elharo pushed a change to branch site-simplified-english
in repository https://gitbox.apache.org/repos/asf/maven-checkstyle-plugin.git
at 8c1ba38 Rewrite site documentation in Simplified Technical English
This branch includes the following new commits:
new 8c1ba38 Rewrite site documentation in Simplified Technical English
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(maven-checkstyle-plugin) 01/01: Rewrite site documentation in Simplified Technical English
Posted by el...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
elharo pushed a commit to branch site-simplified-english
in repository https://gitbox.apache.org/repos/asf/maven-checkstyle-plugin.git
commit 8c1ba38d98151f288d0ac82e649ea3d374c480da
Author: Elliotte Rusty Harold <el...@ibiblio.org>
AuthorDate: Mon Oct 12 12:26:17 2026 +0000
Rewrite site documentation in Simplified Technical English
Rewrite the prose in the site markdown pages according to
ASD-STE100 Simplified Technical English. Use simple tenses, active
voice, imperative mood for instructions, and the approved modals.
Remove contractions, semicolons, and -ing verb forms from the prose.
Align the site menu labels with the new page titles.
---
src/site/markdown/config/index.md | 5 +-
.../markdown/examples/custom-checker-config.md.vm | 15 +++---
.../examples/custom-developed-checkstyle.md.vm | 62 ++++++++++++++--------
.../examples/custom-property-expansion.md.vm | 19 ++++---
.../markdown/examples/inline-checker-config.md.vm | 23 ++++----
.../markdown/examples/multi-module-config.md.vm | 36 ++++++++-----
.../markdown/examples/suppressions-filter.md.vm | 10 ++--
.../markdown/examples/upgrading-checkstyle.md.vm | 11 ++--
src/site/markdown/faq.md | 33 ++++++------
src/site/markdown/index.md.vm | 51 ++++++++++++------
src/site/markdown/usage.md.vm | 31 +++++++----
src/site/site.xml | 12 ++---
12 files changed, 195 insertions(+), 113 deletions(-)
diff --git a/src/site/markdown/config/index.md b/src/site/markdown/config/index.md
index 8236161..021fddb 100644
--- a/src/site/markdown/config/index.md
+++ b/src/site/markdown/config/index.md
@@ -27,7 +27,10 @@ under the License.
# Predefined Rulesets
-Maven Checkstyle Plugin has had different sets of predefined rulesets across different versions. Some have been included in the plugin itself while others have been references to other projects. The table below shows this history.
+Maven Checkstyle Plugin had different sets of predefined rulesets across different versions.
+Some rulesets were included in the plugin itself.
+Other rulesets were references to other projects.
+The table below shows this history.
|Predefined ruleset|2.0 - 2.13|2.14|2.15|2.16 -|
|:---|:---|:---|:---|:---|
diff --git a/src/site/markdown/examples/custom-checker-config.md.vm b/src/site/markdown/examples/custom-checker-config.md.vm
index b55021c..5e00f38 100644
--- a/src/site/markdown/examples/custom-checker-config.md.vm
+++ b/src/site/markdown/examples/custom-checker-config.md.vm
@@ -1,5 +1,5 @@
---
-title: Using a Custom Checkstyle Checker Configuration
+title: Custom Checkstyle Checker Configuration
author:
- 2015-05-01
---
@@ -23,11 +23,12 @@ specific language governing permissions and limitations
under the License.
-->
-# Using a Custom Checkstyle Checker Configuration
+# Custom Checkstyle Checker Configuration
-A custom [Checker configuration xml file](https://checkstyle.org/config.html#Checker) can be defined and then referenced via a URL, File, or build classpath resource reference.
+You can define a custom [Checker configuration xml file](https://checkstyle.org/config.html#Checker).
+You can reference it through a URL, a file, or a build classpath resource.
-To reference a custom Checkstyle Checker configuration, use the `configLocation` parameter.
+Use the `configLocation` parameter to reference a custom Checkstyle Checker configuration.
```xml
<project>
@@ -48,9 +49,11 @@ To reference a custom Checkstyle Checker configuration, use the `configLocation`
</project>
```
-This example causes the Checkstyle Plugin to check for a File named `checkstyle.xml` or a resource named `checkstyle.xml` within the compile scope of the dependencies or build extensions classpath.
+This example makes the plugin check for a file named `checkstyle.xml`.
+It can find the file in the compile scope of the dependencies or in the build extensions classpath.
-There are 2 predefined Checkstyle configuration definitions that ship with the Checkstyle Plugin, the Sun Microsystems Definition is selected by default.
+The Checkstyle Plugin ships with two predefined configuration definitions.
+It selects the Sun Microsystems definition by default.
- **sun_checks.xml** - Sun Microsystems Definition (default).
- **google_checks.xml** - Google Definition.
diff --git a/src/site/markdown/examples/custom-developed-checkstyle.md.vm b/src/site/markdown/examples/custom-developed-checkstyle.md.vm
index 8faee84..4e04dd9 100644
--- a/src/site/markdown/examples/custom-developed-checkstyle.md.vm
+++ b/src/site/markdown/examples/custom-developed-checkstyle.md.vm
@@ -1,5 +1,5 @@
---
-title: Using Custom Developed Checkstyle Checks
+title: Custom Developed Checkstyle Checks
author:
- 2008-02-04
---
@@ -23,18 +23,22 @@ specific language governing permissions and limitations
under the License.
-->
-# Using Custom Developed Checkstyle Checks
+# Custom Developed Checkstyle Checks
-We will guide you through creating a Maven project that produces a jar file of your custom checks. Then we'll include it in one of your projects by adding it as a dependency to the Checkstyle Plugin.
+This example shows how to create a Maven project for your custom checks.
+The project generates a jar file.
+You then use the jar file in your other projects.
+You add the jar file as a dependency to the Checkstyle Plugin.
-The plugin also provides the ability to define the [package names XML document](https://checkstyle.org/config.html#Packages) required to reference your custom check modules more easily.
+The plugin also lets you define the [package names XML document](https://checkstyle.org/config.html#Packages).
+This document lets Checkstyle reference your custom check modules.
-In this example we will be using the [example check](https://checkstyle.org/writingchecks.html#Visitor_in_action) that can be found on the Checkstyle web site.
+This example uses the [example check](https://checkstyle.org/writingchecks.html#Visitor_in_action) from the Checkstyle website.
-Structuring your project
-------------------------
+Project Structure
+-----------------
-First we set up the directory structure for the custom checks project. It looks like this:
+This project has the directory structure below:
```unknown
mycompany-checkstyle-checks
@@ -49,11 +53,11 @@ mycompany-checkstyle-checks
`-- MethodLimitCheck.java
```
-Now we'll go through each of the three files one at a time.
+The sections below describe the three files.
#[[### `pom.xml`]]#
-Not much to say here, except that we add a dependency on Checkstyle.
+This POM adds a dependency on Checkstyle.
```xml
<project>
@@ -74,7 +78,10 @@ Not much to say here, except that we add a dependency on Checkstyle.
#[[### `packagenames.xml`]]#
-This file lets you specify the names of the packages that you want to be able to use. Here we have added `com.mycompany.checks` to the standard set of Checkstyle packages. That means that you can use your custom checks in the Checkstyle configuration file, without having to specify their package name.
+This file lets you specify the names of the packages that you want to use.
+This example adds `com.mycompany.checks` to the standard set of Checkstyle packages.
+You can then use your custom checks in the Checkstyle configuration file.
+You do not need to specify their package name.
```xml
<?xml version="1.0" encoding="UTF-8"?>
@@ -109,7 +116,8 @@ This file lets you specify the names of the packages that you want to be able to
#[[### `MethodLimitCheck.java`]]#
-Here is the example check from the Checkstyle site. It checks that your source files don't have more that 30 methods.
+Here is the example check from the Checkstyle site.
+It checks that your source files do not have more than 30 methods.
```java
package com.mycompany.checks;
@@ -140,16 +148,18 @@ public class MethodLimitCheck extends Check
}
```
-Building a JAR for your custom checks project
----------------------------------------------
+Build the JAR for Your Custom Checks Project
+--------------------------------------------
-To be able to use your custom checks in other projects, you need to package and install them. To do that, just run this on the command line:
+To use your custom checks in other projects, package and install them.
+Run this command:
```shell
mvn install
```
-This produces a JAR file with the following contents and installs it into your local repository.
+This command produces a JAR file with these contents.
+It also installs the file into your local repository.
#[[### `mycompany-checkstyle-checks-1.0.jar`]]#
@@ -170,16 +180,18 @@ mycompany-checkstyle-checks-1.0.jar
`-- MethodLimitCheck.class
```
-Using your checks in another project
-------------------------------------
+Use Your Checks in Another Project
+----------------------------------
-Now you are ready to make use of your custom checks in another project.
+You are now ready to use your custom checks in another project.
#[[### Create a Checkstyle configuration]]#
-Create the file `checkstyle.xml` in the root of the project that wants to use your custom checks. In this file you tell Checkstyle which checks you want to use.
+Create the file `checkstyle.xml` in the root of the project that wants to use your custom checks.
+In this file, tell Checkstyle which checks you want to use.
-**Note:** We don't have to specify the fully qualified classname of our check here. That's because we used the `packagenames.xml` file earlier.
+**Note:** You do not have to specify the fully qualified class name of your check here.
+The `packagenames.xml` file makes this possible.
```xml
<?xml version="1.0" ?>
@@ -197,9 +209,13 @@ Create the file `checkstyle.xml` in the root of the project that wants to use yo
#[[### Configure the Checkstyle Plugin to use your custom checks]]#
-Finally we need to tell the other project that you want it to use your custom Checkstyle checks. In the `pom.xml` of that project, add the following configuration.
+Finally, tell the other project to use your custom Checkstyle checks.
+Add this configuration to the `pom.xml` of that project.
-**Note:** You have to specify a plugin dependency on `mycompany-checkstyle-checks` in the `<build>` element of your `pom.xml`. It will not work inside the `<reporting>` element, because `<reporting>` does not support plugin dependencies. The rest of the configuration is done in the normal way in the `<reporting>` element.
+**Note:** You must specify a plugin dependency on `mycompany-checkstyle-checks` in the `<build>` element of your `pom.xml`.
+This dependency will not work in the `<reporting>` element.
+The `<reporting>` element does not support plugin dependencies.
+Do the rest of the configuration in the normal way in the `<reporting>` element.
```xml
<project>
diff --git a/src/site/markdown/examples/custom-property-expansion.md.vm b/src/site/markdown/examples/custom-property-expansion.md.vm
index b6dc1d6..4c35d21 100644
--- a/src/site/markdown/examples/custom-property-expansion.md.vm
+++ b/src/site/markdown/examples/custom-property-expansion.md.vm
@@ -1,5 +1,5 @@
---
-title: Using Custom Checkstyle Property Expansion Definitions
+title: Custom Checkstyle Property Expansion Definitions
author:
- 2006-07-21
---
@@ -23,13 +23,16 @@ specific language governing permissions and limitations
under the License.
-->
-# Using Custom Checkstyle Property Expansion Definitions
+# Custom Checkstyle Property Expansion Definitions
-Custom [property expansion definitions](https://checkstyle.org/config.html#Properties) for the Checker can be defined.
+You can define custom [property expansion definitions](https://checkstyle.org/config.html#Properties) for the Checker.
-Checkstyle uses the property expansion mechanism to allow injection of specific values into a pre-defined Checker configuration. Using property expansion alone is an insufficient means to customize the checks performed by Checkstyle.
+Checkstyle uses the property expansion mechanism to inject specific values into a pre-defined Checker configuration.
+Property expansion alone is not enough to customize the checks that Checkstyle performs.
-Example: `checkstyle.xml` - only checks the package name in use to ensure that it conforms to the desired scheme, but allows for users of this Checker to specify their own projectname.
+Example: `checkstyle.xml` - This configuration checks the package name in use.
+It makes sure that the package name conforms to the desired scheme.
+It also lets the Checker users specify their own projectname.
```xml
<?xml version="1.0" ?>
@@ -48,7 +51,8 @@ Example: `checkstyle.xml` - only checks the package name in use to ensure that i
</module>
```
-Example: `pom.xml` - Specifies the `projectname` property expansion that Checkstyle will use when encountering such a variable in the above Checker configuration.
+Example: `pom.xml` - This configuration specifies the `projectname` property expansion.
+Checkstyle uses it when it encounters the variable in the Checker configuration above.
```xml
<project>
@@ -73,7 +77,8 @@ Example: `pom.xml` - Specifies the `projectname` property expansion that Checkst
</project>
```
-The property expansion information can also come from a location using the `propertiesLocation` parameter as shown below. The `propertiesLocation` can point to a URL, File or build classpath resource reference.
+You can also provide the property expansion information from a location with the `propertiesLocation` parameter as shown below.
+The parameter can point to a URL, a file, or a build classpath resource.
```xml
<project>
diff --git a/src/site/markdown/examples/inline-checker-config.md.vm b/src/site/markdown/examples/inline-checker-config.md.vm
index 36d180a..eef312b 100644
--- a/src/site/markdown/examples/inline-checker-config.md.vm
+++ b/src/site/markdown/examples/inline-checker-config.md.vm
@@ -1,5 +1,5 @@
---
-title: Using an 'inlined' Checkstyle Checker Configuration
+title: Inline Checkstyle Checker Configuration
author:
- 2015-10-04
---
@@ -23,13 +23,15 @@ specific language governing permissions and limitations
under the License.
-->
-# Using an Inline Checkstyle Checker Configuration
+# Inline Checkstyle Checker Configuration
-Since version 2.12, an inlined [Checker configuration](https://checkstyle.org/config.html#Checker) can be defined directly in the `configuration` section of the plugin itself inside your `pom.xml`.
+From version 2.12, you can define an inline [Checker configuration](https://checkstyle.org/config.html#Checker) directly in the `configuration` section of the plugin inside your `pom.xml`.
-This is especially useful when the Checkstyle checks should be executed with every compile and you do not like to create an own project for your Checkstyle rules and neither like to have a separate parent POM structure.
+This is useful when you want to run the Checkstyle checks with every compile.
+You do not need to create a separate project for your Checkstyle rules.
+You do not need a separate parent POM structure.
-To define a custom Checkstyle checker configuration inside your `pom.xml`, use the `checkstyleRules` parameter.
+Use the `checkstyleRules` parameter to define a custom Checkstyle checker configuration inside your `pom.xml`.
```xml
<project>
@@ -81,13 +83,16 @@ To define a custom Checkstyle checker configuration inside your `pom.xml`, use t
</project>
```
-# Using a different header
+# Different Header
-The inline configuration works by writing the configuration to a file and passing that file to checkstyle. This configuration file must contain a specific [header](https://checkstyle.org/config.html#Configuration_XML_Structure).
+The plugin writes the inline configuration to a file.
+It then passes the file to checkstyle.
+The configuration file must contain a specific [header](https://checkstyle.org/config.html#Configuration_XML_Structure).
-We include one by default that is compatible with the included checkstyle version.
+The plugin includes one by default.
+The default header is compatible with the included checkstyle version.
-When you use a different checkstyle version than the the one that's included it might be necessary for you to specify a different header:
+When you use a different checkstyle version than the one that is included, you must specify a different header:
```xml
<project>
diff --git a/src/site/markdown/examples/multi-module-config.md.vm b/src/site/markdown/examples/multi-module-config.md.vm
index c9d7535..b6a34c3 100644
--- a/src/site/markdown/examples/multi-module-config.md.vm
+++ b/src/site/markdown/examples/multi-module-config.md.vm
@@ -25,11 +25,13 @@ under the License.
# Multimodule Configuration
-Since version 2.12 of this Plugin you can also [inline](./inline-checker-config.html) the configuration directly in the parent pom.
+From version 2.12 of this Plugin, you can [inline](./inline-checker-config.html) the configuration directly in the parent POM.
-Configuring the Checkstyle Plugin for use within large multimodule projects can be done, but it requires a little setup.
+You can configure the Checkstyle Plugin for large multimodule projects.
+It requires some setup.
-This example will use a mysterious project called _whizbang_. This is what the structure of that project looks like:
+This example uses a sample project called _whizbang_.
+The project has the structure below:
```unknown
whizbang
@@ -46,7 +48,11 @@ whizbang
Create a subproject to house the resources
------------------------------------------
-We'll start by adding another sub project that will house our common configuration. Let's call it _build-tools_. In it we put the resources that we want to include. In this example, we will add configuration files for the Checkstyle Plugin. Configuration files for other plugins, like the PMD plugin, can be included in the same subproject if you like.
+Create another subproject that houses your common configuration.
+Call it _build-tools_.
+Put the resources that you want to include in the subproject.
+In this example, add configuration files for the Checkstyle Plugin.
+You can also include configuration files for other plugins, like the PMD plugin, in the same subproject.
```unknown
whizbang
@@ -65,9 +71,9 @@ whizbang
`-- src
```
-**Tip:** put the resources into a subdirectory that you can ensure will be unique and not conflict with anyone else.
+**Tip:** Put the resources into a unique subdirectory so that they do not conflict with anyone else.
-The `pom.xml` file for _build-tools_ should look like this:
+The `pom.xml` file for _build-tools_ looks like this:
```xml
<project>
@@ -82,9 +88,12 @@ The `pom.xml` file for _build-tools_ should look like this:
Configure the other projects to use it
--------------------------------------
-Now we can include the Checkstyle configuration in the top level `pom.xml`.
+Now include the Checkstyle configuration in the top level `pom.xml`.
-**Note:** You have to specify a plugin dependency on `build-tools` in the `<build>` element of your `pom.xml`. It will not work inside the `<reporting>` element, because `<reporting>` does not support plugin dependencies. The rest of the configuration is done in the normal way in the `<reporting>` element.
+**Note:** You must specify a plugin dependency on `build-tools` in the `<build>` element of your `pom.xml`.
+This dependency will not work in the `<reporting>` element.
+The `<reporting>` element does not support plugin dependencies.
+Do the rest of the configuration in the normal way in the `<reporting>` element.
```xml
<project>
@@ -132,14 +141,17 @@ Now we can include the Checkstyle configuration in the top level `pom.xml`.
</project>
```
-Once you are done with that, ensure that you do not include the Maven Checkstyle Plugin in your sub modules, as their definition and configuration, will override the top level parent pom's definition.
+Make sure that you do not include the Maven Checkstyle Plugin in your submodules.
+A submodule definition overrides the top level parent POM definition.
-Based on the Checkstyle Plugin configuration above, the values of `configLocation` and `headerLocation` will be resolved from the classpath. The _build-tools_ JAR was included in the classpath when it was declared as a dependency to the plugin.
+The plugin resolves the values of `configLocation` and `headerLocation` from the classpath.
+The _build-tools_ JAR is in the classpath.
+You declared the JAR as a dependency to the plugin.
-Lastly, kick off a build of the site.
+Then run a build of the site:
```shell
mvn site
```
-Every sub project will now use the same Checkstyle setup and configuration.
+Every subproject now uses the same Checkstyle setup and configuration.
diff --git a/src/site/markdown/examples/suppressions-filter.md.vm b/src/site/markdown/examples/suppressions-filter.md.vm
index 9f9d112..0a9c0a0 100644
--- a/src/site/markdown/examples/suppressions-filter.md.vm
+++ b/src/site/markdown/examples/suppressions-filter.md.vm
@@ -1,5 +1,5 @@
---
-title: Using a Suppressions Filter
+title: Suppressions Filter
author:
- 2006-07-21
---
@@ -23,9 +23,11 @@ specific language governing permissions and limitations
under the License.
-->
-# Using a Suppressions Filter
+# Suppressions Filter
-Checkstyle allows the definition of a list of files and their line ranges that should be suppressed from reporting any violations (known as a [suppressions filter](https://checkstyle.org/config.html#Filters) ).
+Checkstyle lets you define a list of files and their line ranges.
+Checkstyle does not report violations in these ranges.
+This list is called a [suppressions filter](https://checkstyle.org/config.html#Filters).
Example: `checkstyle-suppressions.xml`
@@ -46,7 +48,7 @@ Example: `checkstyle-suppressions.xml`
</suppressions>
```
-Example: `pom.xml` - Specifies the suppressions filter that Checkstyle should use.
+Example: `pom.xml` - This configuration specifies the suppressions filter for Checkstyle.
```xml
<project>
diff --git a/src/site/markdown/examples/upgrading-checkstyle.md.vm b/src/site/markdown/examples/upgrading-checkstyle.md.vm
index 802ed00..58f99c4 100644
--- a/src/site/markdown/examples/upgrading-checkstyle.md.vm
+++ b/src/site/markdown/examples/upgrading-checkstyle.md.vm
@@ -1,5 +1,5 @@
---
-title: Upgrading Checkstyle at Runtime
+title: Upgrade Checkstyle at Runtime
author:
- 2022-02-07
---
@@ -23,11 +23,14 @@ specific language governing permissions and limitations
under the License.
-->
-# Upgrading Checkstyle at Runtime
+# Upgrade Checkstyle at Runtime
-Maven Checkstyle plugin comes with a default Checkstyle version: for `maven-checkstyle-plugin ${project.version}`, Checkstyle ${checkstyleVersion} is used by default.
+The Maven Checkstyle Plugin has a default Checkstyle version.
+For `maven-checkstyle-plugin ${project.version}`, the plugin uses Checkstyle ${checkstyleVersion} by default.
-Given Checkstyle generally keeps good compatibility between versions, you can override the version used at runtime to benefit from [Checkstyle latest bugfixes](https://checkstyle.org/releasenotes.html):
+Checkstyle keeps good compatibility between versions.
+You can override the version used at runtime.
+This lets you use the [latest Checkstyle bug fixes](https://checkstyle.org/releasenotes.html):
```xml
<project>
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index 74eecac..ac60f6c 100644
--- a/src/site/markdown/faq.md
+++ b/src/site/markdown/faq.md
@@ -33,40 +33,41 @@ under the License.
<a id="Where_is_maven_checks.xml_predefined_ruleset"></a>
-### Where is `config/maven_checks.xml` predefined ruleset?
+### Where is the `config/maven_checks.xml` predefined ruleset?
-Starting with maven-checkstyle-plugin version 2.14, `config/maven_checks.xml`
-predefined ruleset is not part of the plugin any more but has moved to
-[Apache Maven Shared Resources](/shared/maven-shared-resources/).
+From maven-checkstyle-plugin version 2.14, `config/maven_checks.xml`
+is no longer part of the plugin.
+The file moved to [Apache Maven Shared Resources](/shared/maven-shared-resources/).
<a id="How_are_the_Checkstyle_properties_set"></a>
### How are the Checkstyle properties set?
-You can set the Checkstyle properties to be used in the plugin configuration of your
-POM through the `propertiesLocation` parameter. The properties file will be resolved
-by the plugin based on its value.
+You can set the Checkstyle properties with the `propertiesLocation` parameter in the
+plugin configuration of your POM.
+The plugin resolves the properties file from the value of the parameter.
<a id="How_do_I_set_a_custom_ruleset"></a>
### How do I set a custom ruleset?
-You can set a custom ruleset through the `configLocation` plugin parameter. If no
-value is specified, the plugin will use a default ruleset, which is the
-`sun_checks.xml`, that is bundled with the plugin.
+You can set a custom ruleset with the `configLocation` plugin parameter.
+If you do not specify a value, the plugin uses the `sun_checks.xml` ruleset.
+This ruleset is bundled with the plugin.
<a id="How_do_I_include_the_test_directory_in_Checkstyle"></a>
### How do I include the test directory in Checkstyle?
-You can include the test directory in the Checkstyle report by setting the
-`includeTestSourceDirectory` plugin parameter to `true`.
+You can include the test directory in the Checkstyle report.
+The `includeTestSourceDirectory` plugin parameter must be `true`.
<a id="What_is_the_difference_between_checkstyle.3Acheckstyle_and_checkstyle.3Acheck"></a>
### What is the difference between checkstyle:checkstyle and checkstyle:check?
-The checkstyle:checkstyle goal is a **reporting** goal that adds a report of
-Checkstyle violations to the output of the maven-site-plugin. The checkstyle:check
-goal is an ordinary goal that reports violations to the console and/or fails the
-build when there are violations.
+The checkstyle:checkstyle goal is a **reporting** goal.
+It adds a report of Checkstyle violations to the output of the maven-site-plugin.
+The checkstyle:check goal is an ordinary goal.
+It reports violations to the console.
+It fails the build when there are violations.
diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm
index 5786c52..b93c967 100644
--- a/src/site/markdown/index.md.vm
+++ b/src/site/markdown/index.md.vm
@@ -26,11 +26,16 @@ under the License.
# ${project.name}
-The Checkstyle Plugin generates a report regarding the code style used by the developers. For more information about Checkstyle, see [https://checkstyle.org/](https://checkstyle.org/).
+The Checkstyle Plugin generates a report on the code style used by the developers.
+For more information about Checkstyle, see [https://checkstyle.org/](https://checkstyle.org/).
-This version of the plugin uses Checkstyle ${checkstyleVersion} by default and requires Java ${javaVersion}. But you can [upgrade the version used at runtime](./examples/upgrading-checkstyle.html).
+This version of the plugin uses Checkstyle ${checkstyleVersion} by default.
+It requires Java ${javaVersion}.
+You can [upgrade the version used at runtime](./examples/upgrading-checkstyle.html).
-The plugin can be configured in the project's POM. Predefined rulesets available for use in this version of the plugin are: [`sun_checks.xml`](https://checkstyle.org/sun_style.html) and [`google_checks.xml`](https://checkstyle.org/google_style.html). You can also use a custom ruleset by specifying it in the plugin configuration.
+The plugin can be configured in the project's POM.
+This version of the plugin provides two predefined rulesets: [`sun_checks.xml`](https://checkstyle.org/sun_style.html) and [`google_checks.xml`](https://checkstyle.org/google_style.html).
+You can also use a custom ruleset in the plugin configuration.
Goals Overview
--------------
@@ -39,34 +44,48 @@ The Checkstyle Plugin has three goals:
- [checkstyle:checkstyle](./checkstyle-mojo.html) is a reporting goal that performs Checkstyle analysis and generates a report on violations.
- [checkstyle:checkstyle-aggregate](./checkstyle-aggregate-mojo.html) is a reporting goal that performs Checkstyle analysis and generates an aggregate HTML report on violations in a multi-module reactor build.
-- [checkstyle:check](./check-mojo.html) is a goal that performs Checkstyle analysis and outputs violations or a count of violations to the console, potentially failing the build. It can also be configured to re-use an earlier analysis.
+- [checkstyle:check](./check-mojo.html) is a goal that performs Checkstyle analysis and outputs violations or a count of violations to the console.
+ It can also fail the build.
+ You can configure it to re-use an earlier analysis.
Major Version Upgrade to version 3.0.0
--------------------------------------
-Please note that the following parameters have been completely removed from the plugin configuration:
+These two parameters were removed from the plugin configuration:
-- `sourceDirectory`: use `sourceDirectories` instead;
+- `sourceDirectory`: use `sourceDirectories` instead.
- `testSourceDirectory`: use `testSourceDirectories` instead.
Usage
-----
-General instructions on how to use the Checkstyle Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples given below.
+General instructions on how to use the Checkstyle Plugin are on the [usage page](./usage.html).
+The examples below describe more specific use cases.
-In case you still have questions regarding the plugin's usage, please have a look at the [FAQ](./faq.html) and feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html).
+If you still have questions about the plugin's usage, look at the [FAQ](./faq.html).
+You can also contact the [user mailing list](./mailing-lists.html).
+The posts to the mailing list are archived.
+An older thread can contain the answer to your question.
+You can also search the [mail archive](./mailing-lists.html).
-If you feel like the plugin is missing a feature or has a defect, you can fill a feature request or bug report in our [issue tracker](https://issues.apache.org/jira/projects/MCHECKSTYLE/). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciate [...]
+If you think that the plugin lacks a feature or has a defect, report it in the [issue tracker](https://issues.apache.org/jira/projects/MCHECKSTYLE/).
+When you create a new issue, include a comprehensive description of your concern.
+For bug fixes, the developers must be able to reproduce your problem.
+Attach entire debug logs, POMs, or little demo projects to the issue.
+Patches are welcome.
+
+Contributors can check out the project from the [source repository](./scm.html).
+They can also find supplementary information in the [guide to helping with Maven](https://maven.apache.org/guides/development/guide-helping.html).
Examples
--------
-The following examples show how to use the Checkstyle Plugin in more advanced usecases:
+The examples below show how to use the Checkstyle Plugin in more advanced use cases:
-- [Upgrading Checkstyle at Runtime](./examples/upgrading-checkstyle.html)
-- [Using an 'Inline' Checkstyle Checker Configuration](./examples/inline-checker-config.html)
-- [Using a Custom Checkstyle Checker Configuration](./examples/custom-checker-config.html)
-- [Using Custom Checkstyle Property Expansion Definitions](./examples/custom-property-expansion.html)
-- [Using a Suppressions Filter](./examples/suppressions-filter.html)
-- [Using Custom Developed Checkstyle Check Modules](./examples/custom-developed-checkstyle.html)
+- [Upgrade Checkstyle at Runtime](./examples/upgrading-checkstyle.html)
+- [Inline Checkstyle Checker Configuration](./examples/inline-checker-config.html)
+- [Custom Checkstyle Checker Configuration](./examples/custom-checker-config.html)
+- [Custom Checkstyle Property Expansion Definitions](./examples/custom-property-expansion.html)
+- [Suppressions Filter](./examples/suppressions-filter.html)
+- [Custom Developed Checkstyle Check Modules](./examples/custom-developed-checkstyle.html)
- [Multimodule Configuration](./examples/multi-module-config.html)
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index 567c24b..7af9f9c 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -26,12 +26,13 @@ under the License.
# Usage
-The following examples describe the basic usage of the Checkstyle Plugin.
+The examples below describe the basic usage of the Checkstyle Plugin.
Generate Checkstyle Report As Part of the Project Reports
---------------------------------------------------------
-To generate the Checkstyle report as part of the Project Reports, add the Checkstyle Plugin in the `<reporting>` section of your `pom.xml`.
+Generate the Checkstyle report as part of the Project Reports.
+Add the Checkstyle Plugin to the `<reporting>` section of your `pom.xml`.
```xml
<project>
@@ -56,7 +57,7 @@ To generate the Checkstyle report as part of the Project Reports, add the Checks
</project>
```
-Then, execute the site phase to generate the report.
+Run the site phase to generate the report.
```shell
mvn site
@@ -65,20 +66,32 @@ mvn site
Generate Checkstyle Report As Standalone
----------------------------------------
-You can also generate the Checkstyle report by explicitly executing the `checkstyle:checkstyle` goal from the command line. You are not required to specify the Checkstyle Plugin in your `pom.xml` unless you want to use a specific configuration.
+You can also generate the Checkstyle report with the `checkstyle:checkstyle` goal from the command line.
+You do not need to specify the Checkstyle Plugin in your `pom.xml` unless you need a specific configuration.
```shell
mvn checkstyle:checkstyle
```
-Checking for Violations as Part of the Build
---------------------------------------------
+Check for Violations as Part of the Build
+-----------------------------------------
-If you want to report to the console or fail the build, you must add an execution of `checkstyle::check` to the `<build>` element and configure any options that you need.
+If you want the console report or a build failure, add an execution of `checkstyle::check` to the `<build>` element.
+Configure any options that you need.
-Options you set in the `<reporting>` element do not have any effect on executions in the `<build>` element.
+Options that you set in the `<reporting>` element do not affect executions in the `<build>` element.
-Note that the phase that `checkstyle::check` is bound to is very important. If bound to the validate phase, it would check the code prior to compiling the code. If the code is invalid, the parsing errors reported by checkstyle may be different than what would be expected from the javac compiler. However, it's guaranteed to run. Another popular option is to bind it to the verify phase which would run much later (and allow the javac compiler to flag invalid code prior to checkstyle). Howev [...]
+The phase that `checkstyle::check` is bound to is important.
+If you bind it to the validate phase, it checks the code before compilation.
+It is guaranteed to run.
+If the code is invalid, the errors that checkstyle reports can differ from the errors from the javac compiler.
+
+Another common option binds the goal to the verify phase.
+The verify phase runs much later than the validate phase.
+A later phase lets the javac compiler flag invalid code before checkstyle runs.
+
+If developers run `mvn test` before they push changes, checkstyle does not run.
+The verify phase occurs after the test phase.
For example:
diff --git a/src/site/site.xml b/src/site/site.xml
index fd37ffd..e66a943 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -32,12 +32,12 @@ under the License.
<item name="Releases History" href="history.html"/>
</menu>
<menu name="Examples">
- <item name="Upgrading Checkstyle at Runtime" href="/examples/upgrading-checkstyle.html"/>
- <item name="Using an Inline Checkstyle Checker Configuration" href="/examples/inline-checker-config.html"/>
- <item name="Using a Custom Checkstyle Checker Configuration" href="/examples/custom-checker-config.html"/>
- <item name="Using Custom Checkstyle Property Expansion Definitions" href="/examples/custom-property-expansion.html"/>
- <item name="Using a Suppressions Filter" href="/examples/suppressions-filter.html"/>
- <item name="Using Custom Developed Checkstyle Checks" href="/examples/custom-developed-checkstyle.html"/>
+ <item name="Upgrade Checkstyle at Runtime" href="/examples/upgrading-checkstyle.html"/>
+ <item name="Inline Checkstyle Checker Configuration" href="/examples/inline-checker-config.html"/>
+ <item name="Custom Checkstyle Checker Configuration" href="/examples/custom-checker-config.html"/>
+ <item name="Custom Checkstyle Property Expansion Definitions" href="/examples/custom-property-expansion.html"/>
+ <item name="Suppressions Filter" href="/examples/suppressions-filter.html"/>
+ <item name="Custom Developed Checkstyle Checks" href="/examples/custom-developed-checkstyle.html"/>
<item name="Multimodule Configuration" href="/examples/multi-module-config.html"/>
</menu>
</body>