8302360: Atomic*.compareAndExchange Javadoc unclear

Reviewed-by: martin, dholmes

Author: viktorklang-ora

src/java.base/share/classes/java/lang/invoke/VarHandle.java

@@ -806,7 +806,7 @@ public boolean hasInvokeExactBehavior() {
      * {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)}
      * , statically represented using varargs.
      * @return {@code true} if successful, otherwise {@code false} if the
-     * witness value was not the same as the {@code expectedValue}.
+     * <em>witness value</em> was not the same as the {@code expectedValue}.
      * @throws UnsupportedOperationException if the access mode is unsupported
      * for this VarHandle.
      * @throws WrongMethodTypeException if the access mode type does not
@@ -839,7 +839,7 @@ public boolean hasInvokeExactBehavior() {
      * @param args the signature-polymorphic parameter list of the form
      * {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)}
      * , statically represented using varargs.
-     * @return the signature-polymorphic result that is the witness value, which
+     * @return the signature-polymorphic result that is the <em>witness value</em>, which
      * will be the same as the {@code expectedValue} if successful
      * , statically represented using {@code Object}.
      * @throws UnsupportedOperationException if the access mode is unsupported
@@ -874,7 +874,7 @@ public boolean hasInvokeExactBehavior() {
      * @param args the signature-polymorphic parameter list of the form
      * {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)}
      * , statically represented using varargs.
-     * @return the signature-polymorphic result that is the witness value, which
+     * @return the signature-polymorphic result that is the <em>witness value</em>, which
      * will be the same as the {@code expectedValue} if successful
      * , statically represented using {@code Object}.
      * @throws UnsupportedOperationException if the access mode is unsupported
@@ -909,7 +909,7 @@ public boolean hasInvokeExactBehavior() {
      * @param args the signature-polymorphic parameter list of the form
      * {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)}
      * , statically represented using varargs.
-     * @return the signature-polymorphic result that is the witness value, which
+     * @return the signature-polymorphic result that is the <em>witness value</em>, which
      * will be the same as the {@code expectedValue} if successful
      * , statically represented using {@code Object}.
      * @throws UnsupportedOperationException if the access mode is unsupported
@@ -936,7 +936,7 @@ public boolean hasInvokeExactBehavior() {
      * {@link #get}.
      *
      * <p>This operation may fail spuriously (typically, due to memory
-     * contention) even if the witness value does match the expected value.
+     * contention) even if the <em>witness value</em> does match the expected value.
      *
      * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)boolean}.
      *
@@ -949,7 +949,7 @@ public boolean hasInvokeExactBehavior() {
      * {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)}
      * , statically represented using varargs.
      * @return {@code true} if successful, otherwise {@code false} if the
-     * witness value was not the same as the {@code expectedValue} or if this
+     * <em>witness value</em> was not the same as the {@code expectedValue} or if this
      * operation spuriously failed.
      * @throws UnsupportedOperationException if the access mode is unsupported
      * for this VarHandle.
@@ -973,7 +973,7 @@ public boolean hasInvokeExactBehavior() {
      * {@link #getVolatile}.
      *
      * <p>This operation may fail spuriously (typically, due to memory
-     * contention) even if the witness value does match the expected value.
+     * contention) even if the <em>witness value</em> does match the expected value.
      *
      * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)boolean}.
      *
@@ -986,7 +986,7 @@ public boolean hasInvokeExactBehavior() {
      * {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)}
      * , statically represented using varargs.
      * @return {@code true} if successful, otherwise {@code false} if the
-     * witness value was not the same as the {@code expectedValue} or if this
+     * <em>witness value</em> was not the same as the {@code expectedValue} or if this
      * operation spuriously failed.
      * @throws UnsupportedOperationException if the access mode is unsupported
      * for this VarHandle.
@@ -1010,7 +1010,7 @@ public boolean hasInvokeExactBehavior() {
      * {@link #getAcquire}.
      *
      * <p>This operation may fail spuriously (typically, due to memory
-     * contention) even if the witness value does match the expected value.
+     * contention) even if the <em>witness value</em> does match the expected value.
      *
      * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)boolean}.
      *
@@ -1024,7 +1024,7 @@ public boolean hasInvokeExactBehavior() {
      * {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)}
      * , statically represented using varargs.
      * @return {@code true} if successful, otherwise {@code false} if the
-     * witness value was not the same as the {@code expectedValue} or if this
+     * <em>witness value</em> was not the same as the {@code expectedValue} or if this
      * operation spuriously failed.
      * @throws UnsupportedOperationException if the access mode is unsupported
      * for this VarHandle.
