From cf1323fb67b2841a99bb497d7947ffa772ff354d Mon Sep 17 00:00:00 2001
From: Joshua Salzedo <joshuasalzedo@gmail.com>
Date: Sun, 21 Mar 2021 16:45:24 -0700
Subject: [PATCH 1/8] Add module-level documentation for embassy::time

---
 embassy/src/time/mod.rs | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/embassy/src/time/mod.rs b/embassy/src/time/mod.rs
index b45a608dd..b19ab6dbb 100644
--- a/embassy/src/time/mod.rs
+++ b/embassy/src/time/mod.rs
@@ -1,3 +1,6 @@
+/// Time abstractions
+/// To use these abstractions, first call `set_clock` with an instance of an monotonic `Clock`.
+///
 mod duration;
 mod instant;
 mod traits;
@@ -14,10 +17,16 @@ pub const TICKS_PER_SECOND: u64 = 32768;
 
 static mut CLOCK: Option<&'static dyn Clock> = None;
 
+/// Sets the clock used for the timing abstractions
+///
+/// Safety: Sets a mutable global.
 pub unsafe fn set_clock(clock: &'static dyn Clock) {
     CLOCK = Some(clock);
 }
 
+/// Return the current timestamp in ticks.
+/// This is guaranteed to be monotonic, i.e. a call to now() will always return
+/// a greater or equal value than earler calls.
 pub(crate) fn now() -> u64 {
     unsafe { unwrap!(CLOCK, "No clock set").now() }
 }

From d453b9dd95589d95239ea3f86f15da647d253aef Mon Sep 17 00:00:00 2001
From: Joshua Salzedo <joshuasalzedo@gmail.com>
Date: Sun, 21 Mar 2021 16:45:48 -0700
Subject: [PATCH 2/8] Add Struct/impl documentation for embassy::time::Duration

---
 embassy/src/time/duration.rs | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/embassy/src/time/duration.rs b/embassy/src/time/duration.rs
index e04afa184..c96007747 100644
--- a/embassy/src/time/duration.rs
+++ b/embassy/src/time/duration.rs
@@ -26,16 +26,18 @@ impl Duration {
         self.ticks * 1_000_000 / TICKS_PER_SECOND
     }
 
+    /// Creates a duration from the specified number of clock ticks
     pub const fn from_ticks(ticks: u64) -> Duration {
         Duration { ticks }
     }
 
+    /// Creates a duration from the specified number of seconds
     pub const fn from_secs(secs: u64) -> Duration {
         Duration {
             ticks: secs * TICKS_PER_SECOND,
         }
     }
