Coverage counter definitions, link to XML report, new outline for documentation.

author: Marc R. Hoffmann <hoffmann@mountainminds.com> 2009-10-02 13:28:46 +0000
committer: Marc R. Hoffmann <hoffmann@mountainminds.com> 2009-10-02 13:28:46 +0000
commit: c4b2078689a7dbdc27c10ca4938c27fc01e64f22 (patch)
tree: 04b35b943ff6c82f997f7738935d4374c6d5a9b0 /org.jacoco.doc
parent: 5d43ad44e9f73cab0e8fd18b3143036a2f23e6cf (diff)
download: jacoco-c4b2078689a7dbdc27c10ca4938c27fc01e64f22.tar.gz
5 files changed, 161 insertions, 10 deletions
diff --git a/org.jacoco.doc/docroot/doc/counters.html b/org.jacoco.doc/docroot/doc/counters.html
new file mode 100644
index 00000000..9fcc12e9
--- /dev/null
+++ b/org.jacoco.doc/docroot/doc/counters.html
@@ -0,0 +1,127 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+  <link rel="stylesheet" href=".resources/doc.css" charset="ISO-8859-1" type="text/css" />
+  <title>JaCoCo - Coverage Counter</title>
+</head>
+<body>
+
+<div class="breadcrumb">
+  <a href="../index.html" class="el_session">JaCoCo</a> &gt;
+  <a href="index.html" class="el_group">Documentation</a> &gt;
+  <span class="el_source">Coverage Counters</span>
+</div>
+
+<h1>Coverage Counters</h1>
+
+<p>
+  JaCoCo uses a set of different counters to calculate coverage metrics. The
+  foundation of all counters are so called <i>basic blocks</i>. All other
+  counters are derived from the <i>basic block</i> coverage information. While
+  JaCoCo counters appear to be closely related to Java source code they are
+  actually only derived from Java class files. In cases where the Java compiler
+  creates so called <i>synthetic</i> code to reflect certain Java language
+  constructs counters may therefore show unexpected results.   
+</p>
+
+<h2>Basic Blocks</h2>
+
+<p>
+  Basic blocks &ndash; mostly just referred to as <i>blocks</i> in the APIs and
+  reports &ndash; are consecutive sequences of byte code instructions that will
+  normally only executed on-block. The boundaries between blocks are
+</p>
+
+<ul>
+  <li>return instructions,</li>
+  <li>throw instructions,</li>
+  <li>(conditional) jump instructions and</li>
+  <li>target labels referred from jump, try/catch or switch instructions.</li>
+</ul>
+
+<p>
+  The JaCoCo instrumentation mechanism inserts a probe at the end of every
+  block. When the probe gets executes the block can be considered as executed.
+  Unfortunately the opposite does not hold true: Exceptions might interrupt a
+  block somewhere in the middle and the probe will not get executed. This
+  results in the major drawback of basic block based probes:
+</p>
+
+<p class="hint">
+  Blocks that encounter an exception somewhere in the middle will be considered
+  as not executed.  
+</p>
+
+<p>
+  Beside this, basic block code coverage has been proven to work very
+  efficiently even with huge applications under test. The reasons are that the
+  blocks can be easily determined at instrumentation time. The amount of
+  inserted probes offer a good tradeoff between runtime overhead and report
+  granularity. And last but not least basic blocks can be determined even if the
+  class files have not been compiled in debug mode and therefore do not contain
+  any source line information. Therefore all coverage counters except the line
+  counter will work also in this case and provide useful coverage information
+  e.g. for binary third party libraries.  
+</p>
+
+<h2>Instructions</h2>
+
+<p>
+  For each block the number of included byte code instructions can be easily
+  determined. The instruction counter summarizes the number of single byte code
+  instructions that belong to executed blocks. As blocks may have different
+  lengths instructions represent the size of the blocks and can serve as a
+  replacement when no line information is available. 
+</p>
+
+<h2>Lines</h2>
+
+<p>
+  For all class files that have been compiled in debug mode with source line
+  information, coverage information for individual lines can be calculated from
+  basic blocks. Each block may span one ore multiple lines of source code. On
+  the other hand a single line of source my belong to multiple blocks. A source
+  line is considered as executed when at least one block that includes this line
+  has been executed.
+</p>
+
+<p>
+  Due to the fact that a single line may belong to more that one block 
+  <i>partial</i> coverage can happen if some of the blocks are executed while
+  others are not. This is typically the case with boolean expressions. While
+  partially coverage lines are counted as executed due to the definition in the
+  previous paragraph, they are highlighted in yellow color in the coverage
+  reports. 
+</p>
+
+<h2>Methods</h2>
+
+<p>
+  Each non-abstract method consists of at least one block. A method is
+  considered as executed when at least one block has been executed. As JaCoCo
+  works on byte code level also constructors and static initializers are counted
+  as methods. Some of these methods may not have a direct correspondence in Java
+  source code, like implicitly generated default constructors or initializers
+  for constants.
+</p>
+
+<h2>Classes</h2>
+
+<p>
+  A class is considered as executed when at least one of its method has been
+  executed. Note that JaCoCo considers constructors as well as static
+  initializers as methods. As Java interface types may contain static
+  initializers such interfaces are also considered as executable classes.
+</p>
+
+
+
+<div class="footer">
+  <div class="versioninfo"><a href="@HOMEURL@">JaCoCo</a> @VERSION@</div>
+  <a href="license.html">Copyright</a> &copy; 2009 Mountainminds GmbH &amp; Co. KG and Contributors
+</div>
+
+</body>
+</html>
+\ No newline at end of file
diff --git a/org.jacoco.doc/docroot/doc/implementation.html b/org.jacoco.doc/docroot/doc/implementation.html
index 39d3865a..f2e8595e 100644
--- a/org.jacoco.doc/docroot/doc/implementation.html
+++ b/org.jacoco.doc/docroot/doc/implementation.html
@@ -53,7 +53,7 @@
   <li><span class="high">Instrumentation*</span>
     <ul>
       <li>Java Source Instrumentation</li>
