On Thu, 22 Feb 2024 23:14:37 GMT, Brent Christian <bchri...@openjdk.org> 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