Merge branch 'pr-4937'

docs/pages/release_notes.md

@@ -40,6 +40,7 @@ This is a {{ site.pmd.release_type }} release.
 * java-codestyle
   * [#4602](https://github.com/pmd/pmd/issues/4602): \[java] UnnecessaryImport: false positives with static imports
   * [#4785](https://github.com/pmd/pmd/issues/4785): \[java] False Positive: PMD Incorrectly report violation for UnnecessaryImport
+  * [#4779](https://github.com/pmd/pmd/issues/4779): \[java] Examples in documentation of MethodArgumentCanBeFinal do not trigger the rule
   * [#4881](https://github.com/pmd/pmd/issues/4881): \[java] ClassNamingConventions: interfaces are identified as abstract classes (regression in 7.0.0)
 * java-design
   * [#3694](https://github.com/pmd/pmd/issues/3694): \[java] SingularField ignores static variables

pmd-java/src/main/resources/category/java/codestyle.xml

@@ -1034,17 +1034,27 @@ public class MissingTheProperSuffix implements SessionBean {}   // non-standard
           class="net.sourceforge.pmd.lang.java.rule.codestyle.MethodArgumentCouldBeFinalRule"
           externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_codestyle.html#methodargumentcouldbefinal">
         <description>
-A method argument that is never re-assigned within the method can be declared final.
+            Reports method and constructor parameters that can be made final because they are never reassigned within the body of the method.
+
+            This rule ignores unused parameters so as not to overlap with the rule {% rule 'java/bestpractices/UnusedFormalParameter' %}.
+            It will also ignore the parameters of abstract methods.
         </description>
         <priority>3</priority>
         <example>
 <![CDATA[
-public void foo1 (String param) {       // do stuff with param never assigning it
-
-}
-
-public void foo2 (final String param) { // better, do stuff with param never assigning it
-
+class Foo {
+    // reported, parameter can be declared final
+    public String foo1(String param) {
+        return param;
+    }
+    // not reported, parameter is declared final
+    public String foo2(final String param) {
+        return param.trim();
+    }
+    // not reported because param is unused
+    public String unusedParam(String param) {
+        return "abc";
+    }
 }
 ]]>
         </example>