On Thu, 22 Feb 2024 12:05:31 GMT, Daniel Jeliński <[email protected]> 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
