Merge pull request #102 from theunkn0wn1/doc/duration

Add some documentation for the timing module

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 two [Instant](struct.Instant.html)s
 pub struct Duration {
     pub(crate) ticks: u64,
 }
@@ -26,49 +27,55 @@ 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,
         }
     }
 
-    /*
-        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 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 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 _)

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,55 @@ 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 +74,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 +86,7 @@ impl Instant {
         }
     }
 
+    /// Duration elapsed since this Instant.
     pub fn elapsed(&self) -> Duration {
         Instant::now() - *self
     }

embassy/src/time/mod.rs

@@ -1,3 +1,6 @@
+//! 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;
@@ -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() }
 }