> On Dec 4, 2015, at 10:07 AM, Kim Barrett <kim.barr...@oracle.com> wrote: > > On Dec 3, 2015, at 6:04 PM, Mandy Chung <mandy.ch...@oracle.com> wrote: >> >>> [Indeed, this whole section isn't strictly necessary; all of it can be >>> inferred from information in other places.] >> >> Agree. This section is no longer necessary and maybe just remove it: > > I wasn't actually intending to suggest removal. It seems like there > is useful overview information to be had here, rather than requiring > readers to make not necessarily obvious inferences. My impression is > that readability is valued more highly than terseness in Java > documentation.
Actually I considered to remove it in the past but just tried to minimize the spec change. I believe one purpose of that section was intended to call out the difference that PhantomReference is not automatically-cleared that is no longer true. In addition it’s clearly mentioned in PhantomReference constructor. I don’t see the need for it in the package summary. The reader will look at the PhantomRefererence to use it.. "It is possible to create a phantom reference with a null queue, but such a reference is completely useless: Its get method will always return null and, since it does not have a queue, it will never be enqueued.” The puzzling part to me is why PhantomReference accepts null ReferenceQueue. I can’t evaluate how high of the source incompatibility risk if we fixed it but I may propose that in a future release until I have cycle. Mandy
