~move benign race explanation to declaration site

Author: qwwdfsad

kotlinx-coroutines-core/common/src/channels/BufferedChannel.kt

@@ -1582,8 +1582,12 @@ internal open class BufferedChannel<E>(
          * When [hasNext] suspends, this field stores the corresponding
          * continuation. The [tryResumeHasNext] and [tryResumeHasNextOnClosedChannel]
          * function resume this continuation when the [hasNext] invocation should complete.
+         *
+         * This property is the subject to bening data race:
+         * It is nulled-out on both completion and cancellation paths that
+         * could happen concurrently.
          */
-        @BenignDataRace // See its uses for the explanation of the race
+        @BenignDataRace
         private var continuation: CancellableContinuationImpl<Boolean>? = null
 
         // `hasNext()` is just a special receive operation.

kotlinx-coroutines-core/common/src/selects/Select.kt

@@ -373,7 +373,7 @@ internal open class SelectImplementation<R>(
     /**
      * List of clauses waiting on this `select` instance.
      *
-     * This property is the subject to bening data-race: concurrent cancellation might null-out this property
+     * This property is the subject to bening data race: concurrent cancellation might null-out this property
      * while [trySelect] operation reads it and iterates over its content.
      * A logical race is resolved by the consensus on [state] property.
      */
@@ -412,8 +412,13 @@ internal open class SelectImplementation<R>(
      * one that stores either result when the clause is successfully registered ([inRegistrationPhase] is `true`),
      * or [DisposableHandle] instance when the clause is completed during registration ([inRegistrationPhase] is `false`).
      * Yet, this optimization is omitted for code simplicity.
+     *
+     * This property is the subject to benign data race:
+     * [Cleanup][cleanup] procedure can be invoked both as part of the completion sequence
+     * and as a cancellation handler triggered by an external cancellation.
+     * In both scenarios, [NO_RESULT] is written to this property via race.
      */
-    @BenignDataRace // See its cleanup phase for the explanation
+    @BenignDataRace
     private var internalResult: Any? = NO_RESULT
 
     /**
@@ -627,10 +632,7 @@ internal open class SelectImplementation<R>(
                         // try to resume the continuation.
                         this.internalResult = internalResult
                         if (cont.tryResume(onCancellation)) return TRY_SELECT_SUCCESSFUL
-                        /*
-                         * If the resumption failed, we need to clean the [result] field to avoid memory leaks.
-                         * This write is benignly races with the very same write in cancellation invoke() handler
-                         */
+                        // If the resumption failed, we need to clean the [result] field to avoid memory leaks.
                         this.internalResult = NO_RESULT
                         return TRY_SELECT_CANCELLED
                     }