Clarity change: make it clear that Atomics.notify() always causes Ato…

…mics.wait() to return

- The docs currently can be interpreted that a sleeping `Atomics.wait()` will never move on unless the expected value changes
- Clarified that this is not the case by André Bargull in https://bugzilla.mozilla.org/show_bug.cgi?id=1942674
- Updated docs to make it more clear under what conditions `Atomics.wait()` can return which value

files/en-us/web/javascript/reference/global_objects/atomics/index.md

@@ -104,7 +104,9 @@ const sab = new SharedArrayBuffer(1024);
 const int32 = new Int32Array(sab);
 ```
 
-A reading thread is sleeping and waiting on location 0 which is expected to be 0. As long as that is true, it will not go on. However, once the writing thread has stored a new value, it will be notified by the writing thread and return the new value (123).
+A reading thread is sleeping and waiting on location 0 because the provided value matches what is stored at the provided index.
+The reading thread will not move on until the writing thread has called `Atomics.notify()` on position 0 of the provided typed array.
+Note that if, after being woken up, the value of location 0 has not been changed by the writing thread, the reading thread will **not** go back to sleep, but will continue on.
 
 ```js
 Atomics.wait(int32, 0, 0);

files/en-us/web/javascript/reference/global_objects/atomics/notify/index.md

@@ -52,9 +52,9 @@ const sab = new SharedArrayBuffer(1024);
 const int32 = new Int32Array(sab);
 ```
 
-A reading thread is sleeping and waiting on location 0 which is expected to be 0. As
-long as that is true, it will not go on. However, once the writing thread has stored a
-new value, it will be notified by the writing thread and return the new value (123).
+A reading thread is sleeping and waiting on location 0 because the provided `value` matches what is stored at the provided `index`.
+The reading thread will not move on until the writing thread has called `Atomics.notify()` on position 0 of the provided `typedArray`.
+Note that if, after being woken up, the value of location 0 has not been changed by the writing thread, the reading thread will **not** go back to sleep, but will continue on.
 
 ```js
 Atomics.wait(int32, 0, 0);

files/en-us/web/javascript/reference/global_objects/atomics/wait/index.md

@@ -38,6 +38,10 @@ Atomics.wait(typedArray, index, value, timeout)
 
 A string which is either `"ok"`, `"not-equal"`, or `"timed-out"`.
 
+- `"ok"` is returned if woken up by a call to `Atomics.notify()`, **regardless of if the expected value has changed**
+- `"not-equal"` is returned immediately if the initial `value` does not equal what is stored at `index`
+- `"timed-out"` is returned if a sleeping wait exceeds the specified `timeout` without being woken up by `Atomics.notify()`
+
 ### Exceptions
 
 - {{jsxref("TypeError")}}
@@ -58,9 +62,9 @@ const sab = new SharedArrayBuffer(1024);
 const int32 = new Int32Array(sab);
 ```
 
-A reading thread is sleeping and waiting on location 0 which is expected to be 0. As
-long as that is true, it will not go on. However, once the writing thread has stored a
-new value, it will be notified by the writing thread and return the new value (123).
+A reading thread is sleeping and waiting on location 0 because the provided `value` matches what is stored at the provided `index`.
+The reading thread will not move on until the writing thread has called `Atomics.notify()` on position 0 of the provided `typedArray`.
+Note that if, after being woken up, the value of location 0 has not been changed by the writing thread, the reading thread will **not** go back to sleep, but will continue on.
 
 ```js
 Atomics.wait(int32, 0, 0);