From 401c636215f02e750939e550bc02622ea7834f3c Mon Sep 17 00:00:00 2001 From: datdenkikniet Date: Thu, 13 Apr 2023 18:10:29 +0200 Subject: [PATCH] rtic-monotonics: Add some docs --- rtic-monotonics/Cargo.toml | 6 ++++-- rtic-monotonics/src/lib.rs | 23 ++++++++++++++++++++++- rtic-monotonics/src/nrf.rs | 2 +- rtic-monotonics/src/nrf/rtc.rs | 13 ++++++++++--- rtic-monotonics/src/nrf/timer.rs | 22 ++++++++++++++++++---- rtic-monotonics/src/rp2040.rs | 2 +- rtic-monotonics/src/systick.rs | 12 ++++++++++-- 7 files changed, 66 insertions(+), 14 deletions(-) diff --git a/rtic-monotonics/Cargo.toml b/rtic-monotonics/Cargo.toml index b9145a245a..3c294ea728 100644 --- a/rtic-monotonics/Cargo.toml +++ b/rtic-monotonics/Cargo.toml @@ -11,10 +11,12 @@ authors = [ "Per Lindgren ", ] categories = ["concurrency", "embedded", "no-std", "asynchronous"] -description = "rtic-monotonics lib TODO" +description = "A library that provides implementations of the Monotonic trait from rtic-time" license = "MIT OR Apache-2.0" -# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html +[package.metadata.docs.rs] +features = ["cortex-m-systick", "rp2040", "nrf52840"] +rustdoc-flags = ["--cfg", "docsrs"] [dependencies] rtic-time = { version = "1.0.0-alpha.1", path = "../rtic-time" } diff --git a/rtic-monotonics/src/lib.rs b/rtic-monotonics/src/lib.rs index 04ce4e2451..507ee64c8b 100644 --- a/rtic-monotonics/src/lib.rs +++ b/rtic-monotonics/src/lib.rs @@ -1,10 +1,31 @@ -//! Crate +//! In-tree implementations of the [`rtic_time::Monotonic`] (reexported) trait for +//! timers & clocks found on commonly used microcontrollers. +//! +//! To enable the implementations, you must enable a feature for the specific MCU you're targeting. +//! +//! # Cortex-M Systick +//! The [`systick`] monotonic works on all cortex-M parts, and requires that the feature `cortex-m-systick` is enabled. +//! +//! # RP2040 +//! The RP2040 monotonics require that the `rp2040` feature is enabled. +//! +//! # nRF +//! nRF monotonics require that one of the available `nrf52*` features is enabled. +//! +//! All implementations of timers for the nRF52 family are documented here. Monotonics that +//! are not available on all parts in this family will have an `Available on crate features X only` +//! tag, describing what parts _do_ support that monotonic. Monotonics without an +//! `Available on crate features X only` tag are available on any `nrf52*` feature. +//! +// To build these docs correctly: +// RUSTFLAGS="--cfg docsrs" cargo doc --featuers cortex-m-systick,rp2040,nrf52840 #![no_std] #![deny(missing_docs)] //deny_warnings_placeholder_for_ci #![allow(incomplete_features)] #![feature(async_fn_in_trait)] +#![cfg_attr(docsrs, feature(doc_cfg))] pub use rtic_time::{Monotonic, TimeoutError, TimerQueue}; diff --git a/rtic-monotonics/src/nrf.rs b/rtic-monotonics/src/nrf.rs index 0f6b97370d..f2fd3f6fcd 100644 --- a/rtic-monotonics/src/nrf.rs +++ b/rtic-monotonics/src/nrf.rs @@ -1,4 +1,4 @@ -//! Monotonic implementations for the nRF series of MCUs. +//! [`Monotonic`](super::Monotonic) implementations for the nRF series of MCUs. pub mod rtc; pub mod timer; diff --git a/rtic-monotonics/src/nrf/rtc.rs b/rtic-monotonics/src/nrf/rtc.rs index 2e23389f19..50087ab644 100644 --- a/rtic-monotonics/src/nrf/rtc.rs +++ b/rtic-monotonics/src/nrf/rtc.rs @@ -1,4 +1,4 @@ -//! RTIC Monotonic impl for the nRF RTCs. +//! [`Monotonic`] implementation for the nRF Real Time Clocks (RTC). //! //! # Example //! @@ -82,6 +82,10 @@ macro_rules! create_nrf_rtc1_monotonic_token { /// Register the Rtc2 interrupt for the monotonic. #[cfg(any(feature = "nrf52832", feature = "nrf52833", feature = "nrf52840"))] +#[cfg_attr( + docsrs, + doc(cfg(any(feature = "nrf52832", feature = "nrf52833", feature = "nrf52840"))) +)] #[macro_export] macro_rules! create_nrf_rtc2_monotonic_token { () => {{ @@ -90,8 +94,11 @@ macro_rules! create_nrf_rtc2_monotonic_token { } macro_rules! make_rtc { - ($mono_name:ident, $rtc:ident, $overflow:ident, $tq:ident) => { + ($mono_name:ident, $rtc:ident, $overflow:ident, $tq:ident$(, doc: ($($doc:tt)*))?) => { /// Monotonic timer queue implementation. + $( + #[cfg_attr(docsrs, doc(cfg($($doc)*)))] + )? pub struct $mono_name; static $overflow: AtomicU32 = AtomicU32::new(0); @@ -243,4 +250,4 @@ macro_rules! make_rtc { make_rtc!(Rtc0, RTC0, RTC0_OVERFLOWS, RTC0_TQ); make_rtc!(Rtc1, RTC1, RTC1_OVERFLOWS, RTC1_TQ); #[cfg(any(feature = "nrf52832", feature = "nrf52833", feature = "nrf52840"))] -make_rtc!(Rtc2, RTC2, RTC2_OVERFLOWS, RTC2_TQ); +make_rtc!(Rtc2, RTC2, RTC2_OVERFLOWS, RTC2_TQ, doc: (any(feature = "nrf52832", feature = "nrf52833", feature = "nrf52840"))); diff --git a/rtic-monotonics/src/nrf/timer.rs b/rtic-monotonics/src/nrf/timer.rs index 5e8fe932b4..6b7ade6a0c 100644 --- a/rtic-monotonics/src/nrf/timer.rs +++ b/rtic-monotonics/src/nrf/timer.rs @@ -1,4 +1,7 @@ -//! Monotonic impl for the 32-bit timers of the nRF series. +//! [`Monotonic`] impl for the 32-bit timers of the nRF series. +//! +//! Not all timers are available on all parts. Ensure that only the available +//! timers are exposed by having the correct `nrf52*` feature enabled for `rtic-monotonic`. //! //! # Example //! @@ -95,6 +98,10 @@ macro_rules! create_nrf_timer2_monotonic_token { } /// Register the Timer3 interrupt for the monotonic. +#[cfg_attr( + docsrs, + doc(cfg(any(feature = "nrf52832", feature = "nrf52833", feature = "nrf52840"))) +)] #[cfg(any(feature = "nrf52832", feature = "nrf52833", feature = "nrf52840"))] #[macro_export] macro_rules! create_nrf_timer3_monotonic_token { @@ -104,6 +111,10 @@ macro_rules! create_nrf_timer3_monotonic_token { } /// Register the Timer4 interrupt for the monotonic. +#[cfg_attr( + docsrs, + doc(cfg(any(feature = "nrf52832", feature = "nrf52833", feature = "nrf52840"))) +)] #[cfg(any(feature = "nrf52832", feature = "nrf52833", feature = "nrf52840"))] #[macro_export] macro_rules! create_nrf_timer4_monotonic_token { @@ -113,8 +124,11 @@ macro_rules! create_nrf_timer4_monotonic_token { } macro_rules! make_timer { - ($mono_name:ident, $timer:ident, $overflow:ident, $tq:ident) => { + ($mono_name:ident, $timer:ident, $overflow:ident, $tq:ident$(, doc: ($($doc:tt)*))?) => { /// Monotonic timer queue implementation. + $( + #[cfg_attr(docsrs, doc(cfg($($doc)*)))] + )? pub struct $mono_name; static $overflow: AtomicU32 = AtomicU32::new(0); @@ -274,6 +288,6 @@ make_timer!(Timer0, TIMER0, TIMER0_OVERFLOWS, TIMER0_TQ); make_timer!(Timer1, TIMER1, TIMER1_OVERFLOWS, TIMER1_TQ); make_timer!(Timer2, TIMER2, TIMER2_OVERFLOWS, TIMER2_TQ); #[cfg(any(feature = "nrf52832", feature = "nrf52833", feature = "nrf52840"))] -make_timer!(Timer3, TIMER3, TIMER3_OVERFLOWS, TIMER3_TQ); +make_timer!(Timer3, TIMER3, TIMER3_OVERFLOWS, TIMER3_TQ, doc: (any(feature = "nrf52832", feature = "nrf52833", feature = "nrf52840"))); #[cfg(any(feature = "nrf52832", feature = "nrf52833", feature = "nrf52840"))] -make_timer!(Timer4, TIMER4, TIMER4_OVERFLOWS, TIMER4_TQ); +make_timer!(Timer4, TIMER4, TIMER4_OVERFLOWS, TIMER4_TQ, doc: (any(feature = "nrf52832", feature = "nrf52833", feature = "nrf52840"))); diff --git a/rtic-monotonics/src/rp2040.rs b/rtic-monotonics/src/rp2040.rs index 8c248f9cab..ac1fc1a7a5 100644 --- a/rtic-monotonics/src/rp2040.rs +++ b/rtic-monotonics/src/rp2040.rs @@ -1,4 +1,4 @@ -//! A monotonic implementation for RP2040's Timer peripheral. +//! [`Monotonic`] implementation for RP2040's Timer peripheral. //! //! # Example //! diff --git a/rtic-monotonics/src/systick.rs b/rtic-monotonics/src/systick.rs index cba9aa290d..0f215a7c3c 100644 --- a/rtic-monotonics/src/systick.rs +++ b/rtic-monotonics/src/systick.rs @@ -1,6 +1,14 @@ -//! A monotonics based on Cortex-M SysTick. Note that this implementation is inefficient as it -//! ticks, and generates interrupts, at a constant rate. +//! [`Monotonic`] based on Cortex-M SysTick. Note: this implementation is inefficient as it +//! ticks and generates interrupts at a constant rate. //! +//! Currently, the following tick rates are supported: +//! +//! | Feature | Tick rate | Precision | +//! |:----------------:|----------:|----------:| +//! | (none / default) | 1 Hz | 1 ms | +//! | systick-100hz | 100 Hz | 10 ms | +//! | systick-10khz | 10 KHz | 0.1 ms | + //! # Example //! //! ```