From 6392f067172541a0cb9b3757a9c7a40d3b7c5e25 Mon Sep 17 00:00:00 2001
From: Dario Nieuwenhuis <dirbaio@dirbaio.net>
Date: Mon, 29 Aug 2022 00:54:14 +0200
Subject: [PATCH] futures: readme, docs improvements.

---
 embassy-futures/Cargo.toml       |  5 ++++-
 embassy-futures/README.md        | 32 +++++++++++++++++++++++++-------
 embassy-futures/src/block_on.rs  |  2 ++
 embassy-futures/src/yield_now.rs | 17 +++++++++++++++++
 4 files changed, 48 insertions(+), 8 deletions(-)

diff --git a/embassy-futures/Cargo.toml b/embassy-futures/Cargo.toml
index e564f5a96..7123b7c61 100644
--- a/embassy-futures/Cargo.toml
+++ b/embassy-futures/Cargo.toml
@@ -6,9 +6,12 @@ edition = "2021"
 [package.metadata.embassy_docs]
 src_base = "https://github.com/embassy-rs/embassy/blob/embassy-futures-v$VERSION/embassy-futures/src/"
 src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-futures/src/"
-features = ["nightly"]
+features = ["defmt"]
 target = "thumbv7em-none-eabi"
 
+[package.metadata.docs.rs]
+features = ["defmt"]
+
 [dependencies]
 defmt = { version = "0.3", optional = true }
 log = { version = "0.4.14", optional = true }
diff --git a/embassy-futures/README.md b/embassy-futures/README.md
index 3810bcafd..7add22c7b 100644
--- a/embassy-futures/README.md
+++ b/embassy-futures/README.md
@@ -1,10 +1,28 @@
 # embassy-futures
 
-Utilities for working with futures:
+An [Embassy](https://embassy.dev) project.
+
+Utilities for working with futures, compatible with `no_std` and not using `alloc`. Optimized for code size,
+ideal for embedded systems.
+
+- Future combinators, like [`join`](join) and [`select`](select)
+- Utilities to use `async` without a fully fledged executor: [`block_on`](block_on::block_on) and [`yield_now`](yield_now::yield_now).
+
+## Interoperability
+
+Futures from this crate can run on any executor.
+
+## Minimum supported Rust version (MSRV)
+
+Embassy is guaranteed to compile on the latest stable Rust version at the time of release. It might compile with older versions but that may change in any new patch release.
+
+## License
+
+This work is licensed under either of
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
+  <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
+
+at your option.
 
-- [`select`](select::select) - waiting for one out of two futures to complete.
-- [`select3`](select::select3) - waiting for one out of three futures to complete.
-- [`select4`](select::select4) - waiting for one out of four futures to complete.
-- [`select_array`](select::select_array) - waiting for one future in an array of futures to complete.
-- [`select_slice`](select::select_slice) - waiting for one future in a slice of futures to complete.
-- [`yield_now`](yield_now::yield_now) - yielding the current task.
diff --git a/embassy-futures/src/block_on.rs b/embassy-futures/src/block_on.rs
index 749fa67f3..da90351ec 100644
--- a/embassy-futures/src/block_on.rs
+++ b/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
diff --git a/embassy-futures/src/yield_now.rs b/embassy-futures/src/yield_now.rs
index 1ebecb916..13b103778 100644
--- a/embassy-futures/src/yield_now.rs
+++ b/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 }
 }