futures: readme, docs improvements.

embassy-futures/src/block_on.rs

@@ -11,6 +11,8 @@ static VTABLE: RawWakerVTable = RawWakerVTable::new(|_| RawWaker::new(ptr::null(
 /// the current thread at 100% cpu usage until the future is done. The
 /// future's `Waker` mechanism is not used.
 ///
+/// You can use this to run multiple futures concurrently with [`join`][crate::join].
+///
 /// It's suitable for systems with no or limited concurrency and without
 /// strict requirements around power consumption. For more complex use
 /// cases, prefer using a "real" executor like `embassy-executor`, which

embassy-futures/src/yield_now.rs

@@ -3,6 +3,23 @@ use core::pin::Pin;
 use core::task::{Context, Poll};
 
 /// Yield from the current task once, allowing other tasks to run.
+///
+/// This can be used to easily and quickly implement simple async primitives
+/// without using wakers. The following snippet will wait for a condition to
+/// hold, while still allowing other tasks to run concurrently (not monopolizing
+/// the executor thread).
+///
+/// ```rust,no_run
+/// while !some_condition() {
+///     yield_now().await;
+/// }
+/// ```
+///
+/// The downside is this will spin in a busy loop, using 100% of the CPU, while
+/// using wakers correctly would allow the CPU to sleep while waiting.
+///
+/// The internal implementation is: on first poll the future wakes itself and
+/// returns `Poll::Pending`. On second poll, it returns `Poll::Ready`.
 pub fn yield_now() -> impl Future<Output = ()> {
     YieldNowFuture { yielded: false }
 }