Document the system_clock module

Author: phil-opp

src/system_clock.rs

@@ -1,3 +1,5 @@
+//! Provides initialization and time-keeping functions for the system clock (`systick`).
+
 use core::convert::TryFrom;
 use core::sync::atomic::{AtomicUsize, Ordering};
 use stm32f7::stm32f7x6::{RCC, SYST};
@@ -6,28 +8,49 @@ static TICKS: AtomicUsize = AtomicUsize::new(0);
 static SYSTEM_CLOCK_SPEED: AtomicUsize = AtomicUsize::new(0);
 static FREQUENCY: AtomicUsize = AtomicUsize::new(0);
 
+/// Increases the global tick count by 1.
 pub fn tick() {
     TICKS.fetch_add(1, Ordering::AcqRel);
 }
 
+/// Returns the current global tick count.
 pub fn ticks() -> usize {
     TICKS.load(Ordering::Acquire)
 }
 
+/// Returns the elapsed milliseconds since [`tick()`] was first called.
+///
+/// [`tick()`]: self::tick
 pub fn ms() -> usize {
     ticks_to_ms(ticks())
 }
 
+/// Wait for the specified number of ticks.
+///
+/// This function spins the thread in a while loop until the [`tick()`] function was invoked
+/// `ticks` times.
 pub fn wait_ticks(ticks: usize) {
     let current = self::ticks();
     let desired = current + ticks;
     while self::ticks() != desired {}
 }
 
+/// Wait for the specified number of milliseconds.
+///
+/// This function spins the thread in a while loop until the specified number of milliseconds
+/// have passed. This function is based on [`wait_ticks`] and [`ms_to_ticks`].
+///
+/// [`wait_ticks`]: self::wait_ticks
+/// [`ms_to_ticks`]: self::ms_to_ticks
 pub fn wait_ms(ms: usize) {
     wait_ticks(ms_to_ticks(ms));
 }
 
+/// Initializes the system clock (systick) of the stm32f7-discovery board to the specified
+/// frequency.
+///
+/// After calling this function, the interrupt handler for the systick interrupt should call
+/// [`tick()`] on each invocation to update the global tick counter in this module.
 pub fn init(Hz(frequency): Hz, systick: &mut SYST, rcc: &RCC) {
     use cortex_m::peripheral::syst::SystClkSource;
     use stm32f7::stm32f7x6::rcc::pllcfgr::PLLPR;
@@ -62,19 +85,32 @@ pub fn init(Hz(frequency): Hz, systick: &mut SYST, rcc: &RCC) {
     systick.enable_counter();
 }
 
+/// Returns the frequency of the system clock.
+///
+/// This is the frequency that was passed to [`init`].
+///
+/// [`init`]: self::init
 pub fn system_clock_speed() -> Hz {
     Hz(SYSTEM_CLOCK_SPEED.load(Ordering::Acquire))
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 #[repr(transparent)]
+/// A frequency in Hz.
 pub struct Hz(pub usize);
 
+/// Translates the passed tick number to a number of milliseconds.
+///
+/// Depends on the [`system_clock_speed`](self::system_clock_speed).
 pub fn ticks_to_ms(ticks: usize) -> usize {
     let frequency = FREQUENCY.load(Ordering::Acquire);
     (ticks * 1000) / frequency
 }
 
+
+/// Translates the passed number of milliseconds to a number of ticks.
+///
+/// Depends on the [`system_clock_speed`](self::system_clock_speed).
 pub fn ms_to_ticks(ms: usize) -> usize {
     let frequency = FREQUENCY.load(Ordering::Acquire);
     let ticks_x1000 = frequency * ms;