@@ -1048,7 +1048,7 @@ public boolean hasInvokeExactBehavior() {
      * {@link #get}.
      *
      * <p>This operation may fail spuriously (typically, due to memory
-     * contention) even if the witness value does match the expected value.
+     * contention) even if the <em>witness value</em> does match the expected value.
      *
      * <p>The method signature is of the form {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)boolean}.
      *
@@ -1062,7 +1062,7 @@ public boolean hasInvokeExactBehavior() {
      * {@code (CT1 ct1, ..., CTn ctn, T expectedValue, T newValue)}
      * , statically represented using varargs.
      * @return {@code true} if successful, otherwise {@code false} if the
-     * witness value was not the same as the {@code expectedValue} or if this
+     * <em>witness value</em> was not the same as the {@code expectedValue} or if this
      * operation spuriously failed.
      * @throws UnsupportedOperationException if the access mode is unsupported
      * for this VarHandle.

src/java.base/share/classes/java/util/concurrent/atomic/AtomicBoolean.java

@@ -260,7 +260,7 @@ public final void setRelease(boolean newValue) {
      *
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */
@@ -278,7 +278,7 @@ public final boolean compareAndExchange(boolean expectedValue, boolean newValue)
      *
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */
@@ -296,7 +296,7 @@ public final boolean compareAndExchangeAcquire(boolean expectedValue, boolean ne
      *
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */

src/java.base/share/classes/java/util/concurrent/atomic/AtomicInteger.java

@@ -465,7 +465,7 @@ public final void setRelease(int newValue) {
      *
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */
@@ -481,7 +481,7 @@ public final int compareAndExchange(int expectedValue, int newValue) {
      *
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */
@@ -497,7 +497,7 @@ public final int compareAndExchangeAcquire(int expectedValue, int newValue) {
      *
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */

src/java.base/share/classes/java/util/concurrent/atomic/AtomicIntegerArray.java

@@ -470,7 +470,7 @@ public final void setRelease(int i, int newValue) {
      * @param i the index
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */
@@ -488,7 +488,7 @@ public final int compareAndExchange(int i, int expectedValue, int newValue) {
      * @param i the index
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */
@@ -506,7 +506,7 @@ public final int compareAndExchangeAcquire(int i, int expectedValue, int newValu
      * @param i the index
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */

src/java.base/share/classes/java/util/concurrent/atomic/AtomicLong.java

@@ -478,7 +478,7 @@ public final void setRelease(long newValue) {
      *
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */
@@ -494,7 +494,7 @@ public final long compareAndExchange(long expectedValue, long newValue) {
      *
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */
@@ -510,7 +510,7 @@ public final long compareAndExchangeAcquire(long expectedValue, long newValue) {
      *
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */

src/java.base/share/classes/java/util/concurrent/atomic/AtomicLongArray.java

@@ -470,7 +470,7 @@ public final void setRelease(int i, long newValue) {
      * @param i the index
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */
@@ -488,7 +488,7 @@ public final long compareAndExchange(int i, long expectedValue, long newValue) {
      * @param i the index
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */
@@ -506,7 +506,7 @@ public final long compareAndExchangeAcquire(int i, long expectedValue, long newV
      * @param i the index
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */

src/java.base/share/classes/java/util/concurrent/atomic/AtomicReference.java

@@ -353,7 +353,7 @@ public final void setRelease(V newValue) {
      *
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */
@@ -369,7 +369,7 @@ public final V compareAndExchange(V expectedValue, V newValue) {
      *
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */
@@ -385,7 +385,7 @@ public final V compareAndExchangeAcquire(V expectedValue, V newValue) {
      *
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */

src/java.base/share/classes/java/util/concurrent/atomic/AtomicReferenceArray.java

@@ -434,7 +434,7 @@ public final void setRelease(int i, E newValue) {
      * @param i the index
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */
@@ -452,7 +452,7 @@ public final E compareAndExchange(int i, E expectedValue, E newValue) {
      * @param i the index
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */
@@ -470,7 +470,7 @@ public final E compareAndExchangeAcquire(int i, E expectedValue, E newValue) {
      * @param i the index
      * @param expectedValue the expected value
      * @param newValue the new value
-     * @return the witness value, which will be the same as the
+     * @return the <em>witness value</em>, which will be the same as the
      * expected value if successful
      * @since 9
      */