From 51583afc1e1e5d6eafefbb994c153d1d923a502f Mon Sep 17 00:00:00 2001
From: Thales Fragoso <thales.fragosoz@gmail.com>
Date: Mon, 28 Jun 2021 18:30:04 -0300
Subject: [PATCH] Add docs for BlockingTimer and rename tick features

---
 embassy/Cargo.toml      |  8 ++++----
 embassy/src/time/mod.rs | 35 +++++++++++++++++++++--------------
 2 files changed, 25 insertions(+), 18 deletions(-)

diff --git a/embassy/Cargo.toml b/embassy/Cargo.toml
index f3cb4655..87f54409 100644
--- a/embassy/Cargo.toml
+++ b/embassy/Cargo.toml
@@ -5,11 +5,11 @@ authors = ["Dario Nieuwenhuis <dirbaio@dirbaio.net>"]
 edition = "2018"
 
 [features]
-default = ["tick-hz-32768"]
+default = ["tick-32768hz"]
 std = ["futures/std", "embassy-traits/std"]
-tick-hz-32768 = []
-tick-hz-1000 = []
-tick-mhz-1 = []
+tick-32768hz = []
+tick-1000hz = []
+tick-1mhz = []
 
 defmt-trace = []
 defmt-debug = []
diff --git a/embassy/src/time/mod.rs b/embassy/src/time/mod.rs
index 2ebe19fb..d50d9ef0 100644
--- a/embassy/src/time/mod.rs
+++ b/embassy/src/time/mod.rs
@@ -11,20 +11,20 @@ pub use instant::Instant;
 pub use traits::*;
 
 #[cfg(any(
-    all(feature = "tick-hz-32768", feature = "tick-hz-1000"),
-    all(feature = "tick-hz-32768", feature = "tick-mhz-1"),
+    all(feature = "tick-32768hz", feature = "tick-1000hz"),
+    all(feature = "tick-32768hz", feature = "tick-1mhz"),
 ))]
 compile_error!(
     "Disable default-features to be able to use a tick rate other than the default (32768 Hz)"
 );
 
-#[cfg(feature = "tick-hz-1000")]
+#[cfg(feature = "tick-1000hz")]
 pub const TICKS_PER_SECOND: u64 = 1_000;
 
-#[cfg(feature = "tick-hz-32768")]
+#[cfg(feature = "tick-32768hz")]
 pub const TICKS_PER_SECOND: u64 = 32_768;
 
-#[cfg(feature = "tick-mhz-1")]
+#[cfg(feature = "tick-1mhz")]
 pub const TICKS_PER_SECOND: u64 = 1_000_000;
 
 static mut CLOCK: Option<&'static dyn Clock> = None;
@@ -43,47 +43,54 @@ pub(crate) fn now() -> u64 {
     unsafe { unwrap!(CLOCK, "No clock set").now() }
 }
 
+/// Type used for blocking delays through embedded-hal traits.
+///
+/// For this interface to work, the Executor's clock must be correctly initialized before using it.
+/// The delays are implemented in a "best-effort" way, meaning that the cpu will block for at least
+/// the amount provided, but accuracy can be affected by many factors, including interrupt usage.
+/// Make sure to use a suitable tick rate for your use case. The tick rate can be chosen through
+/// features flags of this crate.
 pub struct BlockingTimer;
 
 impl embedded_hal::blocking::delay::DelayMs<u8> for BlockingTimer {
     fn delay_ms(&mut self, ms: u8) {
-        block_for(Duration::from_millis(u64::from(ms)))
+        block_for(Duration::from_millis(ms as u64))
     }
 }
 
 impl embedded_hal::blocking::delay::DelayMs<u16> for BlockingTimer {
     fn delay_ms(&mut self, ms: u16) {
-        block_for(Duration::from_millis(u64::from(ms)))
+        block_for(Duration::from_millis(ms as u64))
     }
 }
 
 impl embedded_hal::blocking::delay::DelayMs<u32> for BlockingTimer {
     fn delay_ms(&mut self, ms: u32) {
-        block_for(Duration::from_millis(u64::from(ms)))
+        block_for(Duration::from_millis(ms as u64))
     }
 }
 
-#[cfg(feature = "tick-mhz-1")]
 impl embedded_hal::blocking::delay::DelayUs<u8> for BlockingTimer {
     fn delay_us(&mut self, us: u8) {
-        block_for(Duration::from_micros(u64::from(us)))
+        block_for(Duration::from_micros(us as u64))
     }
 }
 
-#[cfg(feature = "tick-mhz-1")]
 impl embedded_hal::blocking::delay::DelayUs<u16> for BlockingTimer {
     fn delay_us(&mut self, us: u16) {
-        block_for(Duration::from_micros(u64::from(us)))
+        block_for(Duration::from_micros(us as u64))
     }
 }
 
-#[cfg(feature = "tick-mhz-1")]
 impl embedded_hal::blocking::delay::DelayUs<u32> for BlockingTimer {
     fn delay_us(&mut self, us: u32) {
-        block_for(Duration::from_micros(u64::from(us)))
+        block_for(Duration::from_micros(us as u64))
     }
 }
 
+/// Blocks the cpu for at least `duration`.
+///
+/// For this interface to work, the Executor's clock must be correctly initialized before using it.
 pub fn block_for(duration: Duration) {
     let expires_at = Instant::now() + duration;
     while Instant::now() < expires_at {}