RFR: 8276700: Improve java.lang.ref.Cleaner javadocs

[Mandy Chung]

On Mon, 8 Nov 2021 13:27:17 GMT, Hendrik Schreiber <hschreiber at openjdk.org> wrote:

>> src/java.base/share/classes/java/lang/ref/Cleaner.java line 93:
>> 
>>> 91:  *
>>> 92:  *        // Static state class, capturing information necessary for
>>> 93:  *        // cleanup, but no reference to the instance being cleaned
>> 
>> Suggestion:
>> 
>>  *        // State class captures information necessary for cleanup.
>>  *        // It must hold no reference to the instance being cleaned
>>  *        // and therefore it is a static inner class in this CleaningExample.
>> 
>> 
>> Would this be clearer?
>
> I don't believe so. `no reference to the instance being cleaned` is the essential part (to me).

This is what I suggested and makes it clear that *must hold no reference to the instance being cleaned*.  Maybe you didn't notice it's still there? 
 

 *        // State class captures information necessary for cleanup.
 *        // It must hold no reference to the instance being cleaned
 *        // and therefore it is a static inner class in this CleaningExample
 ```

-------------

PR: https://git.openjdk.java.net/jdk/pull/6076