From 723ebfcb4f17e48f2a614f0e1e124e8da9c75b70 Mon Sep 17 00:00:00 2001
From: JuliDi <20155974+JuliDi@users.noreply.github.com>
Date: Sun, 4 May 2025 16:31:26 +0200
Subject: [PATCH] clarify docs for signal and watch

---
 embassy-sync/src/signal.rs | 5 +++--
 embassy-sync/src/watch.rs  | 4 ++--
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/embassy-sync/src/signal.rs b/embassy-sync/src/signal.rs
index a0f4b5a74..e7095401e 100644
--- a/embassy-sync/src/signal.rs
+++ b/embassy-sync/src/signal.rs
@@ -6,7 +6,7 @@ use core::task::{Context, Poll, Waker};
 use crate::blocking_mutex::raw::RawMutex;
 use crate::blocking_mutex::Mutex;
 
-/// Single-slot signaling primitive.
+/// Single-slot signaling primitive for a _single_ consumer.
 ///
 /// This is similar to a [`Channel`](crate::channel::Channel) with a buffer size of 1, except
 /// "sending" to it (calling [`Signal::signal`]) when full will overwrite the previous value instead
@@ -17,6 +17,7 @@ use crate::blocking_mutex::Mutex;
 /// updates.
 ///
 /// For more advanced use cases, you might want to use [`Channel`](crate::channel::Channel) instead.
+/// For multiple consumers, use [`Watch`](crate::watch::Watch) instead.
 ///
 /// Signals are generally declared as `static`s and then borrowed as required.
 ///
@@ -106,7 +107,7 @@ where
         })
     }
 
-    /// Future that completes when this Signal has been signaled.
+    /// Future that completes when this Signal has been signaled, taking the value out of the signal.
     pub fn wait(&self) -> impl Future<Output = T> + '_ {
         poll_fn(move |cx| self.poll_wait(cx))
     }
diff --git a/embassy-sync/src/watch.rs b/embassy-sync/src/watch.rs
index e76646c0b..08d6a833d 100644
--- a/embassy-sync/src/watch.rs
+++ b/embassy-sync/src/watch.rs
@@ -10,7 +10,7 @@ use crate::blocking_mutex::raw::RawMutex;
 use crate::blocking_mutex::Mutex;
 use crate::waitqueue::MultiWakerRegistration;
 
-/// The `Watch` is a single-slot signaling primitive that allows multiple receivers to concurrently await
+/// The `Watch` is a single-slot signaling primitive that allows _multiple_ (`N`) receivers to concurrently await
 /// changes to the value. Unlike a [`Signal`](crate::signal::Signal), `Watch` supports multiple receivers,
 /// and unlike a [`PubSubChannel`](crate::pubsub::PubSubChannel), `Watch` immediately overwrites the previous
 /// value when a new one is sent, without waiting for all receivers to read the previous value.
@@ -298,7 +298,7 @@ impl<M: RawMutex, T: Clone, const N: usize> WatchBehavior<T> for Watch<M, T, N>
 }
 
 impl<M: RawMutex, T: Clone, const N: usize> Watch<M, T, N> {
-    /// Create a new `Watch` channel.
+    /// Create a new `Watch` channel for `N` receivers.
     pub const fn new() -> Self {
         Self {
             mutex: Mutex::new(RefCell::new(WatchState {