pmd-doc: Add test case for renamed rules

Uses the pattern documented in rule deprecation policy.
The rule reference should be deprecated to get a deprecation
warning, if it is still used.

pmd-doc/src/test/resources/expected/java.md

@@ -15,7 +15,10 @@ folder: pmd/rules
 *   [JumbledIncrementer](pmd_rules_java_sample.html#jumbledincrementer): Avoid jumbled loop incrementers - its usually a mistake, and is confusing even if intentional.
 *   [MovedRule](pmd_rules_java_sample.html#movedrule): <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f; font-size: 75%;">Deprecated</span> The rule has been moved to another ruleset. Use instead [JumbledIncrementer](pmd_rules_java_sample2.html#jumbledincrementer).
 *   [OverrideBothEqualsAndHashcode](pmd_rules_java_sample.html#overridebothequalsandhashcode): Override both 'public boolean Object.equals(Object other)', and 'public int Object.hashCode()', o...
-*   [RenamedRule](pmd_rules_java_sample.html#renamedrule): <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f; font-size: 75%;">Deprecated</span> The rule has been renamed. Use instead [JumbledIncrementer](pmd_rules_java_sample.html#jumbledincrementer).
+*   [RenamedRule1](pmd_rules_java_sample.html#renamedrule1): <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f; font-size: 75%;">Deprecated</span> The rule has been renamed. Use instead [JumbledIncrementer](pmd_rules_java_sample.html#jumbledincrementer).
+*   [RenamedRule2](pmd_rules_java_sample.html#renamedrule2): <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f; font-size: 75%;">Deprecated</span> The rule has been renamed. Use instead [JumbledIncrementer](pmd_rules_java_sample.html#jumbledincrementer).
+*   [RenamedRule3](pmd_rules_java_sample.html#renamedrule3): <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f; font-size: 75%;">Deprecated</span> The rule has been renamed. Use instead [JumbledIncrementer](pmd_rules_java_sample.html#jumbledincrementer).
+*   [RenamedRule4](pmd_rules_java_sample.html#renamedrule4): <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f; font-size: 75%;">Deprecated</span> The rule has been renamed. Use instead [JumbledIncrementer](pmd_rules_java_sample.html#jumbledincrementer).
 *   [XSSInDocumentation](pmd_rules_java_sample.html#xssindocumentation): &lt;script&gt;alert('XSS at the beginning');&lt;/script&gt; HTML tags might appear at various places.        ...
 
 ## Additional rulesets

pmd-doc/src/test/resources/expected/sample.md

@@ -5,7 +5,7 @@ permalink: pmd_rules_java_sample.html
 folder: pmd/rules/java
 sidebaractiveurl: /pmd_rules_java.html
 editmepath: ../rulesets/ruledoctest/sample.xml
-keywords: Sample, XSSInDocumentation, OverrideBothEqualsAndHashcode, JumbledIncrementer, DeprecatedSample, RenamedRule, MovedRule
+keywords: Sample, XSSInDocumentation, OverrideBothEqualsAndHashcode, JumbledIncrementer, DeprecatedSample, RenamedRule1, RenamedRule2, RenamedRule3, RenamedRule4, MovedRule
 language: Java
 ---
 <!-- DO NOT EDIT THIS FILE. This file is generated from file ../rulesets/ruledoctest/sample.xml. -->
@@ -204,7 +204,7 @@ public class Foo {
 <rule ref="category/java/sample.xml/OverrideBothEqualsAndHashcode" />
 ```
 
-## RenamedRule
+## RenamedRule1
 
 <span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span> 
 
@@ -257,12 +257,235 @@ Avoid jumbled loop incrementers - its usually a mistake, and is confusing even i
 
 **Use this rule with the default properties by just referencing it:**
 ``` xml
-<rule ref="category/java/sample.xml/RenamedRule" />
+<rule ref="category/java/sample.xml/RenamedRule1" />
 ```
 
 **Use this rule and customize it:**
 ``` xml
-<rule ref="category/java/sample.xml/RenamedRule">
+<rule ref="category/java/sample.xml/RenamedRule1">
+    <properties>
+        <property name="sampleAdditionalProperty" value="the value" />
+        <property name="sampleMultiStringProperty" value="Value1|Value2" />
+        <property name="sampleRegexProperty1" value="\/\*\s+(default|package)\s+\*\/" />
+        <property name="sampleRegexProperty2" value="[a-z]*" />
+        <property name="sampleRegexProperty3" value="\s+" />
+        <property name="sampleRegexProperty4" value="_dd_" />
+        <property name="sampleRegexProperty5" value="[0-9]{1,3}" />
+        <property name="sampleRegexProperty6" value="\b" />
+        <property name="sampleRegexProperty7" value="\n" />
+    </properties>
+</rule>
+```
+
+## RenamedRule2
+
+<span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span> 
+
+This rule has been renamed. Use instead: [JumbledIncrementer](#jumbledincrementer)
+
+**Since:** PMD 1.0
+
+**Priority:** Medium (3)
+
+Avoid jumbled loop incrementers - its usually a mistake, and is confusing even if intentional.
+
+**This rule is defined by the following XPath expression:**
+``` xpath
+//ForStatement
+ [
+  ForUpdate/StatementExpressionList/StatementExpression/PostfixExpression/PrimaryExpression/PrimaryPrefix/Name/@Image
+  =
+  ancestor::ForStatement/ForInit//VariableDeclaratorId/@Image
+ ]
+```
+
+**Example(s):**
+
+``` java
+{%raw%}public class JumbledIncrementerRule1 {
+    public void foo() {
+        for (int i = 0; i < 10; i++) {          // only references 'i'
+            for (int k = 0; k < 20; i++) {      // references both 'i' and 'k'
+                System.out.println("Hello");
+            }
+        }
+    }
+}{%endraw%}
+```
+
+**This rule has the following properties:**
+
+|Name|Default Value|Description|Multivalued|
+|----|-------------|-----------|-----------|
+|sampleAdditionalProperty|the value|This is a additional property for tests|no|
+|sampleMultiStringProperty|Value1 \| Value2|Test property with multiple strings|yes. Delimiter is '\|'.|
+|sampleDeprecatedProperty|test|<span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f; font-size: 75%;">Deprecated</span>  This is a sample deprecated property for tests|no|
+|sampleRegexProperty1|\\/\\\*\\s+(default\|package)\\s+\\\*\\/|The property is of type regex|no|
+|sampleRegexProperty2|\[a-z\]\*|The property is of type regex|no|
+|sampleRegexProperty3|\\s+|The property is of type regex|no|
+|sampleRegexProperty4|\_dd\_|The property is of type regex|no|
+|sampleRegexProperty5|\[0-9\]{1,3}|The property is of type regex|no|
+|sampleRegexProperty6|\\b|The property is of type regex|no|
+|sampleRegexProperty7|\\n|The property is of type regex|no|
+
+**Use this rule with the default properties by just referencing it:**
+``` xml
+<rule ref="category/java/sample.xml/RenamedRule2" />
+```
+
+**Use this rule and customize it:**
+``` xml
+<rule ref="category/java/sample.xml/RenamedRule2">
+    <properties>
+        <property name="sampleAdditionalProperty" value="the value" />
+        <property name="sampleMultiStringProperty" value="Value1|Value2" />
+        <property name="sampleRegexProperty1" value="\/\*\s+(default|package)\s+\*\/" />
+        <property name="sampleRegexProperty2" value="[a-z]*" />
+        <property name="sampleRegexProperty3" value="\s+" />
+        <property name="sampleRegexProperty4" value="_dd_" />
+        <property name="sampleRegexProperty5" value="[0-9]{1,3}" />
+        <property name="sampleRegexProperty6" value="\b" />
+        <property name="sampleRegexProperty7" value="\n" />
+    </properties>
+</rule>
+```
+
+## RenamedRule3
+
+<span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span> 
+
+This rule has been renamed. Use instead: [JumbledIncrementer](#jumbledincrementer)
+
+<span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span> 
+
+**Since:** PMD 1.0
+
+**Priority:** Medium (3)
+
+Avoid jumbled loop incrementers - its usually a mistake, and is confusing even if intentional.
+
+**This rule is defined by the following XPath expression:**
+``` xpath
+//ForStatement
+ [
+  ForUpdate/StatementExpressionList/StatementExpression/PostfixExpression/PrimaryExpression/PrimaryPrefix/Name/@Image
+  =
+  ancestor::ForStatement/ForInit//VariableDeclaratorId/@Image
+ ]
+```
+
+**Example(s):**
+
+``` java
+{%raw%}public class JumbledIncrementerRule1 {
+    public void foo() {
+        for (int i = 0; i < 10; i++) {          // only references 'i'
+            for (int k = 0; k < 20; i++) {      // references both 'i' and 'k'
+                System.out.println("Hello");
+            }
+        }
+    }
+}{%endraw%}
+```
+
+**This rule has the following properties:**
+
+|Name|Default Value|Description|Multivalued|
+|----|-------------|-----------|-----------|
+|sampleAdditionalProperty|the value|This is a additional property for tests|no|
+|sampleMultiStringProperty|Value1 \| Value2|Test property with multiple strings|yes. Delimiter is '\|'.|
+|sampleDeprecatedProperty|test|<span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f; font-size: 75%;">Deprecated</span>  This is a sample deprecated property for tests|no|
+|sampleRegexProperty1|\\/\\\*\\s+(default\|package)\\s+\\\*\\/|The property is of type regex|no|
+|sampleRegexProperty2|\[a-z\]\*|The property is of type regex|no|
+|sampleRegexProperty3|\\s+|The property is of type regex|no|
+|sampleRegexProperty4|\_dd\_|The property is of type regex|no|
+|sampleRegexProperty5|\[0-9\]{1,3}|The property is of type regex|no|
+|sampleRegexProperty6|\\b|The property is of type regex|no|
+|sampleRegexProperty7|\\n|The property is of type regex|no|
+
+**Use this rule with the default properties by just referencing it:**
+``` xml
+<rule ref="category/java/sample.xml/RenamedRule3" />
+```
+
+**Use this rule and customize it:**
+``` xml
+<rule ref="category/java/sample.xml/RenamedRule3">
+    <properties>
+        <property name="sampleAdditionalProperty" value="the value" />
+        <property name="sampleMultiStringProperty" value="Value1|Value2" />
+        <property name="sampleRegexProperty1" value="\/\*\s+(default|package)\s+\*\/" />
+        <property name="sampleRegexProperty2" value="[a-z]*" />
+        <property name="sampleRegexProperty3" value="\s+" />
+        <property name="sampleRegexProperty4" value="_dd_" />
+        <property name="sampleRegexProperty5" value="[0-9]{1,3}" />
+        <property name="sampleRegexProperty6" value="\b" />
+        <property name="sampleRegexProperty7" value="\n" />
+    </properties>
+</rule>
+```
+
+## RenamedRule4
+
+<span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span> 
+
+This rule has been renamed. Use instead: [JumbledIncrementer](#jumbledincrementer)
+
+<span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span> 
+
+**Since:** PMD 1.0
+
+**Priority:** Medium (3)
+
+Avoid jumbled loop incrementers - its usually a mistake, and is confusing even if intentional.
+
+**This rule is defined by the following XPath expression:**
+``` xpath
+//ForStatement
+ [
+  ForUpdate/StatementExpressionList/StatementExpression/PostfixExpression/PrimaryExpression/PrimaryPrefix/Name/@Image
+  =
+  ancestor::ForStatement/ForInit//VariableDeclaratorId/@Image
+ ]
+```
+
+**Example(s):**
+
+``` java
+{%raw%}public class JumbledIncrementerRule1 {
+    public void foo() {
+        for (int i = 0; i < 10; i++) {          // only references 'i'
+            for (int k = 0; k < 20; i++) {      // references both 'i' and 'k'
+                System.out.println("Hello");
+            }
+        }
+    }
+}{%endraw%}
+```
+
+**This rule has the following properties:**
+
+|Name|Default Value|Description|Multivalued|
+|----|-------------|-----------|-----------|
+|sampleAdditionalProperty|the value|This is a additional property for tests|no|
+|sampleMultiStringProperty|Value1 \| Value2|Test property with multiple strings|yes. Delimiter is '\|'.|
+|sampleDeprecatedProperty|test|<span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f; font-size: 75%;">Deprecated</span>  This is a sample deprecated property for tests|no|
+|sampleRegexProperty1|\\/\\\*\\s+(default\|package)\\s+\\\*\\/|The property is of type regex|no|
+|sampleRegexProperty2|\[a-z\]\*|The property is of type regex|no|
+|sampleRegexProperty3|\\s+|The property is of type regex|no|
+|sampleRegexProperty4|\_dd\_|The property is of type regex|no|
+|sampleRegexProperty5|\[0-9\]{1,3}|The property is of type regex|no|
+|sampleRegexProperty6|\\b|The property is of type regex|no|
+|sampleRegexProperty7|\\n|The property is of type regex|no|
+
+**Use this rule with the default properties by just referencing it:**
+``` xml
+<rule ref="category/java/sample.xml/RenamedRule4" />
+```
+
+**Use this rule and customize it:**
+``` xml
+<rule ref="category/java/sample.xml/RenamedRule4">
     <properties>
         <property name="sampleAdditionalProperty" value="the value" />
         <property name="sampleMultiStringProperty" value="Value1|Value2" />

pmd-doc/src/test/resources/rulesets/ruledoctest/sample.xml

@@ -216,8 +216,18 @@ RuleTag with full category and without quotes: Use {% rule java/sample/RenamedRu
  </properties>
  </rule>
 
-<rule name="RenamedRule" ref="JumbledIncrementer"/>
+    <rule name="RenamedRule1" ref="JumbledIncrementer"/>
 
-<rule name="MovedRule" ref="rulesets/ruledoctest/sample2.xml/JumbledIncrementer"/>
+    <rule name="RenamedRule2" ref="rulesets/ruledoctest/sample.xml/JumbledIncrementer"/>
+
+    <!-- variant 1 of a renamed rule. This is definitively within the same ruleset. -->
+    <rule name="RenamedRule3" ref="JumbledIncrementer" deprecated="true" />
+
+    <!-- see Rule deprecation policy: /docs/pages/pmd/devdocs/rule_deprecation.md -->
+    <!-- variant 2 of a renamed and/or moved rule. This could also keep the rule name but
+         move the rule into a different rule or do any combination of both -->
+    <rule name="RenamedRule4" ref="rulesets/ruledoctest/sample.xml/JumbledIncrementer" deprecated="true" />
+
+    <rule name="MovedRule" ref="rulesets/ruledoctest/sample2.xml/JumbledIncrementer"/>
 
 </ruleset>