Clarify violationSuppressXPath docs

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,
+violation node as the context node*.  If the XPath query matches anything,
-then the violation will be suppressed.
+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
 </rule>
 ```
 
+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
+<property name="violationSuppressXPath" value="./ancestor::ClassOrInterfaceDeclaration[contains(@Image, 'Bean')]"/>
+```
+
+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