[java] Fix #4779 - Improve doc of MethodArgumentCanBeFinal

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/UnusedVariable' %}.
+            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>