From 75820c55c2bac702d0ecaf20933429269ff2fb1e Mon Sep 17 00:00:00 2001
From: Rahix <rahix@rahix.de>
Date: Wed, 1 May 2024 16:01:13 +0200
Subject: [PATCH] generic: Improve documentation of clock module

---
 avr-hal-generic/src/clock.rs | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/avr-hal-generic/src/clock.rs b/avr-hal-generic/src/clock.rs
index 5d04d5bc9e..f7588747bc 100644
--- a/avr-hal-generic/src/clock.rs
+++ b/avr-hal-generic/src/clock.rs
@@ -1,4 +1,27 @@
-//! Generic trait for clock speeds
+//! Core clock speed management
+//!
+//! AVR microcontrollers support different core clock speeds.  Peripheral drivers need to know
+//! about this speed to calculate timing parameters.  To make this as efficient as possible, the
+//! clock speed is tracked as a compile-time constant.  This means peripheral drivers can do
+//! compile-time calculation of timing parameters.
+//!
+//! # How To Use
+//! If you are using `arduino-hal`, there is nothing you need to do - the core clock speed is
+//! defined in `arduino-hal` as `arduino_hal::DefaultClock` and the const-generic parameters of all
+//! peripheral drivers are preset to this value.
+//!
+//! If you are using a MCU HAL like `atmega-hal` or `attiny-hal`, you need to take care of clock
+//! speed management manually.  The best way to do this is as follows:
+//!
+//! - Define a "constant" for your core clock speed in the crate root:
+//!   ```ignore
+//!   type CoreClock = atmega_hal::clock::MHz16;
+//!   ```
+//! - Define aliases for peripheral driver types based on this clock:
+//!   ```ignore
+//!   type Adc = atmega_hal::adc::Adc<crate::CoreClock>;
+//!   type I2c = atmega_hal::i2c::I2c<crate::CoreClock>;
+//!   ```
 
 /// A clock speed
 pub trait Clock {