This is an automated email from the ASF dual-hosted git repository.
elharo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-checkstyle-plugin.git
The following commit(s) were added to refs/heads/master by this push:
new 1170aa3 Rewrite site documentation in Simplified Technical English
(#719)
1170aa3 is described below
commit 1170aa3c8721b7b7c32c3c8ca5afc47ba14af968
Author: Elliotte Rusty Harold <[email protected]>
AuthorDate: Tue Nov 10 20:49:04 2026 +0000
Rewrite site documentation in Simplified Technical English (#719)
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 d64273a..b5002aa 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:
```text
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 88ffb56..3407633 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:
```text
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.
```text
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>