Add docs for Hertz structs

src/lib.rs

@@ -63,6 +63,7 @@
 //! [README]: https://github.com/stm32-rs/stm32f1xx-hal/tree/v0.5.3
 
 #![no_std]
+#![deny(intra_doc_link_resolution_failure)]
 
 // If no target specified, print error message.
 #[cfg(not(any(feature = "stm32f100", feature = "stm32f101", feature = "stm32f103")))]

src/time.rs

@@ -1,4 +1,31 @@
 //! Time units
+//!
+//! See [`Hertz`], [`KiloHertz`] and [`MegaHertz`] for creating increasingly higher frequencies.
+//!
+//! The [`U32Ext`] trait adds various methods like `.hz()`, `.mhz()`, etc to the `u32` primitive type,
+//! allowing it to be converted into frequencies.
+//!
+//! # Examples
+//!
+//! ## Create a 2 MHz frequency
+//!
+//! This example demonstrates various ways of creating a 2 MHz (2_000_000 Hz) frequency. They are
+//! all equivalent, however the `2.mhz()` variant should be preferred for readability.
+//!
+//! ```rust
+//! use stm32f1xx_hal::{
+//!     time::Hertz,
+//!     // Imports U32Ext trait
+//!     prelude::*,
+//! };
+//!
+//! let freq_hz = 2_000_000.hz();
+//! let freq_khz = 2_000.khz();
+//! let freq_mhz = 2.mhz();
+//!
+//! assert_eq!(freq_hz, freq_khz);
+//! assert_eq!(freq_khz, freq_mhz);
+//! ```
 
 use cortex_m::peripheral::DWT;
 
@@ -9,14 +36,64 @@ use crate::rcc::Clocks;
 pub struct Bps(pub u32);
 
 /// Hertz
+///
+/// Create a frequency specified in [Hertz](https://en.wikipedia.org/wiki/Hertz).
+///
+/// See also [`KiloHertz`] and [`MegaHertz`] for semantically correct ways of creating higher
+/// frequencies.
+///
+/// # Examples
+///
+/// ## Create an 60 Hz frequency
+///
+/// ```rust
+/// use stm32f1xx_hal::time::Hertz;
+///
+/// let freq = 60.hz();
+/// ```
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub struct Hertz(pub u32);
 
-/// KiloHertz
+/// Kilohertz
+///
+/// Create a frequency specified in kilohertz.
+///
+/// See also [`Hertz`] and [`MegaHertz`] for semantically correct ways of creating lower or higher
+/// frequencies.
+///
+/// # Examples
+///
+/// ## Create a 100 Khz frequency
+///
+/// This example creates a 100 KHz frequency. This could be used to set an I2C data rate or PWM
+/// frequency, etc.
+///
+/// ```rust
+/// use stm32f1xx_hal::time::Hertz;
+///
+/// let freq = 100.khz();
+/// ```
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub struct KiloHertz(pub u32);
 
-/// MegaHertz
+/// Megahertz
+///
+/// Create a frequency specified in kilohertz.
+///
+/// See also [`Hertz`] and [`KiloHertz`] for semantically correct ways of creating lower
+/// frequencies.
+///
+/// # Examples
+///
+/// ## Create a an 8 MHz frequency
+///
+/// This example creates an 8 MHz frequency that could be used to configure an SPI peripheral, etc.
+///
+/// ```rust
+/// use stm32f1xx_hal::time::Hertz;
+///
+/// let freq = 8.mhz();
+/// ```
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub struct MegaHertz(pub u32);