On 20/10/2020 12:40 pm, Kim Barrett wrote:
On Oct 19, 2020, at 7:20 PM, Mandy Chung <mch...@openjdk.java.net> wrote:
On Mon, 19 Oct 2020 23:10:23 GMT, Mandy Chung <mch...@openjdk.org> wrote:
Looks good.
That's the crux of it: what exactly is meant by "the referent"? Does it
mean the original object that was used as the referent, or does it mean
the current value of the "referent" field inside the Reference (as get
might return)?
"the referent" is the object a `Reference` object refers to.
as it's described in java.lang.ref package description:
Each reference-object type is implemented by a subclass of the abstract base
Reference class. An instance of one of
these subclasses encapsulates a single reference to a particular object, called
the referent.
See also `@return` in `Reference::get`:
@return The object to which this reference refers, or null if this reference
object has been cleared
In light of David's comments, I now think get's @return text is inconsistent
with the rest of get's description, which starts off with
* Returns this reference object's referent.
That seems definitional to me. It then goes on to say
* If this reference object has
* been cleared, either by the program or by the garbage collector, then
* this method returns {@code null}.
which is just noting that the referent is null after clearing.
But the @return seems to be suggesting some distinction between the referent
and the post-clear result of calling get. If there is such a distinction
then the first sentence of the description is factually false. I think this
would be improved by changing "or" to "which is" in the @return description.
I also personally prefer to use the "refers to" wording in the specification as
well (IIRC I suggested that wordings).
What about:
* Tests if this reference object refers to {@code obj}.
* If {@code obj} is {@code null}, this method returns {@code true} if
* this reference object was constructed with a {@code null} referent
* or has been cleared.
and
@return {@code true} if {@code obj} is the object to which this reference
refers,
or if {@code obj} is {@code null} and this reference has been
cleared.
I think the @param description of refersTo has the same problem. I don't
think there's any need to mention null at all in the description of
refersTo. I originally thought, and still think, the following is sufficient
and accurate, (esp. with the above wording tweak for get's @return text).
/**
* Tests if the referent of this reference object is {@code obj}.
*
* @param obj the object to compare with this reference object's referent
* @return {@code true} if {@code obj} is the referent of this reference object
* @since 16
*/
Mandy asked for additional discussion around null, but I've come around to
agreeing the current text isn't ideal. Rather than just rewording the
current @return text though, how about this:
/**
* Tests if the referent of this reference object is {@code obj}.
* Using a {@code null} {@code obj} allows detection of a reference that
* has been cleared, if it initially had some other referent value.
*
* @param obj the object to compare with this reference object's referent
* @return {@code true} if {@code obj} is the referent of this reference object
* @since 16
*/
I'm okay with that version too. Like Mandy I think the "if it initially
..." can be dropped.
Thanks,
David
-----
