From d9a441c7d6bd7b8bb67ec1e12dbaf80d3b74a253 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Fournier?= Date: Wed, 12 Jun 2019 18:38:25 +0200 Subject: [PATCH] Clarify violationSuppressXPath docs --- .../pmd/userdocs/suppressing_warnings.md | 22 +++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/docs/pages/pmd/userdocs/suppressing_warnings.md b/docs/pages/pmd/userdocs/suppressing_warnings.md index 20ab95452d..cf52782c0a 100644 --- a/docs/pages/pmd/userdocs/suppressing_warnings.md +++ b/docs/pages/pmd/userdocs/suppressing_warnings.md @@ -187,8 +187,13 @@ of no use. ### The property `violationSuppressXPath` This property defines an XPath query to be executed *using the -violation node as the starting point*. If the XPath query matches anything, -then the violation will be suppressed. +violation node as the context node*. If the XPath query matches anything, +then the violation will be suppressed. Note that the query shouldn't be finding +the violation nodes to suppress, but rather, finding a non-empty sequence of nodes +when evaluated with the violation node as a context node. + +The XPath version used by those queries is XPath 1.0, so it doesn't support e.g. +regex tests. This will be updated with PMD 7.0.0. For example, to suppress reporting specifically typed parameters which are unused: @@ -200,6 +205,19 @@ For example, to suppress reporting specifically typed parameters which are unuse ``` +Note the use of `.` to refer to the context node. Using `//` at the start of the +expression should be avoided, as it would test all nodes in the file, and suppress +more violations than expected. + +Another example, to suppress violations occurring in classes whose name contains `Bean`: +```xml + +``` + +Note here the used of the `./ancestor::` axis instead of `//`. The latter would match +any ClassOrInterfaceDeclaration in the file, while the former matches only class +declaration nodes that *enclose the violation node*, which is usually what you'd want. + Note for XPath based suppression to work, you must know how to write an XPath query that matches the AST structure of the nodes of the violations you wish to suppress. XPath queries are explained in