<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
<head>
    <name>CoverageReport: GroboCoverage Ant Tasks</name>
    <doc-version>$Date: 2004/04/06 02:57:09 $</doc-version>
    <author>Matt Albrecht</author>
</head>
<body>

<P>
<link name="v2_antdoc">All Tasks</link>
</P>

<anttask name="coveragereport">
    <description>
    <i>deprecated - use <link name="v2_antdoc_grobo-report">grobo-report</link>
    instead.</i>
    <p>
    Generates an XML report describing all the coverage tallies for the
    classes that were logged during runtime execution.  The report combines
    the runtime coverage logs with the post-compilation generated data.  One
    report is created per analysis module.  Currently, this task supports
    all included channel outputs (<code>DirectoryChannelLoggerFactory</code>,
    <code>CacheDirChannelLoggerFactory</code>, and
    <code>MinDirChannelLoggerFactory</code>).
    </p>
    </description>
    
    <ant-nested-element name="simplestyle">
        <description>
         Generates one HTML file for each analysis module<special-text>,
         which look something like
         <link name="CoverageReport-LineCount">this</link></special-text>.
        </description>
        <ant-nested-element name="param">
            <description>
            Used to pass a parameter to the underlying XSL stylesheet.
            The usage is exactly like the <code>param</code> structure
            for the <ant-link href="CoreTasks/style.html">style</ant-link>
            Ant task.
            </description>
            <ant-parameter>
                <attribute>name</attribute>
                <description>Name of the XSL parameter</description>
                <required>Yes</required>
            </ant-parameter>
            <ant-parameter>
                <attribute>expression</attribute>
                <description>Text value to be placed into the param.</description>
                <required>Yes</required>
            </ant-parameter>
            <ant-parameter>
                <attribute>if</attribute>
                <description>The param will only pass if this property is
                set.</description>
                <required>No</required>
            </ant-parameter>
            <ant-parameter>
                <attribute>if</attribute>
                <description>The param will only pass unless this property is
                set.</description>
                <required>No</required>
            </ant-parameter>
        </ant-nested-element>
        <ant-parameter>
            <attribute>prefix</attribute>
            <description>The text to prepend all output HTML file names.
            The output name will look like
            <code><i>prefix</i>ModuleName<i>suffix</i></code>.  Default
            prefix is <code>CoverageReport-</code>.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>suffix</attribute>
            <description>The text to append to all output HTML file names.
            The output name will look like
            <code><i>prefix</i>ModuleName<i>suffix</i></code>.  Default
            prefix is <code>CoverageReport-</code>.  Default suffix is
            <code>.html</code>.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>destdir</attribute>
            <description>The output directory to place the HTML files.
            Default directory is <code>.</code>.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>removeEmpty</attribute>
            <description>A boolean value.  This describes whether the
            output report should remove all methods and classes that don't
            have any code attributed to them (such as interfaces and
            abstract methods).  Default is <code>false</code>.
            </description>
            <required>No</required>
        </ant-parameter>
    </ant-nested-element>
    
    <ant-nested-element name="sourcestyle">
        <description>
         Generates a JavaDoc-like collection of HTML files for all the
         analysis modules, linking the coverage reports to the source files.
         This report shows the contents of the source files and highlights
         whichever lines were not covered.
        </description>
        <ant-parameter>
            <attribute>title</attribute>
            <description>The title text to be placed on the top of every
            HTML file.  Default is <code>Summary Coverage Report</code>.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>srcdir</attribute>
            <description>Directory containing the source files.
            </description>
            <required>Yes</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>destdir</attribute>
            <description>The output directory to place the HTML files.
            Default directory is <code>.</code>.
            </description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>footertext</attribute>
            <description>Text to be put at the bottom of every
            center frame's page (default is an advertisement for
            GroboUtils).</description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>footerhref</attribute>
            <description>Link to have the <code>footertext</code>
            point to (default is an advertisement for GroboUtils).</description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>stylesheet</attribute>
            <description>Stylesheet file to use in replacement of
            the default.</description>
            <required>No</required>
        </ant-parameter>
        <ant-parameter>
            <attribute>removeEmpty</attribute>
            <description>A boolean value.  This describes whether the
            output report should remove all methods and classes that don't
            have any code attributed to them (such as interfaces and
            abstract methods).  Default is <code>false</code>.
            </description>
            <required>No</required>
        </ant-parameter>
    
        <ant-nested-element name="srcdir">
            <description>
            In addition to the <code>srcdir</code> attribute, you can include
            multiple source directories for searching.  The first directory
            containing the source file will be used in the report.
            </description>
            <ant-parameter>
                <attribute>name</attribute>
                <description>The name of the directory containing a
                source tree.
                </description>
                <required>Yes</required>
            </ant-parameter>
        </ant-nested-element>
    </ant-nested-element>

    <ant-parameter>
        <attribute>datadir</attribute>
        <description>The name of the directory to read the analysis module
        generated data from.  This same directory should be specified in the
        <tt>coveragepostcompiler</tt> task's <tt>datadir</tt> attribute as
        well.
        </description>
        <required>Yes</required>
    </ant-parameter>
    <ant-parameter>
        <attribute>logDir</attribute>
        <description>The name of the directory to read the log output
        generated from running the code.  This same directory should be
        specified in the <tt>grobocoverage.properties</tt> file.
        </description>
        <required>Yes</required>
    </ant-parameter>
    <ant-parameter>
        <attribute>outdir</attribute>
        <description>The name of the directory that will contain the generated
        XML documents.
        </description>
        <required>Yes</required>
    </ant-parameter>
    <ant-parameter>
        <attribute>reportfileprefix</attribute>
        <description>Text that will prepend each outputted XML document's
        file name (default is <tt>Coverage-</tt>).
        </description>
        <required>No</required>
    </ant-parameter>
    <ant-parameter>
        <attribute>reportfileextension</attribute>
        <description>Text that will append each outputted XML document's
        file name (default is <tt>.xml</tt>).
        </description>
        <required>No</required>
    </ant-parameter>
    <ant-parameter>
        <attribute>failonerror</attribute>
        <description>Boolean describing if an error in this task should cause
        the build to fail (default is <tt>false</tt>).
        </description>
        <required>No</required>
    </ant-parameter>
    <ant-example>
        <source>
