From d20d110fcdb24879f66a303c5153d1a1ebde735a Mon Sep 17 00:00:00 2001
From: qm3ster <qm3ster@gmail.com>
Date: Thu, 20 Aug 2020 15:39:45 +0300
Subject: [PATCH] Improve timer documentation

---
 src/internal/timer.rs | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/src/internal/timer.rs b/src/internal/timer.rs
index 68aca7e02ca..c97d2459088 100644
--- a/src/internal/timer.rs
+++ b/src/internal/timer.rs
@@ -1,5 +1,6 @@
 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,
@@ -7,7 +8,7 @@ pub struct Timer {
 }
 
 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;
     }