[java] SingletonClassReturningNewInstance behaving differently from documentation

Affects PMD Version: 7.15.0

Rule: SingletonClassReturningNewInstance

Please provide the rule name and a link to the rule documentation: SingletonClassReturningNewInstance

Description: The rule description particularly mentions "Failure to check whether an instance has already been created" as the criteria for this rule. However, the following code clearly does not check the existence of an instance and always creates a new object, yet, it is not detected.

The given example in the documentation mentions not storing the new Singleton() to the instance variable and directly returning it (i.e., doing return new Singleton() will raise the flag). But if the rule only detects whether the new Singleton() is stored in the instance variable, the rule documentation should be updated to remove "Failure to check whether an instance has already been created" part and make it explicit that the rule only checks if the new Singleton() is stored in instance. Otherwise, the following code should raise a flag.

Code Sample demonstrating the issue:

class Singleton {
    private static Singleton instance = null;

    private Singleton() {}

    public static Singleton getInstance() {
        synchronized(Singleton.class) {
            instance = new Singleton();
            return instance;
        }
    }

    public static void showBug() {
        Singleton instance1 = Singleton.getInstance();
        Singleton instance2 = Singleton.getInstance();
        System.out.println("Are instances equal? " + (instance1 == instance2));
    }
}

Expected outcome:

PMD should report a violation at line 6, but doesn't. This is a false-negative.
Otherwise, a clearer description of the rule in the documentation.

Running PMD through: [CLI]

Start with the SingletonClassReturningNewInstance rule documentation and reproduce the supplied Java example through the CLI. Determine whether the intended fix is to report reassignment of a new instance or to clarify the documented detection criteria; done means the behavior and documentation agree, with coverage for the example if the rule behavior changes.