From 78c43ed87a232e2305891a0c795724708867c7a8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Fournier?= <clement.fournier@tu-dresden.de>
Date: Sat, 6 Apr 2024 16:56:25 +0200
Subject: [PATCH] [java] Fix #4779 - Improve doc of MethodArgumentCanBeFinal

---
 .../resources/category/java/codestyle.xml     | 24 +++++++++++++------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/pmd-java/src/main/resources/category/java/codestyle.xml b/pmd-java/src/main/resources/category/java/codestyle.xml
index 01b868afa7..867b911ed8 100644
--- a/pmd-java/src/main/resources/category/java/codestyle.xml
+++ b/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>