Add details for all the other monotonic implementations.

6 files changed, 51 insertions, 24 deletions

diff --git a/rtic-monotonics/src/imxrt.rs b/rtic-monotonics/src/imxrt.rs
index d59e91e..04556f6 100644
--- a/rtic-monotonics/src/imxrt.rs
+++ b/rtic-monotonics/src/imxrt.rs
@@ -4,6 +4,9 @@
 //!
 //! ```
 //! use rtic_monotonics::imxrt::prelude::*;
+//!
+//! // Create the type `Mono`. It will manage the GPT1 timer, and
+//! // run with a resolution of 1 µs (1,000,000 ticks per second).
 //! imxrt_gpt1_monotonic!(Mono, 1_000_000);
 //!
 //! fn init() {
@@ -19,8 +22,9 @@
 //!
 //! async fn usage() {
 //!     loop {
-//!          // Use the monotonic
+//!          // You can use the monotonic to get the time...
 //!          let timestamp = Mono::now();
+//!          // ...and you can use it to add a delay to this async function
 //!          Mono::delay(100.millis()).await;
 //!     }
 //! }
diff --git a/rtic-monotonics/src/nrf/rtc.rs b/rtic-monotonics/src/nrf/rtc.rs
index f76e319..b63364b 100644
--- a/rtic-monotonics/src/nrf/rtc.rs
+++ b/rtic-monotonics/src/nrf/rtc.rs
@@ -4,19 +4,24 @@
 //!
 //! ```
 //! use rtic_monotonics::nrf::rtc::prelude::*;
+//!
+//! // Create the type `Mono`. It will manage the RTC timer, and
+//! // run with a resolution of 30.517 µs (32,768 ticks per second).
 //! nrf_rtc0_monotonic!(Mono);
 //!
 //! fn init() {
 //!     # // This is normally provided by the selected PAC
-//!     # let rtc = unsafe { core::mem::transmute(()) };
-//!     // Start the monotonic
-//!     Mono::start(rtc);
+//!     # let RTC0 = unsafe { core::mem::transmute(()) };
+//!     // Start the monotonic, passing ownership of the appropriate RTC object
+//!     // relevant nRF52x PAC.
+//!     Mono::start(RTC0);
 //! }
 //!
 //! async fn usage() {
 //!     loop {
-//!          // Use the monotonic
+//!          // You can use the monotonic to get the time...
 //!          let timestamp = Mono::now();
+//!          // ...and you can use it to add a delay to this async function
 //!          Mono::delay(100.millis()).await;
 //!     }
 //! }
diff --git a/rtic-monotonics/src/nrf/timer.rs b/rtic-monotonics/src/nrf/timer.rs
index 6bf1968..bd41496 100644
--- a/rtic-monotonics/src/nrf/timer.rs
+++ b/rtic-monotonics/src/nrf/timer.rs
@@ -7,19 +7,24 @@
 //!
 //! ```
 //! use rtic_monotonics::nrf::timer::prelude::*;
-//! nrf_timer0_monotonic!(Mono);
+//!
+//! // Create the type `Mono`. It will manage the TIMER0 timer, and
+//! // run with a resolution of 1 µs (1,000,000 ticks per second).
+//! nrf_timer0_monotonic!(Mono, 1_000_000);
 //!
 //! fn init() {
 //!     # // This is normally provided by the selected PAC
-//!     # let timer = unsafe { core::mem::transmute(()) };
-//!     // Start the monotonic
-//!     Mono::start(timer);
+//!     # let TIMER0 = unsafe { core::mem::transmute(()) };
+//!     // Start the monotonic, passing ownership of a TIMER0 object from the
+//!     // relevant nRF52x PAC.
+//!     Mono::start(TIMER0);
 //! }
 //!
 //! async fn usage() {
 //!     loop {
-//!          // Use the monotonic
+//!          // You can use the monotonic to get the time...
 //!          let timestamp = Mono::now();
+//!          // ...and you can use it to add a delay to this async function
 //!          Mono::delay(100.millis()).await;
 //!     }
 //! }
diff --git a/rtic-monotonics/src/rp2040.rs b/rtic-monotonics/src/rp2040.rs
index b04376c..6f8cb2b 100644
--- a/rtic-monotonics/src/rp2040.rs
+++ b/rtic-monotonics/src/rp2040.rs
@@ -7,21 +7,25 @@
 //! ```
 //! use rtic_monotonics::rp2040::prelude::*;
 //!