&lt;coveragereport
        datadir="${dirs.test-output}/coverage-data"
        logdir="${dirs.test-output}/coverage-log"
        outdir="${dirs.test-output}"&gt;
&lt;/coveragereport&gt;
        </source>
        <description>
        The &lt;coveragereport&gt; task generates one <tt>.xml</tt> file
        for each analysis module that has data in the
        <tt>${dirs.test-output}/coverage-data</tt> directory, using the
        runtime log data found in the <tt>${dirs.test-output}/coverage-log</tt>
        directory.  It also places in the same directory an <tt>.xml</tt> file
        that contains all the analysis module data.
        </description>
    </ant-example>
    <ant-example>
        <source>
&lt;coveragereport
        datadir="${dirs.test-output}/coverage-data"
        logdir="${dirs.test-output}/coverage-log"
        outdir="${dirs.test-output}"&gt;
    &lt;simplestyle destdir="${dirs.test-output}" removeempty="true" /&gt;
    &lt;sourcestyle destdir="${dirs.test-output}/source-report"
        removeempty="true" srcdir="src"
        title="Summary Coverage Report of My Code"&gt;
        
        &lt;srcdir name="${dirs.temp}/generated-source-1" /&gt;
        &lt;srcdir name="${dirs.temp}/generated-source-2" /&gt;
    &lt;/sourcestyle&gt;
&lt;/coveragereport&gt;
        </source>
        <description>
        Same as above, but this also generates two human-readable reports.
        The first (simplestyle) generates one HTML file in the
        <tt>${dirs.test-output}</tt> directory for each analysis module
        XML report.  <special-text>The generated file will
        look something like <link name="CoverageReport-LineCount">this</link>.
        </special-text>
        <p>
        The second (sourcestyle) generates a directory hierarchy of framed
        HTML pages in the <tt>${dirs.test-output}/source-report</tt>
        directory.  It links the original Java source files into the HTML
        by looking in the directories <code>src</code>,
        <code>${dirs.temp}/generated-source-1</code>, and
        <code>${dirs.temp}/generated-source-2</code> for the source files
        corresponding to the covered class files, in that order.
        </p>
        </description>
    </ant-example>
</anttask>

<P>
<link name="v2_antdoc">All Tasks</link>
</P>

</body>
</document>

