On Dec 3, 2015, at 1:14 PM, Peter Levart <peter.lev...@gmail.com> wrote: > > On 12/03/2015 06:01 PM, Mandy Chung wrote: >>> On Dec 3, 2015, at 5:01 AM, Peter Levart <peter.lev...@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. […] >> >> * <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. >> > > Or: > > ..., so they are only useful if they are registered with a queue.
Drawing on the various suggestions so far, how about this: ----- Soft, weak, and phantom 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 access to the referent before they are cleared, and hence need not be registered with a queue in order to be useful. Phantom references, by contrast, prevent access to the referent, so they are only useful when registered with a queue. ----- I prefer the explicit list in the opening sentence, rather than collapsing that to just "References", to avoid any possible confusion that this might apply to (the internal and undocumented, but visible in the code) FinalReference. I included a serial comma in the list; I generally prefer that usage, and it's consistent with earlier usage on the same page. In the final sentence, I prefer to avoid the use of "must", especially without any "to be useful" qualification, as that sounds like it might be a formal requirement, and that would be inconsistent with the PhantomReference constructor documentation. The second sentence (about soft and weak references) could be deleted, along with the "by contrast" phrase in the third, without loss of information. It does save the reader a bit of inference though. [Indeed, this whole section isn't strictly necessary; all of it can be inferred from information in other places.]