-
+    /// Creates a duration from the specified number of milliseconds
     pub const fn from_millis(millis: u64) -> Duration {
         Duration {
             ticks: millis * TICKS_PER_SECOND / 1000,
@@ -45,30 +47,34 @@ impl Duration {
     /*
         NOTE: us delays may not be as accurate
     */
+    /// Creates a duration from the specified number of microseconds
+    /// NOTE: Delays this small may be inaccurate.
     pub const fn from_micros(micros: u64) -> Duration {
         Duration {
             ticks: micros * TICKS_PER_SECOND / 1_000_000,
         }
     }
 
+    /// Adds one Duration to another, returning a new Duration or None in the event of an overflow.
     pub fn checked_add(self, rhs: Duration) -> Option<Duration> {
         self.ticks
             .checked_add(rhs.ticks)
             .map(|ticks| Duration { ticks })
     }
-
+    /// Subtracts one Duration to another, returning a new Duration or None in the event of an overflow.
     pub fn checked_sub(self, rhs: Duration) -> Option<Duration> {
         self.ticks
             .checked_sub(rhs.ticks)
             .map(|ticks| Duration { ticks })
     }
+    /// Multiplies one Duration to another, returning a new Duration or None in the event of an overflow.
 
     pub fn checked_mul(self, rhs: u32) -> Option<Duration> {
         self.ticks
             .checked_mul(rhs as _)
             .map(|ticks| Duration { ticks })
     }
-
+    /// Divides one Duration against another, returning a new Duration or None in the event of an overflow.
     pub fn checked_div(self, rhs: u32) -> Option<Duration> {
         self.ticks
             .checked_div(rhs as _)

From dcdd768e0360683db747906e4780e5470d1961a1 Mon Sep 17 00:00:00 2001
From: Joshua Salzedo <joshuasalzedo@gmail.com>
Date: Sun, 21 Mar 2021 16:45:53 -0700
Subject: [PATCH 3/8] Add Struct/impl documentation for embassy::time::Instant

---
 embassy/src/time/instant.rs | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/embassy/src/time/instant.rs b/embassy/src/time/instant.rs
index 06ab84c75..9a544fc46 100644
--- a/embassy/src/time/instant.rs
+++ b/embassy/src/time/instant.rs
@@ -6,6 +6,7 @@ use super::{now, Duration};
 
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// An Instant in time, based on the MCU's clock ticks since startup.
 pub struct Instant {
     ticks: u64,
 }
@@ -14,44 +15,54 @@ impl Instant {
     pub const MIN: Instant = Instant { ticks: u64::MIN };
     pub const MAX: Instant = Instant { ticks: u64::MAX };
 
+    /// Returns an Instant representing the current time.
     pub fn now() -> Instant {
         Instant { ticks: now() }
     }
 
+    /// Instant as clock ticks since MCU start.
     pub const fn from_ticks(ticks: u64) -> Self {
         Self { ticks }
     }
 
+    /// Instant as milliseconds since MCU start.
     pub const fn from_millis(millis: u64) -> Self {
         Self {
             ticks: millis * TICKS_PER_SECOND as u64 / 1000,
         }
     }
-
+    /// Instant representing seconds since MCU start.
     pub const fn from_secs(seconds: u64) -> Self {
         Self {
             ticks: seconds * TICKS_PER_SECOND as u64,
         }
     }
 
+    /// Instant as ticks since MCU start.
+
     pub const fn as_ticks(&self) -> u64 {
         self.ticks
     }
+    /// Instant as seconds since MCU start.
 
     pub const fn as_secs(&self) -> u64 {
         self.ticks / TICKS_PER_SECOND as u64
     }
+    /// Instant as miliseconds since MCU start.
 
     pub const fn as_millis(&self) -> u64 {
         self.ticks * 1000 / TICKS_PER_SECOND as u64
     }
 
+    /// Duration between this Instant and another Instant
+    /// Panics on over/underflow.
     pub fn duration_since(&self, earlier: Instant) -> Duration {
         Duration {
             ticks: self.ticks.checked_sub(earlier.ticks).unwrap(),
         }
     }
 
+    /// Duration between this Instant and another Instant
     pub fn checked_duration_since(&self, earlier: Instant) -> Option<Duration> {
         if self.ticks < earlier.ticks {
             None
@@ -62,6 +73,8 @@ impl Instant {
         }
     }
 
+    /// Returns the duration since the "earlier" Instant.
+    /// If the "earlier" instant is in the future, the duration is set to zero.
     pub fn saturating_duration_since(&self, earlier: Instant) -> Duration {
         Duration {
             ticks: if self.ticks < earlier.ticks {
@@ -72,6 +85,7 @@ impl Instant {
         }
     }
 
+    /// Duration elapsed since this Instant.
     pub fn elapsed(&self) -> Duration {
         Instant::now() - *self
     }

From f8d63279efed5dfd649118ac89903a8bcb01a09d Mon Sep 17 00:00:00 2001
From: Joshua Salzedo <joshuasalzedo@gmail.com>
Date: Sun, 21 Mar 2021 17:01:13 -0700
Subject: [PATCH 4/8] Re-add erroneously removed newlines

---
 embassy/src/time/duration.rs | 5 ++++-
 embassy/src/time/instant.rs  | 1 +
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/embassy/src/time/duration.rs b/embassy/src/time/duration.rs
index c96007747..474d0621b 100644
--- a/embassy/src/time/duration.rs
+++ b/embassy/src/time/duration.rs
@@ -37,6 +37,7 @@ impl Duration {
             ticks: secs * TICKS_PER_SECOND,
         }
     }
+
     /// Creates a duration from the specified number of milliseconds
     pub const fn from_millis(millis: u64) -> Duration {
         Duration {
@@ -61,19 +62,21 @@ impl Duration {
             .checked_add(rhs.ticks)
             .map(|ticks| Duration { ticks })
     }
+
     /// Subtracts one Duration to another, returning a new Duration or None in the event of an overflow.
     pub fn checked_sub(self, rhs: Duration) -> Option<Duration> {
         self.ticks
             .checked_sub(rhs.ticks)
             .map(|ticks| Duration { ticks })
     }
-    /// Multiplies one Duration to another, returning a new Duration or None in the event of an overflow.
 
+    /// Multiplies one Duration to another, returning a new Duration or None in the event of an overflow.
     pub fn checked_mul(self, rhs: u32) -> Option<Duration> {
         self.ticks
             .checked_mul(rhs as _)
             .map(|ticks| Duration { ticks })
     }
+
     /// Divides one Duration against another, returning a new Duration or None in the event of an overflow.
     pub fn checked_div(self, rhs: u32) -> Option<Duration> {
         self.ticks
diff --git a/embassy/src/time/instant.rs b/embassy/src/time/instant.rs
index 9a544fc46..61a61defe 100644
--- a/embassy/src/time/instant.rs
+++ b/embassy/src/time/instant.rs
@@ -31,6 +31,7 @@ impl Instant {
             ticks: millis * TICKS_PER_SECOND as u64 / 1000,
         }
     }
+
     /// Instant representing seconds since MCU start.
     pub const fn from_secs(seconds: u64) -> Self {
         Self {

From e363607d70ee088d2da43ec27d4a6257069a6b06 Mon Sep 17 00:00:00 2001
From: Joshua Salzedo <joshuasalzedo@gmail.com>
Date: Sun, 21 Mar 2021 17:01:52 -0700
Subject: [PATCH 5/8] Added doc to the embassy::time::Duration struct

---
 embassy/src/time/duration.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/embassy/src/time/duration.rs b/embassy/src/time/duration.rs
index 474d0621b..db0e2cf2d 100644
--- a/embassy/src/time/duration.rs
+++ b/embassy/src/time/duration.rs
@@ -5,6 +5,7 @@ use super::TICKS_PER_SECOND;
 
 #[derive(Debug, Default, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// Represents the difference between [Instant::now()](struct.Instant.html#method.now) and some other Instant
 pub struct Duration {
     pub(crate) ticks: u64,
 }

From 10f14747c35f5deab8240c4d792439d72f807bf9 Mon Sep 17 00:00:00 2001
From: Joshua Salzedo <joshuasalzedo@gmail.com>
Date: Sun, 21 Mar 2021 17:05:22 -0700
Subject: [PATCH 6/8] Fix module-level docstring

---
 embassy/src/time/mod.rs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/embassy/src/time/mod.rs b/embassy/src/time/mod.rs
index b19ab6dbb..4e9b5f592 100644
--- a/embassy/src/time/mod.rs
+++ b/embassy/src/time/mod.rs
@@ -1,6 +1,6 @@
-/// Time abstractions
-/// To use these abstractions, first call `set_clock` with an instance of an monotonic `Clock`.
-///
+//! Time abstractions
+//! To use these abstractions, first call `set_clock` with an instance of an [Clock](trait.Clock.html).
+//!
 mod duration;
 mod instant;
 mod traits;

From 7988b78107245b33fb8241d0eb04c7110e03f213 Mon Sep 17 00:00:00 2001
From: Joshua Salzedo <joshuasalzedo@gmail.com>
Date: Sun, 21 Mar 2021 17:05:36 -0700
Subject: [PATCH 7/8] remove now redundant non-doc comment

---
 embassy/src/time/duration.rs | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/embassy/src/time/duration.rs b/embassy/src/time/duration.rs
index db0e2cf2d..38b0c0832 100644
--- a/embassy/src/time/duration.rs
+++ b/embassy/src/time/duration.rs
@@ -46,9 +46,6 @@ impl Duration {
         }
     }
 
-    /*
-        NOTE: us delays may not be as accurate
-    */
     /// Creates a duration from the specified number of microseconds
     /// NOTE: Delays this small may be inaccurate.
     pub const fn from_micros(micros: u64) -> Duration {

From 42be860446856937048efa05538e43408677186e Mon Sep 17 00:00:00 2001
From: Joshua Salzedo <joshuasalzedo@gmail.com>
Date: Sun, 21 Mar 2021 17:11:30 -0700
Subject: [PATCH 8/8] Correct descriptions of Duration

---
 embassy/src/time/duration.rs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/embassy/src/time/duration.rs b/embassy/src/time/duration.rs
index 38b0c0832..5157450ad 100644
--- a/embassy/src/time/duration.rs
+++ b/embassy/src/time/duration.rs
@@ -5,7 +5,7 @@ use super::TICKS_PER_SECOND;
 
 #[derive(Debug, Default, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-/// Represents the difference between [Instant::now()](struct.Instant.html#method.now) and some other Instant
+/// Represents the difference between two [Instant](struct.Instant.html)s
 pub struct Duration {
     pub(crate) ticks: u64,
 }
@@ -68,14 +68,14 @@ impl Duration {
             .map(|ticks| Duration { ticks })
     }
 
-    /// Multiplies one Duration to another, returning a new Duration or None in the event of an overflow.
+    /// Multiplies one Duration by a scalar u32, returning a new Duration or None in the event of an overflow.
     pub fn checked_mul(self, rhs: u32) -> Option<Duration> {
         self.ticks
             .checked_mul(rhs as _)
             .map(|ticks| Duration { ticks })
     }
 
-    /// Divides one Duration against another, returning a new Duration or None in the event of an overflow.
+    /// Divides one Duration a scalar u32, returning a new Duration or None in the event of an overflow.
     pub fn checked_div(self, rhs: u32) -> Option<Duration> {
         self.ticks
             .checked_div(rhs as _)