Merge #732

732: Docs 1 r=korken89 a=datdenkikniet

Going over all of the subprojects and trying to find stuff that may need docs

Co-authored-by: datdenkikniet <jcdra1@gmail.com>

7 files changed, 66 insertions, 14 deletions

diff --git a/rtic-monotonics/Cargo.toml b/rtic-monotonics/Cargo.toml
index b9145a2..3c294ea 100644
--- a/rtic-monotonics/Cargo.toml
+++ b/rtic-monotonics/Cargo.toml
@@ -11,10 +11,12 @@ authors = [
   "Per Lindgren <per.lindgren@ltu.se>",
 ]
 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 04ce4e2..507ee64 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 0f6b973..f2fd3f6 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 2e23389..50087ab 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 5e8fe93..6b7ade6 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 8c248f9..ac1fc1a 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 cba9aa2..0f215a7 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
 //!
 //! ```