RFR: 8314480: Memory ordering spec updates in java.lang.ref [v9]

[Y. Srinivas Ramakrishna]

On Thu, 22 Feb 2024 12:05:31 GMT, Daniel Jeliński <djelinski at openjdk.org> wrote:

>> src/java.base/share/classes/java/lang/ref/Reference.java line 491:
>> 
>>> 489:      * If this reference is not registered with a queue, or was already enqueued
>>> 490:      * (by the garbage collector, or a previous call to {@code enqueue}), this
>>> 491:      * method is <b><i>unnsuccessful</i></b> and returns false.
>> 
>> Suggestion:
>> 
>>      * method is <b><i>unsuccessful</i></b> and returns false.
>
> or, better yet, `fails`

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?).

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/16644#discussion_r1499714011