+//! // Create the type `Mono`. It will manage the TIMER peripheral,
+//! // which is a 1 MHz, 64-bit timer.
 //! rp2040_timer_monotonic!(Mono);
 //!
 //! fn init() {
 //!     # // This is normally provided by the selected PAC
-//!     # let timer = unsafe { core::mem::transmute(()) };
-//!     # let mut resets = unsafe { core::mem::transmute(()) };
+//!     # let TIMER = unsafe { core::mem::transmute(()) };
+//!     # let mut RESETS = unsafe { core::mem::transmute(()) };
 //!     #
-//!     // Start the monotonic
-//!     Mono::start(timer, &mut resets);
+//!     // Start the monotonic - passing ownership of an rp2040_pac object for
+//!     // TIMER0, and temporary access to one for the RESET peripheral.
+//!     Mono::start(TIMER, &mut RESETS);
 //! }
 //!
 //! async fn usage() {
 //!     loop {
-//!          // Use the monotonic
+//!          // You can use the monotonic to get the time...
 //!          let timestamp = Mono::now();
+//!          // ...and you can use it to add a delay to this async function
 //!          Mono::delay(100.millis()).await;
 //!     }
 //! }
diff --git a/rtic-monotonics/src/rp235x.rs b/rtic-monotonics/src/rp235x.rs
index 7624d1d..d58139a 100644
--- a/rtic-monotonics/src/rp235x.rs
+++ b/rtic-monotonics/src/rp235x.rs
@@ -8,21 +8,25 @@
 //! ```
 //! use rtic_monotonics::rp235x::prelude::*;
 //!
+//! // Create the type `Mono`. It will manage the TIMER0 peripheral,
+//! // which is a 1 MHz, 64-bit timer.
 //! rp235x_timer_monotonic!(Mono);
 //!
 //! fn init() {
 //!     # // This is normally provided by the selected PAC
-//!     # let timer = unsafe { core::mem::transmute(()) };
-//!     # let mut resets = unsafe { core::mem::transmute(()) };
+//!     # let TIMER = unsafe { core::mem::transmute(()) };
+//!     # let mut RESETS = unsafe { core::mem::transmute(()) };
 //!     #
-//!     // Start the monotonic
-//!     Mono::start(timer, &mut resets);
+//!     // Start the monotonic - passing ownership of an rp235x_pac object for
+//!     // TIMER0, and temporary access to one for the RESET peripheral.
+//!     Mono::start(TIMER, &mut RESETS);
 //! }
 //!
 //! async fn usage() {
 //!     loop {
-//!          // Use the monotonic
+//!          // You can use the monotonic to get the time...
 //!          let timestamp = Mono::now();
+//!          // ...and you can use it to add a delay to this async function
 //!          Mono::delay(100.millis()).await;
 //!     }
 //! }
diff --git a/rtic-monotonics/src/stm32.rs b/rtic-monotonics/src/stm32.rs
index fbcee0c..e6cb71b 100644
--- a/rtic-monotonics/src/stm32.rs
+++ b/rtic-monotonics/src/stm32.rs
@@ -8,23 +8,28 @@
 //! ```
 //! use rtic_monotonics::stm32::prelude::*;
 //!
-//! // Define the monotonic and set it to 1MHz tick rate
+//! // Create the type `Mono`. It will manage the TIM2 timer, and
+//! // run with a resolution of 1 µs (1,000,000 ticks per second).
 //! stm32_tim2_monotonic!(Mono, 1_000_000);
 //!
 //! fn init() {
 //!     // If using `embassy-stm32` HAL, timer clock can be read out like this:
 //!     let timer_clock_hz = embassy_stm32::peripherals::TIM2::frequency();
-//!     // Or define it manually if you are using other HAL or know correct frequency:
+//!     // Or define it manually if you are using another HAL or know the
+//!     // correct frequency:
 //!     let timer_clock_hz = 64_000_000;
 //!
-//!     // Start the monotonic
+//!     // Start the monotonic. The TIM2 prescaler is calculated from the
+//!     // clock frequency given here, and the resolution given to the
+//!     // `stm32_tim2_monotonic!` macro call above. No PAC object is required.
 //!     Mono::start(timer_clock_hz);
 //! }
 //!
 //! async fn usage() {
 //!     loop {
-//!          // Use the monotonic
+//!          // You can use the monotonic to get the time...
 //!          let timestamp = Mono::now();
+//!          // ...and you can use it to add a delay to this async function
 //!          Mono::delay(100.millis()).await;
 //!     }
 //! }