From 9af343b2a3f275058cf6b774afe56b4fa956d64c Mon Sep 17 00:00:00 2001
From: Tom Copeland <tomcopeland@users.sourceforge.net>
Date: Fri, 26 Jul 2002 16:19:43 +0000
Subject: [PATCH] tweak

git-svn-id: https://pmd.svn.sourceforge.net/svnroot/pmd/trunk@524 51baf565-9d33-0410-a72c-fc3788e3496d
---
 pmd/xdocs/howtowritearule.xml | 33 ++++++++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/pmd/xdocs/howtowritearule.xml b/pmd/xdocs/howtowritearule.xml
index cb68b62675..b8908de3d7 100644
--- a/pmd/xdocs/howtowritearule.xml
+++ b/pmd/xdocs/howtowritearule.xml
@@ -9,15 +9,20 @@
 <p>
 Writing PMD rules is cool because you don't have to wait for us to get around to implementing feature requests.
 </p>
-
+    <subsection name="Get a development environment set up first">
+    <p>
+    In order to do rules, it'll help if you can modify the PMD source.
+    So download the latest source release (i.e., pmd-src-0.7.zip or something) and unzip it somewhere on your computer.
+    </p>
+    </subsection>
     <subsection name="Figure out what you want to look for">
     <p>
-    First, figure out what you're looking for.  Let's use "While loops must use braces" as an example.
+    Now lets's figure out what problem you want to spot.  Let's use "While loops must use braces" as an example.
     You've seen this before a thousand times so you know what it looks like:
     </p>
     <source>
 <![CDATA[
-       public class Foo {
+       public class Example {
         public void bar() {
          while (baz)
             buz.doSomething();
@@ -25,12 +30,15 @@ Writing PMD rules is cool because you don't have to wait for us to get around to
        }
 ]]>
     </source>
+    <p>
+    So we know what an example in source code looks like, which is half the battle.
+    </p>
     </subsection>
 
     <subsection name="Write a test-data example and look at the AST">
     <p>
-    PMD uses a JJTree/JavaCC generated parser to parse the source code and produce an AST (Abstract Syntax Tree).
-    This means that the code above looks like this:
+    PMD doesn't use the source code directly; it uses a JJTree/JavaCC generated parser to parse the source code and
+    produce an AST (Abstract Syntax Tree).  The AST for the code above looks like this:
     </p>
     <source>
 <![CDATA[
@@ -76,6 +84,21 @@ CompilationUnit
                Arguments
 ]]>
     </source>
+    <p>
+    You can generate this yourself by:
+    <ul>
+    <li>Put the example file in the pmd/test-data directory in a file called "Example.java"</li>
+    <li>Edit the class <code>net.sourceforge.pmd.PMD</code> and uncomment the line that says <code>c.dump();</code></li>
+    <li>Open a command prompt and cd into the pmd/etc directory</li>
+    <li>Recompile the project using the Ant task; i.e., <code>ant compile</ant></li>
+    <li>Run the <code>go</code> batch file to run PMD on one file, like this: <code>go Example xml rulesets/basic.xml</code>.  The go.bat file
+    will fill in the directories and main class and whatnot.
+    You'll probably have to edit this batch file to match where you unzipped PMD.</li>
+    <li>If you get a ClassNotFoundException, make sure the pmd-?.?.jar file is on your classpath.</li>
+    <li>The rulesets need to be on there too - so make sure the pmd directory is on your classpath too.</li>
+    <li>If you get a FileNotFoundException, make sure that go.bat is pointing to the test-data directory where you put Example.java</li>
+    </ul>
+    </p>
 
     </subsection>