Add Struct/impl documentation for embassy::time::Instant

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
     }