From 8b586a98803923f11a9b05fe214fa25c2c23207f Mon Sep 17 00:00:00 2001
From: "Marc R. Hoffmann" <hoffmann@mountainminds.com>
Date: Thu, 19 Sep 2019 23:45:08 +0200
Subject: [PATCH] Update documentation about "excludes" option of agent (#932)

---
 .../org/jacoco/maven/AbstractAgentMojo.java   |  5 ++++-
 org.jacoco.doc/docroot/doc/agent.html         |  4 +++-
 org.jacoco.doc/docroot/doc/ant.html           |  3 ++-
 org.jacoco.doc/docroot/doc/faq.html           | 21 +++++++++++++++++++
 4 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/jacoco-maven-plugin/src/org/jacoco/maven/AbstractAgentMojo.java b/jacoco-maven-plugin/src/org/jacoco/maven/AbstractAgentMojo.java
index d097c530c8..5f862793bd 100644
--- a/jacoco-maven-plugin/src/org/jacoco/maven/AbstractAgentMojo.java
+++ b/jacoco-maven-plugin/src/org/jacoco/maven/AbstractAgentMojo.java
@@ -68,7 +68,10 @@ public abstract class AbstractAgentMojo extends AbstractJacocoMojo {
 
 	/**
 	 * A list of class names to exclude from instrumentation. May use wildcard
-	 * characters (* and ?). When not specified nothing will be excluded.
+	 * characters (* and ?). When not specified nothing will be excluded. Except
+	 * for performance optimization or technical corner cases this option is
+	 * normally not required. If you want to exclude classes from the report
+	 * please configure the <code>report</code> goal accordingly.
 	 */
 	@Parameter
 	private List<String> excludes;
diff --git a/org.jacoco.doc/docroot/doc/agent.html b/org.jacoco.doc/docroot/doc/agent.html
index b9b5731ebd..05eb992ddb 100644
--- a/org.jacoco.doc/docroot/doc/agent.html
+++ b/org.jacoco.doc/docroot/doc/agent.html
@@ -100,7 +100,9 @@ <h1>Java Agent</h1>
           The list entries are separated by a colon (<code>:</code>) and
           may use wildcard characters (<code>*</code> and <code>?</code>).
           Except for performance optimization or technical corner cases this
-          option is normally not required. 
+          option is normally not required. If you want to exclude classes from
+          the report please configure the respective report generation tool
+          accordingly.
       </td>
       <td><i>empty</i> (no excluded classes)</td>
     </tr>
diff --git a/org.jacoco.doc/docroot/doc/ant.html b/org.jacoco.doc/docroot/doc/ant.html
index c7cf5bba6b..de02410b8b 100644
--- a/org.jacoco.doc/docroot/doc/ant.html
+++ b/org.jacoco.doc/docroot/doc/ant.html
@@ -191,7 +191,8 @@ <h2><a name="coverage">Task <code>coverage</code></a></h2>
           The list entries are separated by a colon (<code>:</code>) and
           may use wildcard characters (<code>*</code> and <code>?</code>).
           Except for performance optimization or technical corner cases this
-          option is normally not required. 
+          option is normally not required. If you want to exclude classes from
+          the report please configure the <code>report</code> task accordingly.
       </td>
       <td><i>empty</i> (no excluded classes)</td>
     </tr>
diff --git a/org.jacoco.doc/docroot/doc/faq.html b/org.jacoco.doc/docroot/doc/faq.html
index e7e9f3eedf..b13e66998a 100644
--- a/org.jacoco.doc/docroot/doc/faq.html
+++ b/org.jacoco.doc/docroot/doc/faq.html
@@ -184,6 +184,27 @@ <h3>Why do I get a <code>StackOverflowError</code> during code coverage analysis
       the <code>-Xss</code> JVM option.</li>
 </ul>
 
+<h3>Why do I see classes in the coverage report although I excluded them in the JaCoCo agent configuration?</h3>
+<p>
+  The <code>includes</code> and <code>excludes</code> options of the
+  <a href="agent.html">JaCoCo agent</a> determine for which classes execution
+  data is collected. Except for technical corner cases these options are
+  normally not required. If you exclude classes, no execution data is collected
+  for them.
+</p> 
+<p>  
+  Report creation is a separate step where all class files which should show up
+  in the report are explicitly provided. Coverage is determined from the
+  provided execution data. If execution data is missing for a particular class,
+  this class is shown as not covered because the report generator cannot
+  distinguish whether the class was excluded or not executed.
+</p>
+
+<p>
+  If you want to exclude classes from the report please configure the
+  respective report generation tool accordingly. 
+</p>
+
 </div>
 <div class="footer">
   <span class="right"><a href="${jacoco.home.url}">JaCoCo</a> ${qualified.bundle.version}</span>