Proposal Details

This is the current documentation for atomic.Bool CompareAndSwap:

// CompareAndSwap executes the compare-and-swap operation for the boolean value x.
func (x *Bool) CompareAndSwap(old, new bool) (swapped bool) {
	return CompareAndSwapUint32(&x.v, b32(old), b32(new))
}

This only happens for the special case Bool: From reading only the types bool * bool -> bool it is not clear if the return value is the first or second parameter, or some other bool value. The documentation comment just states the obvious (CompareAndSwap does compare-and-swap) and swapped is ambiguous IMHO b/c it could mean the swapped-in value new, the swapped-out value old, or that the swap operation was done.

The proposal is to clarify the doc comment as e.g. (assuming this is even correct)

// CompareAndSwap executes the compare-and-swap operation for the boolean value x.
// It returns true if the swap was done.

I'm not native English speaking, so, there is probably better wording.

References

• sync/atomic: add typed atomic values #50860
• doc: update Go memory model #50859