<!--
  ~ Copyright 2009 the original author or authors.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~      http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->
<chapter id="code_quality_plugin">
    <title>The Code Quality Plugin</title>

    <para>The code quality plugin adds tasks which perform code quality checks and generate reports from these checks.
        The following tools are supported:
        <itemizedlist>
            <listitem><para><ulink url="http://checkstyle.sourceforge.net/index.html">Checkstyle</ulink></para></listitem>
            <listitem><para><ulink url="http://codenarc.sourceforge.net/index.html">CodeNarc</ulink></para></listitem>
        </itemizedlist>
    </para>

    <section>
        <title>Usage</title>
        <para>To use the code quality plugin, include in your build script:</para>
        <sample id="useCodeQualityPlugin" dir="codeQuality" title="Using the code quality plugin">
            <sourcefile file="build.gradle" snippet="use-plugin"/>
        </sample>
    </section>

    <section>
        <title>Tasks</title>
        <para>When used with the Java plugin, the code quality plugin adds the following tasks to the project:</para>
        <table>
            <title>Code quality plugin - Java tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>checkstyleMain</literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.plugins.quality.Checkstyle"/></td>
                <td>Runs Checkstyle against the production Java source files.</td>
            </tr>
            <tr>
                <td>
                    <literal>checkstyleTest</literal>
                </td>
                <td><literal>compile</literal></td>
                <td><apilink class="org.gradle.api.plugins.quality.Checkstyle"/></td>
                <td>Runs Checkstyle against the test Java source files.</td>
            </tr>
            <tr>
                <td>
                    <literal>checkstyle<replaceable>SourceSet</replaceable></literal>
                </td>
                <td>-</td>
                <td><apilink class="org.gradle.api.plugins.quality.Checkstyle"/></td>
                <td>Runs Checkstyle against the given source set's Java source files.</td>
            </tr>
        </table>

        <para>When used with the Groovy plugin, the code quality plugin adds the following tasks to the project:</para>

        <table>
            <title>Code quality plugin - tasks</title>
            <thead>
                <tr>
                    <td>Task name</td>
                    <td>Depends on</td>
                    <td>Type</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>codenarcMain</td>
                <td>-</td>
                <td><apilink class="org.gradle.api.plugins.quality.CodeNarc"/></td>
                <td>Runs CodeNarc against the production Groovy source files.</td>
            </tr>
            <tr>
                <td>codenarcTest</td>
                <td>-</td>
                <td><apilink class="org.gradle.api.plugins.quality.CodeNarc"/></td>
                <td>Runs CodeNarc against the test Groovy source files.</td>
            </tr>
            <tr>
                <td>codenarc<replaceable>SourceSet</replaceable></td>
                <td>-</td>
                <td><apilink class="org.gradle.api.plugins.quality.CodeNarc"/></td>
                <td>Runs CodeNarc against the given source set's Groovy source files.</td>
            </tr>
        </table>
        <para>The Code quality plugin adds the following dependencies to tasks added by the Java plugin.</para>
        <table>
            <title>Code quality plugin - additional task dependencies</title>
            <thead>
                <td>Task name</td>
                <td>Depends on</td>
            </thead>
            <tr>
                <td>check</td>
                <td>All Checkstyle and CodeNarc tasks, including <literal>checkstyleMain</literal>,
                    <literal>checkstyleTest</literal>,
                    <literal>codenarcMain</literal> and
                    <literal>codenarcTest</literal>
                </td>
            </tr>
        </table>
        <figure>
            <title>Code quality plugin - tasks</title>
            <imageobject>
                <imagedata fileref="img/codeQualityPluginTasks.png"/>
            </imageobject>
        </figure>
    </section>

    <section>
        <title>Project layout</title>
        <para>The code quality plugin expects the following project layout:</para>
        <table>
            <title>Code quality plugin - project layout</title>
            <thead>
                <tr>
                    <td>File</td>
                    <td>Meaning</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <filename>config/checkstyle/checkstyle.xml</filename>
                </td>
                <td>Checkstyle configuration file</td>
            </tr>
            <tr>
                <td>
                    <filename>config/codenarc/codenarc.xml</filename>
                </td>
                <td>CodeNarc configuration file</td>
            </tr>
        </table>
    </section>

    <section>
        <title>Dependency management</title>
        <para>The code quality plugin does not add any dependency configurations.</para>
    </section>

    <section>
        <title>Convention properties</title>
        <para>When used with the Java plugin, the code quality plugin adds the following convention properties to the project:</para>
        <table>
            <title>Code quality plugin - convention properties</title>
            <thead>
                <tr>
                    <td>Property name</td>
                    <td>Type</td>
                    <td>Default value</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>checkstyleConfigFileName</literal>
                </td>
                <td>
                    <classname>String</classname>
                </td>
                <td>
                    <literal>config/checkstyle/checkstyle.xml</literal>
                </td>
                <td>
                    The location of the Checkstyle configuration file, relative to the project directory.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>checkstyleConfigFile</literal>
                </td>
                <td>
                    <classname>File</classname> (read-only)
                </td>
                <td>
                    <literal><replaceable>projectDir</replaceable>/<replaceable>checkstyleConfigFileName</replaceable></literal>
                </td>
                <td>
                    The Checkstyle configuration file.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>checkstyleResultsDirName</literal>
                </td>
                <td>
                    <classname>String</classname>
                </td>
                <td>
                    <literal>checkstyle</literal>
                </td>
                <td>
                    The name of the directory to generate Checkstyle results into, relative to the build directory.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>checkstyleResultsDir</literal>
                </td>
                <td>
                    <classname>File</classname> (read-only)
                </td>
                <td>
                    <literal><replaceable>buildDir</replaceable>/<replaceable>checkstyleResultsDirName</replaceable></literal>
                </td>
                <td>
                    The directory to generate Checkstyle results into.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>checkstyleProperties</literal>
                </td>
                <td>
                    <classname>Map</classname>
                </td>
                <td>
                    <literal>[:]</literal>
                </td>
                <td>
                    The properties to use when loading the Checkstyle configuration.
                </td>
            </tr>
        </table>

        <para>These convention properties are provided by a convention object of type
            <apilink class="org.gradle.api.plugins.quality.JavaCodeQualityPluginConvention"/>.</para>

        <para>When used with the Groovy plugin, the code quality plugin adds the following convention properties to the project:</para>

        <table>
            <title>Code quality plugin - convention properties</title>
            <thead>
                <tr>
                    <td>Property name</td>
                    <td>Type</td>
                    <td>Default value</td>
                    <td>Description</td>
                </tr>
            </thead>
            <tr>
                <td>
                    <literal>codeNarcConfigFileName</literal>
                </td>
                <td>
                    <classname>String</classname>
                </td>
                <td>
                    <literal>config/codenarc/codenarc.xml</literal>
                </td>
                <td>
                    The location of the CodeNarc configuration file, relative to the project directory.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>codeNarcConfigFile</literal>
                </td>
                <td>
                    <classname>File</classname> (read-only)
                </td>
                <td>
                    <literal><replaceable>projectDir</replaceable>/<replaceable>codeNarcConfigFileName</replaceable></literal>
                </td>
                <td>
                    The CodeNarc configuration file.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>codeNarcReportsDirName</literal>
                </td>
                <td>
                    <classname>String</classname>
                </td>
                <td>
                    <literal>codenarc</literal>
                </td>
                <td>
                    The name of the directory to generate CodeNarc reports into, relative to the reports directory.
                </td>
            </tr>
            <tr>
                <td>
                    <literal>codeNarcReportsDir</literal>
                </td>
                <td>
                    <classname>File</classname> (read-only)
                </td>
                <td>
                    <literal><replaceable>reportsDir</replaceable>/<replaceable>codeNarcReportsDirName</replaceable></literal>
                </td>
                <td>
                    The directory to generate CodeNarc reports into.
                </td>
            </tr>
        </table>

        <para>These convention properties are provided by a convention object of type
            <apilink class="org.gradle.api.plugins.quality.GroovyCodeQualityPluginConvention"/>.</para>
    </section>

</chapter>