Update documentation about "excludes" option of agent (#932)

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;

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>

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>

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>