From d1437323559ef906268e36a75a12001cf36ace58 Mon Sep 17 00:00:00 2001 From: Romain Pelisse Date: Mon, 11 Feb 2008 16:44:11 +0000 Subject: [PATCH] Fixing out of dated XPath Query, bug [1874313] Documentation bugs. Thanks to Dave Cronin for the report! git-svn-id: https://pmd.svn.sourceforge.net/svnroot/pmd/trunk@5756 51baf565-9d33-0410-a72c-fc3788e3496d --- pmd/etc/changelog.txt | 1 + pmd/xdocs/xpathruletutorial.xml | 38 +++++++++++++++++---------------- 2 files changed, 21 insertions(+), 18 deletions(-) diff --git a/pmd/etc/changelog.txt b/pmd/etc/changelog.txt index aa159a2600..b24b73593d 100644 --- a/pmd/etc/changelog.txt +++ b/pmd/etc/changelog.txt @@ -2,6 +2,7 @@ Fixed bug 1843273 - False - on SimplifyBooleanReturns Fixed bug 1848888 - Fixed false positive in UseEqualsToCompareStrings +Fixed bug 1874313 - Documentation bugs Fixed bug 1855409 - False + in EmptyMethodInAbstractClassShouldBeAbstract Fixed other false positives in EmptyMethodInAbstractClassShouldBeAbstract diff --git a/pmd/xdocs/xpathruletutorial.xml b/pmd/xdocs/xpathruletutorial.xml index 852df06e3a..90b7df191e 100644 --- a/pmd/xdocs/xpathruletutorial.xml +++ b/pmd/xdocs/xpathruletutorial.xml @@ -18,10 +18,10 @@ Writing PMD rules with XPath can be a bit easier than writing rules with Java co

-

From FOLDOC an AST is 'A data structure - representing something which has been parsed, often used as - a compiler or interpreter's internal representation of a - program while it is being optimised and from which code +

From FOLDOC an AST is 'A data structure + representing something which has been parsed, often used as + a compiler or interpreter's internal representation of a + program while it is being optimised and from which code generation is performed'.

In our context, this means that we basically have a tree representation @@ -29,12 +29,12 @@ Writing PMD rules with XPath can be a bit easier than writing rules with Java co And since it's conceptually similar to XML, it can be queried with XPath to find a pattern.

- +

PMD comes with a handy tool that you will love if you want to write an XPath rule. Designer, runnable from a script in bin/, is a very simple and useful utility for writing rules.

-

The basic steps involved in writing XPath rules are these: +

The basic steps involved in writing XPath rules are these:

  1. Write a simple Java example source snippet in Designer
  2. See the AST for the class you wrote
    3. @@ -72,7 +72,7 @@ Writing PMD rules with XPath can be a bit easier than writing rules with Java co declarations is, well, using the FieldDeclaration node. This expression matches only the two fields declared in the class:

    //FieldDeclaration -

    In a similar way, you can match only local variables with this +

    In a similar way, you can match only local variables with this expression

    //LocalVariableDeclaration

    With local variables we need to be more careful. Consider the @@ -82,18 +82,18 @@ Writing PMD rules with XPath can be a bit easier than writing rules with Java co final int one; int two; - { + { int a; } - } + } }]]> -

    Local variable declarations will match 'a', since it is a perfectly +

    Local variable declarations will match 'a', since it is a perfectly legal Java local variable. Now, a more interesting expression is - to match variables declared in a method, and not on an internal block, + to match variables declared in a method, and not on an internal block, nor in the class. Maybe you'll start with an expression like this:

    //MethodDeclaration//LocalVariableDeclaration

    You'll quickly see that all three local variables are matched. A possible - solution for this is to request that the parent of the local variable + solution for this is to request that the parent of the local variable declaration is the MethodDeclaration node:

    -

    Let's consider that we are writing rules for logger. Let's assume we +

    Let's consider that we are writing rules for logger. Let's assume we use the Java logging API and we want to find all classes that have more than one logger. The following expression returns all variable declarations whose type is 'Logger'.

    - -

    Finding a class with more than one logger is quite easy now. This + +

    Finding a class with more than one logger is quite easy now. This expression matches the classes we are looking for.

    - 1]]]> -

    But let's refine this expression a little bit more. Consider the + 1]]]> +

    But let's refine this expression a little bit more. Consider the following class:

    With this class we will only be matching one violation, when we probably would have wanted to produce two violations (one for each class). The following refined expression matches classes that contain more than one logger.

    - 1]]]> + 1]]]>

    Let's assume we have a Factory class, that could be always declared final. We'll search an xpath expression that matches all declarations of Factory and reports a violation if it is not declared final.