SONARJAVA-5504 Documentation to explain the behavior of the UnusedLocalVariableCheck in unresolved variable cases (#5097)

Author: romainbrenguier

java-checks/src/main/java/org/sonar/java/checks/helpers/UnresolvedIdentifiersVisitor.java

@@ -29,7 +29,7 @@
 
 public class UnresolvedIdentifiersVisitor extends BaseTreeVisitor {
 
-  private Set<String> unresolvedIdentifierNames = new HashSet<>();
+  private final Set<String> unresolvedIdentifierNames = new HashSet<>();
 
   @Override
   public void visitMemberSelectExpression(MemberSelectExpressionTree tree) {
@@ -72,6 +72,7 @@ private Set<String> unresolvedNames() {
     return Collections.unmodifiableSet(unresolvedIdentifierNames);
   }
 
+  /** Returns whether an identifier with the same name as the candidate is unresolved. */
   public boolean isUnresolved(String candidate) {
     return unresolvedIdentifierNames.contains(candidate);
   }

java-checks/src/main/java/org/sonar/java/checks/unused/UnusedLocalVariableCheck.java

@@ -74,6 +74,7 @@ public void leaveNode(Tree tree) {
       VariableTree variable = (VariableTree) tree;
       IdentifierTree simpleName = variable.simpleName();
       if (!simpleName.isUnnamedVariable()) {
+        // If a variable with the same name as this is unresolved, we can't be sure it's not a usage of this. So we can't raise an issue.
         boolean unresolved = UNRESOLVED_IDENTIFIERS_AND_SWITCH_CASE_VISITOR.isUnresolved(simpleName.name());
         if (!unresolved && isProperLocalVariable(variable) && isUnused(variable.symbol()) && canBeReplaced(variable)) {
           QuickFixHelper.newIssue(context)