-      <li><span class="high">Byte Code Instrumentation'</span>
+      <li><span class="high">Byte Code Instrumentation*</span>
         <ul>
           <li>Offline
             <ul>
@@ -94,8 +94,9 @@
 
 <p class="intro">
   Instrumentation means inserting probes at certain check points in the Java
-  byte code. A probe generated piece of byte code that records the fact that it
-  has been executed. JaCoCo inserts probes at the end of every basic block.    
+  byte code. A probe is a generated piece of byte code that records the fact
+  that it has been executed. JaCoCo inserts probes at the end of every basic
+  block.    
 </p>
 
 <p>
diff --git a/org.jacoco.doc/docroot/doc/index.html b/org.jacoco.doc/docroot/doc/index.html
index c483eb89..180ca00d 100644
--- a/org.jacoco.doc/docroot/doc/index.html
+++ b/org.jacoco.doc/docroot/doc/index.html
@@ -15,14 +15,38 @@
 
 <h1>Documentation</h1>
 
-<h2>Contents</h2>
+<h3>Concepts</h3>
 
 <ul>
   <li><a href="mission.html">Mission</a></li>
-  <li><a href="implementation.html">Implementation Design</a></li>
+  <li><i>Introduction to Code Coverage</i></li>
+  <li><a href="counters.html">Coverage Counters</a></li>
+</ul>
+
+<h3>Using JaCoCo</h3>
+
+<ul>
   <li><a href="ant.html">Ant Tasks</a></li>
   <li><a href="agent.html">Java Agent</a></li>
+</ul>
+
+<h3>Integrating JaCoCo</h3>
+
+<ul>
+  <li><a href="implementation.html">Implementation Design</a></li>
   <li><a href="api/index.html">API Documentation (JavaDoc)</a></li>
+</ul>
+
+<h3>Developing JaCoCo</h3>
+
+<ul>
+  <li><i>Development Environment</i></li>
+  <li><i>Building JaCoCo</i></li>
+</ul>
+
+<h3>Legal</h3>
+
+<ul>
   <li><a href="license.html">License</a></li>
 </ul>
 
diff --git a/org.jacoco.doc/docroot/index.html b/org.jacoco.doc/docroot/index.html
index f243d294..96c2e6bb 100644
--- a/org.jacoco.doc/docroot/index.html
+++ b/org.jacoco.doc/docroot/index.html
@@ -38,7 +38,8 @@
   <li><a href="doc/index.html">Documentation</a></li>
   <li><a href="test/index.html">JUnit Test Results</a></li>
   <li><a href="coverage/index.html">Code Coverage Report</a>
-      (<a href="coverage/JaCoCo.csv">CSV</a>)</li>
+      (<a href="coverage/JaCoCo.csv">CSV</a>, 
+       <a href="coverage/JaCoCo.xml">XML</a>)</li>
   <li><a href="doc/license.html">License</a></li>
 </ul>
 
@@ -78,7 +79,7 @@
     </tr>
     <tr>
       <td>org.jacoco.ant_@VERSION@.jar</td>
-      <td>JaCoCo ant bundle</td>
+      <td>JaCoCo Ant bundle</td>
       <td>JaCoCo core, JaCoCo report, ASM 3.x, Ant 1.7.x</td>
     </tr>
   </tbody>
diff --git a/org.jacoco.doc/junitstyle/junit-noframes.xsl b/org.jacoco.doc/junitstyle/junit-noframes.xsl
index a4b4763c..f843fe59 100644
--- a/org.jacoco.doc/junitstyle/junit-noframes.xsl
+++ b/org.jacoco.doc/junitstyle/junit-noframes.xsl
@@ -139,9 +139,8 @@
                     <!-- match the testsuites of this package -->
                     <xsl:apply-templates select="/testsuites/testsuite[./@package = current()/@package]" mode="print.test"/>
                 </table>
-                <a href="#top">Back to top</a>
-                <p/>
                 <p/>
+                <a href="#top">Back to top</a>
         </xsl:for-each>
     </xsl:template>
 
@@ -166,7 +165,6 @@
                 <xsl:apply-templates select="./testcase" mode="print.test"/>
             </table>
             <p/>
-
             <a href="#top">Back to top</a>
         </xsl:for-each>
     </xsl:template>
author	Marc R. Hoffmann <hoffmann@mountainminds.com>	2009-10-02 13:28:46 +0000
committer	Marc R. Hoffmann <hoffmann@mountainminds.com>	2009-10-02 13:28:46 +0000
commit	c4b2078689a7dbdc27c10ca4938c27fc01e64f22 (patch)
tree	04b35b943ff6c82f997f7738935d4374c6d5a9b0 /org.jacoco.doc
parent	5d43ad44e9f73cab0e8fd18b3143036a2f23e6cf (diff)
download	jacoco-c4b2078689a7dbdc27c10ca4938c27fc01e64f22.tar.gz