From e8c48297908835b6c2920709a7c87c40467e045c Mon Sep 17 00:00:00 2001
From: Ryan Summers <ryan.summers@vertigo-designs.com>
Date: Wed, 17 Feb 2021 17:26:54 +0100
Subject: [PATCH] Adding docs for the cycle counter

---
 src/hardware/cycle_counter.rs | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/src/hardware/cycle_counter.rs b/src/hardware/cycle_counter.rs
index 53535ff..fab196b 100644
--- a/src/hardware/cycle_counter.rs
+++ b/src/hardware/cycle_counter.rs
@@ -2,13 +2,29 @@ use rtic::cyccnt::{Duration, Instant, U32Ext};
 
 use stm32h7xx_hal::time::Hertz;
 
+/// A simple clock for counting elapsed milliseconds.
 pub struct CycleCounter {
+
+    // The time of the next millisecond in the system.
     next_tick: Option<Instant>,
+
+    // The number of elapsed milliseconds recorded.
     ticks: u32,
+
+    // The increment amount of clock cycles for each elapsed millisecond.
     increment: Duration,
 }
 
 impl CycleCounter {
+
+    /// Construct the cycle counting clock.
+    ///
+    /// # Args
+    /// * `dwt` - The debug watch and trace unit of the CPU core.
+    /// * `cpu_frequency` - The frequency that the cycle counter counts at.
+    ///
+    /// # Returns
+    /// A clock that can be used for measuring elapsed milliseconds.
     pub fn new(
         mut dwt: cortex_m::peripheral::DWT,
         cpu_frequency: impl Into<Hertz>,
@@ -24,6 +40,18 @@ impl CycleCounter {
         }
     }
 
+    /// Get the current number of milliseconds elapsed in the system.
+    ///
+    /// # Note
+    /// This function must be called more often than once per 10 seconds to prevent internal
+    /// wrapping of the cycle counter.
+    ///
+    /// The internal millisecond accumulator will overflow just shy of every 50 days.
+    ///
+    /// This function does not start counting milliseconds until the very first invocation.
+    ///
+    /// # Returns
+    /// The number of elapsed milliseconds since the system started.
     pub fn current_ms(&mut self) -> u32 {
         if self.next_tick.is_none() {
             self.next_tick = Some(Instant::now() + self.increment);