On Thu, 22 Feb 2024 23:14:37 GMT, Brent Christian <[email protected]> wrote:
>> I note that the adjective(s) (un)successful and the adverb(s)
>> (un)successfully are used at several places in these comments, it might
>> makes sense to use those terms here as well such that the documentation in
>> internally consistent in its use of success or failure of actions. In
>> particular, if this terminology is consistent with precedent in the official
>> JLS spec.
>>
>> However, I note that there are places where these terms are italicized and
>> places where they aren't. I am not sure I follow the convention for
>> italicization. In general, the first use (i.e. introduction) of a term that
>> the reader might want to pay attention to calls for italicization when
>> documents are read sequentially, such as in research papers. These javadoc
>> specs will usually not be read in sequentially. But considering that someone
>> does read them in order, I'd suggest italicizing only the first use of the
>> term or, if not, then perhaps none. Alternatively, you might want to
>> italicize all uses (but why?).
>
> Thanks for finding my misspelling, djelinski. đ
The use of "(un)successful(ly)" in relation to `Reference.enqueue()` is quite
deliberate (and builds on the previous wording, "successful").
The intention was to use it consistently (is that not the case somewhere?). For
example, it's also used in the new **Memory Consistency Properties** section of
the `java.lang.ref` package docs ("The enqueueing of a reference...by a
successful call to `Reference.enqueue()`...").
A "successful call to `enqueue()`" is meant to be shorthand for:
"the reference has been enqueued, and the enqueuing was performed by the
`enqueue()` method (rather than by the garbage collector). Therefore there is a
_happens-before_ edge between the `enqueue()` method call and the dequeuing of
the Reference (whereas there would not be this _happens-before_ if the GC had
already enqueued the Reference at the time of the `enqueue()` call)."
The text emphasis with italics is to indicate this added significance of the
result of the `enqueue()` call -- ala `happens-before`.
I'm not aware of a similar scenario covered in the JLS, so AFAIK there is not
precedent to be consistent with in that regard.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/16644#discussion_r1500073141
