src/site/fml/faq.fml

<?xml version="1.0" encoding="UTF-8"?>

<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you 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.
-->


<faqs xmlns="http://maven.apache.org/FML/1.0.1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/FML/1.0.1 http://maven.apache.org/xsd/fml-1.0.1.xsd"
  id="FAQ" title="Frequently Asked Questions">
  <part id="General">
    <faq id="Is there any way to skip the PMD or CPD reports temporarily">
      <question>
        The PMD report takes a long time to generate. Is there any way to skip
        the PMD or CPD reports temporarily?
      </question>
      <answer>
        <p>
          Yes, each report supports a skip parameter which you can pass on the
          command line, <code>-Dpmd.skip=true</code> and
          <code>-Dcpd.skip=true</code> respectively.
        </p>
      </answer>
    </faq>
    <faq id="xref_links">
      <question>
        How can I generate links to the JXR cross-referenced source?
      </question>
      <answer>
        <p>
          First make sure that the <a href="pmd-mojo.html#linkXRef">linkXRef</a> parameter is configured
          correctly (it is switched on by default).
        </p>
        <p>
          Then, the jxr plugin has to run first so that the links can be picked up by the pmd report.
          If you run from the command line, use <code>mvn jxr:jxr pmd:pmd</code>, or if you want the
          reports generated by the site plugin, configure the jxr plugin in your reporting section, see
          <a href="http://maven.apache.org/plugins/maven-jxr-plugin/usage.html">JXR usage</a>.
        </p>
      </answer>
    </faq>
    <faq id="no report in site">
      <question>
        I have add the PMD/CPD reports, but they do not show up in the generated site. Has the plugin been executed?
      </question>
      <answer>
        <p>
          If there are no violations, then by default no reports are created and the entire PMD or CPD section
          is not rendered in the site. To change this behaviour, set the
          <a href="pmd-mojo.xml#skipEmptyReport">skipEmptyReport for PMD</a> or <a href="cpd-mojo#skipEmptyReport">skipEmptyReport for CPD</a>
          to <code>false</code>.
        </p>
      </answer>
    </faq>
    <faq id="violations failures warnings">
        <question>
          What's the difference between violations, failures and warnings and when is a build failing?
        </question>
        <answer>
          <p>
            PMD reports violations. These violations originate from rules - the rules, that are enabled in the
            configured ruleset (see property <a href="pmd-mojo.html#rulesets">rulesets</a>). Each rule has a assigned
            priority (1 - high, 2 - medium-high, 3 - medium, 4 - medium-low, 5 - low). This priority is also used
            for the violation.
          </p>
          <p>
            Violations with a high enough priority can fail the build when using the <a href="check-mojo.html">check</a> goal.
            These violations are called "failures". The exact priority, when to fail the build, is configured via the property
            <a href="check-mojo.html#failurePriority">failurePriority</a>.
          </p>
          <p>
            Violations, that have a priority too low to fail the build, are called "warnings". These warnings appear
            in the report and are displayed in the build output, if the property <a href="check-mojo.html#verbose">verbose</a>
            is enabled.
          </p>
          <p>
            With the property <a href="check-mojo.html#failOnViolation">failOnViolation</a> the build failure
            can be entirely disabled. This is most useful at command line with <code>-Dpmd.failOnViolation=false</code>.
          </p>
          <p>
            With the property <a href="check-mojo.html#maxAllowedViolations">maxAllowedViolations</a> one can configure
            how many failures are allowed, before the build is failed.
          </p>
        </answer>
    </faq>
    <faq id="typeresolution aggregate">
      <question>
        What does the warning "The project xyz does not seem to be compiled. PMD results might be inaccurate." mean?
      </question>
      <answer>
        <p>
          In order to improve PMD's results, type resolution should be used. It is enabled by default
          (property <a href="pmd-mojo.html#typeResolution">typeResolution</a>) and helps to avoid false positive
          findings by matching the exact types of method parameters or variables.
        </p>
        <p>
          However, this requires that the project is built first, so that not only the project's dependencies
          can be used for type resolution, but also the project's classes as well.
        </p>
        <p>
          When using the property <a href="pmd-mojo.html#aggregate">aggregate</a>, this is problematic: With
          aggregate=true, PMD is executed at the root of a multi-module project <em>before the individual
          modules are built</em>. Then the types of the individual projects are not available, which might lead to
          false positive findings e.g. for the rule "UnusedPrivateMethod".
          If this might be the case, then the warning "The project xyz does not seem
          to be compiled. PMD results might be inaccurate" is issued.
        </p>
        <p>
          In order to use type resolution and aggregate together, maven needs to be execute in two passes:
          First pass will compile the projects (e.g. <code>mvn clean package</code>) and the second pass
          will execute PMD without clean via the verify phase (e.g. <code>mvn verify</code>).
        </p>
      </answer>
    </faq>
  </part>
</faqs>