From a9c5840bc258318e0e5f6c3c79db865cb9cf3f1e Mon Sep 17 00:00:00 2001
From: Andreas Dangel <adangel@apache.org>
Date: Sat, 6 Apr 2019 16:57:54 +0200
Subject: [PATCH] [MPMD-279] Improve documentation of maxAllowedViolations

Submitted by: Jeffrey Bennett
---
 .../pmd/AbstractPmdViolationCheckMojo.java    | 15 ++++++++-
 .../plugins/pmd/PmdViolationCheckMojo.java    | 13 ++++++--
 src/site/fml/faq.fml                          | 31 +++++++++++++++++++
 3 files changed, 55 insertions(+), 4 deletions(-)

diff --git a/src/main/java/org/apache/maven/plugins/pmd/AbstractPmdViolationCheckMojo.java b/src/main/java/org/apache/maven/plugins/pmd/AbstractPmdViolationCheckMojo.java
index a536cae3..57c2ab3c 100644
--- a/src/main/java/org/apache/maven/plugins/pmd/AbstractPmdViolationCheckMojo.java
+++ b/src/main/java/org/apache/maven/plugins/pmd/AbstractPmdViolationCheckMojo.java
@@ -50,6 +50,8 @@ public abstract class AbstractPmdViolationCheckMojo<D>
 
     /**
      * Whether to fail the build if the validation check fails.
+     * The properties {@code failurePriority} and {@code maxAllowedViolations} control
+     * under which conditions exactly the build should be failed.
      */
     @Parameter( property = "pmd.failOnViolation", defaultValue = "true", required = true )
     protected boolean failOnViolation;
@@ -88,7 +90,12 @@ public abstract class AbstractPmdViolationCheckMojo<D>
     private String excludeFromFailureFile;
 
     /**
-     * The maximum number of violations allowed before execution fails.
+     * The maximum number of failures allowed before execution fails.
+     * Used in conjunction with {@code failOnViolation=true} and utilizes {@code failurePriority}.
+     * This value has no meaning if {@code failOnViolation=false}.
+     * If the number of failures is greater than this number, the build will be failed.
+     * If the number of failures is less than or equal to this value,
+     * then the build will not be failed.
      *
      * @since 3.10.0
      */
@@ -157,6 +164,12 @@ protected void executeCheck( final String filename, final String tagName, final
                 }
 
                 this.getLog().info( message );
+
+                if ( failureCount > 0 && isFailOnViolation() && failureCount <= getMaxAllowedViolations() )
+                {
+                    this.getLog().info( "The build is not failed, since " + getMaxAllowedViolations()
+                        + " violations are allowed (maxAllowedViolations)." );
+                }
             }
             catch ( final IOException e )
             {
diff --git a/src/main/java/org/apache/maven/plugins/pmd/PmdViolationCheckMojo.java b/src/main/java/org/apache/maven/plugins/pmd/PmdViolationCheckMojo.java
index 06ba4ba3..43202b8b 100644
--- a/src/main/java/org/apache/maven/plugins/pmd/PmdViolationCheckMojo.java
+++ b/src/main/java/org/apache/maven/plugins/pmd/PmdViolationCheckMojo.java
@@ -58,9 +58,16 @@ public PmdViolationCheckMojo()
     }
 
     /**
-     * What priority level to fail the build on. Failures at or above this level will stop the build. Anything below
-     * will be warnings and will be displayed in the build output if verbose=true. Note: Minimum Priority = 5 Maximum
-     * Priority = 0
+     * What priority level to fail the build on.
+     * PMD violations are assigned a priority from 1 (most severe) to 5 (least severe) according the
+     * the rule's priority.
+     * Violations at or less than this priority level are considered failures and will fail
+     * the build if {@code failOnViolation=true} and the count exceeds {@code maxAllowedViolations}.
+     * The other violations will be regarded as warnings and will be displayed in the build output
+     * if {@code verbose=true}.
+     * Setting a value of 5 will treat all violations as failures, which may cause the build to fail.
+     * Setting a value of 1 will treat all violations as warnings.
+     * Only values from 1 to 5 are valid.
      */
     @Parameter( property = "pmd.failurePriority", defaultValue = "5", required = true )
     private int failurePriority;
diff --git a/src/site/fml/faq.fml b/src/site/fml/faq.fml
index c63d8c7d..e9f80c05 100644
--- a/src/site/fml/faq.fml
+++ b/src/site/fml/faq.fml
@@ -68,5 +68,36 @@ under the License.
         </p>
       </answer>
     </faq>
+    <faq id="violations failures warnings">
+        <question>
+          What's the difference between violations, failures and warnings and when is a build failing?
+        </question>
+        <answer>
+          <p>
+            PMD reports violations. These violations originate from rules - the rules, that are enabled in the
+            configured ruleset (see property <a href="pmd-mojo.html#rulesets">rulesets</a>). Each rule has a assigned
+            priority (1 - high, 2 - medium-high, 3 - medium, 4 - medium-low, 5 - low). This priority is also used
+            for the violation.
+          </p>
+          <p>
+            Violations with a high enough priority can fail the build when using the <a href="check-mojo.html">check</a> goal.
+            These violations are called "failures". The exact priority, when to fail the build, is configured via the property
+            <a href="check-mojo.html#failurePriority">failurePriority</a>.
+          </p>
+          <p>
+            Violations, that have a priority too low to fail the build, are called "warnings". These warnings appear
+            in the report and are displayed in the build output, if the property <a href="check-mojo.html#verbose">verbose</a>
+            is enabled.
+          </p>
+          <p>
+            With the property <a href="check-mojo.html#failOnViolation">failOnViolation</a> the build failure
+            can be entirely disabled. This is most useful at command line with <code>-Dpmd.failOnViolation=false</code>.
+          </p>
+          <p>
+            With the property <a href="check-mojo.html#maxAllowedViolations">maxAllowedViolations</a> one can configure
+            how many failures are allowed, before the build is failed.
+          </p>
+        </answer>
+    </faq>
   </part>
 </faqs>
\ No newline at end of file