[ant] Improve documentation

Refs #4658

docs/pages/pmd/userdocs/cpd/cpd.md

@@ -333,8 +333,14 @@ For details, see [CPD Report Formats](pmd_userdocs_cpd_report_formats.html).
 Andy Glover wrote an Ant task for CPD; here's how to use it:
 
 ```xml
+<path id="pmd.classpath">
+    <fileset dir="/home/joe/pmd-bin-{{site.pmd.version}}/lib">
+        <include name="*.jar"/>
+    </fileset>
+</path>
+<taskdef name="cpd" classname="net.sourceforge.pmd.ant.CPDTask" classpathref="pmd.classpath" />
+
 <target name="cpd">
-    <taskdef name="cpd" classname="net.sourceforge.pmd.ant.CPDTask" />
     <cpd minimumTokenCount="100" outputFile="/home/tom/cpd.txt">
         <fileset dir="/home/tom/tmp/ant">
             <include name="**/*.java"/>

docs/pages/pmd/userdocs/tools/ant.md

@@ -181,7 +181,6 @@ automatically and the latest language version is used.
 `ruleset` nested element - another way to specify rulesets. You can specify multiple elements. Here's an example:
 
     <target name="pmd">
-        <taskdef name="pmd" classname="net.sourceforge.pmd.ant.PMDTask"/>
         <pmd>
             <ruleset>rulesets/java/quickstart.xml</ruleset>
             <ruleset>config/my-ruleset.xml</ruleset>
@@ -373,7 +372,6 @@ You can run pmd then with `ant pmd`.
 An HTML report with the "linkPrefix" and "linePrefix" properties:
 
     <target name="pmd">
-        <taskdef name="pmd" classname="net.sourceforge.pmd.ant.PMDTask"/>
         <pmd rulesetfiles="rulesets/java/quickstart.xml">
             <formatter type="html" toFile="pmd_report.html">
                 <param name="linkPrefix" value="https://maven.apache.org/plugins/maven-pmd-plugin/xref/"/>

pmd-ant/src/main/java/net/sourceforge/pmd/ant/CPDTask.java

@@ -40,20 +40,26 @@ import net.sourceforge.pmd.lang.LanguageRegistry;
  *
  * <p>Runs the CPD utility via ant. The ant task looks like this:</p>
  *
- * <pre>
+ * <pre>{@code
- * &lt;project name="CPDProj" default="main" basedir="."&gt;
+ *   <project name="CPDProject" default="main" basedir=".">
- *   &lt;taskdef name="cpd" classname="net.sourceforge.pmd.cpd.CPDTask" /&gt;
+ *     <path id="pmd.classpath">
- *   &lt;target name="main"&gt;
+ *         <fileset dir="/home/joe/pmd-bin-VERSION/lib">
- *     &lt;cpd encoding="UTF-16LE" language="java" ignoreIdentifiers="true"
+ *             <include name="*.jar"/>
- *          ignoreLiterals="true" ignoreAnnotations="true" minimumTokenCount="100"
+ *         </fileset>
- *          outputFile="c:\cpdrun.txt"&gt;
+ *     </path>
- *       &lt;fileset dir="/path/to/my/src"&gt;
+ *     <taskdef name="cpd" classname="net.sourceforge.pmd.ant.CPDTask" classpathref="pmd.classpath" />
- *         &lt;include name="*.java"/&gt;
+ *
- *       &lt;/fileset&gt;
+ *     <target name="main">
- *     &lt;/cpd&gt;
+ *       <cpd encoding="UTF-16LE" language="java" ignoreIdentifiers="true"
- *   &lt;/target&gt;
+ *            ignoreLiterals="true" ignoreAnnotations="true" minimumTokenCount="100"
- * &lt;/project&gt;
+ *            outputFile="c:\cpdrun.txt">
- * </pre>
+ *         <fileset dir="/path/to/my/src">
+ *           <include name="*.java"/>
+ *         </fileset>
+ *       </cpd>
+ *     </target>
+ *   </project>
+ * }</pre>
  *
  * <p>Required: minimumTokenCount, outputFile, and at least one file</p>
  */

pmd-ant/src/main/java/net/sourceforge/pmd/ant/PMDTask.java

@@ -24,6 +24,31 @@ import net.sourceforge.pmd.ant.internal.PMDTaskImpl;
 /**
  * PMD Ant task. Setters of this class are interpreted by Ant as properties
  * settable in the XML. This is therefore published API.
+ *
+ * <p>Runs PMD analysis via ant. The ant task looks like this:</p>
+ *
+ * <pre>{@code
+ *   <project name="PMDProject" default="main" basedir=".">
+ *     <path id="pmd.classpath">
+ *         <fileset dir="/home/joe/pmd-bin-VERSION/lib">
+ *             <include name="*.jar"/>
+ *         </fileset>
+ *     </path>
+ *     <taskdef name="pmd" classname="net.sourceforge.pmd.ant.PMDTask" classpathref="pmd.classpath" />
+ *
+ *     <target name="main">
+ *       <pmd>
+ *         <ruleset>rulesets/java/quickstart.xml</ruleset>
+ *         <ruleset>config/my-ruleset.xml</ruleset>
+ *         <fileset dir="/usr/local/j2sdk1.4.1_01/src/">
+ *             <include name="java/lang/*.java"/>
+ *         </fileset>
+ *       </pmd>
+ *     </target>
+ *   </project>
+ * }</pre>
+ *
+ * <p>Required: rulesetfiles/ruleset, fileset</p>
  */
 public class PMDTask extends Task {