RFR: 8071507: (ref) Clear phantom reference as soft and weak references do

[Mandy Chung]

> On Dec 3, 2015, at 5:01 AM, Peter Levart <peter.levart at gmail.com> wrote:
> 
>  I would only rephrase this statement in package-info.java a bit:
> 
>  96  * Soft and weak references are automatically cleared by the collector
>  97  * before being added to the queues with which they are registered, if any,
>  98  * hence they need not be registered with a queue in order to be useful.
>  99  * Phantom references, by contrast, do not allow their referents to be
> 100  * retrieved, so they must be registered with a queue.

Kim brought up the potential confusion on the above wordings.  To me this is clear when I read it as a fresh reader (not comparing the before and after).  The confusion could be due to the section header “Automatically-cleared references”.  This paragraph talks about the need of registering references (soft/weak refs vs phantom refs).  I thought about (1) changing the section header to “Registering references”, or (2) a small rewording like this:

  * <h3>Automatically-cleared references</h3>
  *
- * Soft and weak references are automatically cleared by the collector
- * before being added to the queues with which they are registered, if
- * any.  Therefore soft and weak references need not be registered
- * with a queue in order to be useful, while phantom references do.
- * An object that is reachable via phantom references will remain so
- * until all such references are cleared or themselves become
- * unreachable.
+ * References are automatically cleared by the collector before being
+ * added to the queues with which they are registered, if any.
+ * Soft and weak references allow their referents to be retrieved,
+ * hence they need not be registered with a queue in order to be useful.
+ * Phantom references, by contrast, do not allow their referents to be
+ * retrieved, so they must be registered with a queue.

Mandy