From 40617fea043538833e40bec1694c17be6faf5077 Mon Sep 17 00:00:00 2001
From: Joshua Salzedo <joshuasalzedo@gmail.com>
Date: Wed, 24 Mar 2021 13:19:05 -0700
Subject: [PATCH] Document embassy::util::signal & embassy::util

---
 embassy/src/util/mod.rs    | 1 +
 embassy/src/util/signal.rs | 7 ++++++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/embassy/src/util/mod.rs b/embassy/src/util/mod.rs
index e64e7f1f..6917e999 100644
--- a/embassy/src/util/mod.rs
+++ b/embassy/src/util/mod.rs
@@ -1,3 +1,4 @@
+//! Async utilities
 mod drop_bomb;
 mod forever;
 mod mutex;
diff --git a/embassy/src/util/signal.rs b/embassy/src/util/signal.rs
index e3c5fad1..12dc7c31 100644
--- a/embassy/src/util/signal.rs
+++ b/embassy/src/util/signal.rs
@@ -10,6 +10,9 @@ use crate::executor;
 use crate::fmt::panic;
 use crate::interrupt::{Interrupt, InterruptExt};
 
+/// Synchronization primitive. Allows creating awaitable signals that may be passed between tasks.
+///
+/// For more advanced use cases, please consider [futures-intrusive](https://crates.io/crates/futures-intrusive) channels or mutexes.
 pub struct Signal<T> {
     state: UnsafeCell<State<T>>,
 }
@@ -29,7 +32,7 @@ impl<T: Send> Signal<T> {
             state: UnsafeCell::new(State::None),
         }
     }
-
+    /// Mark this Signal as completed.
     pub fn signal(&self, val: T) {
         cortex_m::interrupt::free(|_| unsafe {
             let state = &mut *self.state.get();
@@ -64,10 +67,12 @@ impl<T: Send> Signal<T> {
         })
     }
 
+    /// Future that completes when this Signal has been signaled.
     pub fn wait(&self) -> impl Future<Output = T> + '_ {
         futures::future::poll_fn(move |cx| self.poll_wait(cx))
     }
 
+    /// non-blocking method to check whether this signal has been signaled.
     pub fn signaled(&self) -> bool {
         cortex_m::interrupt::free(|_| matches!(unsafe { &*self.state.get() }, State::Signaled(_)))
     }