docs: extend the waker documentation

5 files changed, 13 insertions, 1 deletions

diff --git a/embassy-sync/README.md b/embassy-sync/README.md
index 6871bcabc..91c59884f 100644
--- a/embassy-sync/README.md
+++ b/embassy-sync/README.md
@@ -12,7 +12,7 @@ Synchronization primitives and data structures with async support:
 - [`Mutex`](mutex::Mutex) - Mutex for synchronizing state between asynchronous tasks.
 - [`Pipe`](pipe::Pipe) - Byte stream implementing `embedded_io` traits.
 - [`WakerRegistration`](waitqueue::WakerRegistration) - Utility to register and wake a `Waker`.
-- [`AtomicWaker`](waitqueue::AtomicWaker) - A variant of `WakerRegistration` accessible using a non-mut API.
+- [`AtomicWaker`](waitqueue::AtomicWaker) - Utility to register and wake a `Waker` from interrupt context.
 - [`MultiWakerRegistration`](waitqueue::MultiWakerRegistration) - Utility registering and waking multiple `Waker`'s.
 - [`LazyLock`](lazy_lock::LazyLock) - A value which is initialized on the first access
 
diff --git a/embassy-sync/src/waitqueue/atomic_waker.rs b/embassy-sync/src/waitqueue/atomic_waker.rs
index 231902c5a..5a9910e7f 100644
--- a/embassy-sync/src/waitqueue/atomic_waker.rs
+++ b/embassy-sync/src/waitqueue/atomic_waker.rs
@@ -5,6 +5,9 @@ use crate::blocking_mutex::raw::{CriticalSectionRawMutex, RawMutex};
 use crate::blocking_mutex::Mutex;
 
 /// Utility struct to register and wake a waker.
+/// If a waker is registered, registering another waker will replace the previous one without waking it.
+/// Intended to wake a task from an interrupt. Therefore, it is generally not expected,
+/// that multiple tasks register try to register a waker simultaneously.
 pub struct GenericAtomicWaker<M: RawMutex> {
     waker: Mutex<M, Cell<Option<Waker>>>,
 }
diff --git a/embassy-sync/src/waitqueue/atomic_waker_turbo.rs b/embassy-sync/src/waitqueue/atomic_waker_turbo.rs
index 5c6a96ec8..c06b83056 100644
--- a/embassy-sync/src/waitqueue/atomic_waker_turbo.rs
+++ b/embassy-sync/src/waitqueue/atomic_waker_turbo.rs
@@ -4,6 +4,9 @@ use core::sync::atomic::{AtomicPtr, Ordering};
 use core::task::Waker;
 
 /// Utility struct to register and wake a waker.
+/// If a waker is registered, registering another waker will replace the previous one without waking it.
+/// The intended use case is to wake tasks from interrupts. Therefore, it is generally not expected,
+/// that multiple tasks register try to register a waker simultaneously.
 pub struct AtomicWaker {
     waker: AtomicPtr<()>,
 }
diff --git a/embassy-sync/src/waitqueue/multi_waker.rs b/embassy-sync/src/waitqueue/multi_waker.rs
index 0e520bf40..0384d6bed 100644
--- a/embassy-sync/src/waitqueue/multi_waker.rs
+++ b/embassy-sync/src/waitqueue/multi_waker.rs
@@ -3,6 +3,8 @@ use core::task::Waker;
 use heapless::Vec;
 
 /// Utility struct to register and wake multiple wakers.
+/// Queue of wakers with a maximum length of `N`.
+/// Intended for waking multiple tasks.
 pub struct MultiWakerRegistration<const N: usize> {
     wakers: Vec<Waker, N>,
 }
diff --git a/embassy-sync/src/waitqueue/waker_registration.rs b/embassy-sync/src/waitqueue/waker_registration.rs
index 9b666e7c4..7f24f8fb6 100644
--- a/embassy-sync/src/waitqueue/waker_registration.rs
+++ b/embassy-sync/src/waitqueue/waker_registration.rs
@@ -2,6 +2,10 @@ use core::mem;
 use core::task::Waker;
 
 /// Utility struct to register and wake a waker.
+/// If a waker is registered, registering another waker will replace the previous one.
+/// The previous waker will be woken in this case, giving it a chance to reregister itself.
+/// Although it is possible to wake multiple tasks this way,
+/// this will cause them to wake each other in a loop registering themselves.
 #[derive(Debug, Default)]
 pub struct WakerRegistration {
     waker: Option<Waker>,