Improve timer documentation

src/internal/timer.rs

@@ -1,13 +1,14 @@
 use tokio::time::{delay_until, Duration, Instant};
 
+/// A reusable timer that keeps track of its duration/interval/period.
 #[derive(Debug)]
 pub struct Timer {
     due: Instant,
     duration: Duration,
 }
 
 impl Timer {
-    /// construct timer, initially set and due `duration_in_ms` in the future
+    /// Constructs a `Timer`, initially armed to expire in `duration_in_ms` from the current instant.
     pub fn new(duration_in_ms: u64) -> Timer {
         let duration = Duration::from_millis(duration_in_ms);
 
@@ -17,13 +18,15 @@ impl Timer {
         }
     }
 
-    /// block until next due time resetting afterwards
+    /// Blocks until the due time.
+    /// The timer wil be reset afterwards, `duration` later.
     pub async fn hold(&mut self) {
         delay_until(self.due).await;
         self.increment();
     }
 
-    /// returns true and resets the timer if due
+    /// Returns true if the timer is expired (current instant past `due` time).
+    /// Resets the timer `duration` later if it is.
     pub fn check(&mut self) -> bool {
         if Instant::now() >= self.due {
             self.increment();
@@ -33,12 +36,13 @@ impl Timer {
         }
     }
 
-    /// reset timer to be 1 duration after previous due time
+    /// Resets the timer to expire 1 `duration` later than the previous due time.
     fn increment(&mut self) {
         self.due += self.duration
     }
 
-    /// reset timer to be 1 duration from **now**
+    /// Resets timer to expire 1 `duration` from the current instant.
+    /// This has the same effect as constructing a new `Timer` with the same `duration`.
     pub fn reset(&mut self) {
         self.due = Instant::now() + self.duration;
     }