Assorted doc improvements (#1507)

* Assorted doc improvements

* Fix `missing_docs`

* Remove unnecessary `mut`

* Chip specific ESP-IDF link for ETM and RNG

* Move `chip!` macro to soc-module

esp-hal/src/embassy/executor/interrupt.rs

@@ -54,7 +54,7 @@ impl CallbackContext {
 }
 
 fn handle_interrupt<const NUM: u8>() {
-    let mut swi = unsafe { SoftwareInterrupt::<NUM>::steal() };
+    let swi = unsafe { SoftwareInterrupt::<NUM>::steal() };
     swi.reset();
 
     unsafe {

esp-hal/src/etm.rs

@@ -18,8 +18,8 @@
 //! a particular Event to a particular Task. When an event is activated, the ETM
 //! channel will trigger the corresponding task automatically.
 //!
-//! More information: <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c6/api-reference/peripherals/etm.html>
-//!
+//! For more information, please refer to the
+#![doc = concat!("[ESP-IDF documentation](https://docs.espressif.com/projects/esp-idf/en/latest/", crate::soc::chip!(), "/api-reference/peripherals/etm.html)")]
 //! ## Example
 //! ```no_run
 //! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);

esp-hal/src/mcpwm/timer.rs

@@ -17,7 +17,7 @@ use crate::{
 
 /// A MCPWM timer
 ///
-/// Every timer of a particular [`MCPWM`](super::MCPWM) peripheral can be used
+/// Every timer of a particular [`MCPWM`](super::McPwm) peripheral can be used
 /// as a timing reference for every
 /// [`Operator`](super::operator::Operator) of that peripheral
 pub struct Timer<const TIM: u8, PWM> {

esp-hal/src/rmt.rs

@@ -1,41 +1,41 @@
 //! # Remote Control Peripheral (RMT)
 //!
 //! ## Overview
-//! Some ESP32 bitss include a remote control peripheral (RMT) that
-//! is designed to handle infrared remote control signals. For that
-//! purpose, it can convert bitstreams of data (from the RAM) into
-//! pulse codes and even modulate those codes into a carrier wave.
+//! The RMT (Remote Control Transceiver) peripheral was designed to act as an
+//! infrared transceiver. However, due to the flexibility of its data format,
+//! RMT can be extended to a versatile and general-purpose transceiver,
+//! transmitting or receiving many other types of signals.
 //!
-//! It can also convert received pulse codes (again, with carrier
-//! wave support) into data bits.
 //!
-//! A secondary use case for this peripheral is to drive RGB(W) LEDs
-//! that bear an internal IC and use a pulse code protocol.
+//! Typically, the RMT peripheral can be used in the following scenarios:
+//! - Transmit or receive infrared signals, with any IR protocols, e.g., NEC
+//! - General-purpose sequence generator
+//! - Transmit signals in a hardware-controlled loop, with a finite or infinite
+//!   number of times
+//! - Modulate the carrier to the output signal or demodulate the carrier from
+//!   the input signal
 //!
 //! ## Channels
-//! The RMT peripheral has the following channels available
-//! on individual chips:
-//!
-//! * The **ESP32** has 8 channels, each of them can be either receiver or
-//!   transmitter
-//! * The **ESP32-C3** has 4 channels, `Channel<0>` and `Channel<1>` hardcoded
-//!   for transmitting signals and `Channel<2>` and `Channel<3>` hardcoded for
-//!   receiving signals.
-//! * The **ESP32-C6** has 4 channels, `Channel<0>` and `Channel<1>` hardcoded
-//!   for transmitting signals and `Channel<2>` and `Channel<3>` hardcoded for
-//!   receiving signals.
-//! * The **ESP32-H2** has 4 channels, `Channel<0>` and `Channel<1>` hardcoded
-//!   for transmitting signals and `Channel<2>` and `Channel<3>` hardcoded for
-//!   receiving signals.
-//! * The **ESP32-S2** has 4 channels, each of them can be either receiver or
-//!   transmitter.
-//! * The **ESP32-S3** has 8 channels, `Channel<0>`-`Channel<3>` hardcoded for
-//!   transmitting signals and `Channel<4>`-`Channel<7>` hardcoded for receiving
-//!   signals.
-//!
-//! For more information, please refer to the ESP-IDF documentation:
-//! <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/rmt.html>
-//!
+//! There are
+#![cfg_attr(
+    esp32,
+    doc = "8 channels, each of them can be either receiver or transmitter"
+)]
+#![cfg_attr(
+    esp32s2,
+    doc = "4 channels, each of them can be either receiver or transmitter"
+)]
+#![cfg_attr(
+    esp32s3,
+    doc = "8 channels, `Channel<0>`-`Channel<3>` hardcoded for transmitting signals and `Channel<4>`-`Channel<7>` hardcoded for receiving signals"
+)]
+#![cfg_attr(
+    any(esp32c3, esp32c6, esp32h2),
+    doc = "4 channels, `Channel<0>` and `Channel<1>` hardcoded for transmitting signals and `Channel<2>` and `Channel<3>` hardcoded for receiving signals."
+)]
+#![doc = "  "]
+//! For more information, please refer to the
+#![doc = concat!("[ESP-IDF documentation](https://docs.espressif.com/projects/esp-idf/en/latest/", crate::soc::chip!(), "/api-reference/peripherals/rmt.html)")]
 //! ## Examples
 //!
 //! ### Initialization
@@ -82,6 +82,7 @@
 //! let transaction = channel.transmit(&data);
 //! channel = transaction.wait().unwrap();
 //! ```
+#![warn(missing_docs)]
 
 use core::marker::PhantomData;
 
@@ -97,12 +98,17 @@ use crate::{
     system::PeripheralClockControl,
 };
 
+/// Errors
 #[derive(Debug, Clone, Copy, PartialEq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
+    /// The desired frequency is impossible to reach
     UnreachableTargetFrequency,
+    /// The amount of pulses exceeds the size of the FIFO
     Overflow,
+    /// An argument is invalid
     InvalidArgument,
+    /// An error occurred during transmission
     TransmissionError,
 }
 
@@ -211,7 +217,7 @@ impl<'d, M> Rmt<'d, M>
 where
     M: crate::Mode,
 {
-    pub fn new_internal(
+    pub(crate) fn new_internal(
         peripheral: impl Peripheral<P = crate::peripherals::RMT> + 'd,
         frequency: HertzU32,
         _clocks: &Clocks,
@@ -295,6 +301,7 @@ impl<'d> Rmt<'d, crate::Async> {
     }
 }
 
+/// Creates a TX channel
 pub trait TxChannelCreator<'d, T, P>
 where
     P: OutputPin,
@@ -325,6 +332,7 @@ where
     }
 }
 
+/// Creates a TX channel in async mode
 #[cfg(feature = "async")]
 pub trait TxChannelCreatorAsync<'d, T, P>
 where
@@ -356,6 +364,7 @@ where
     }
 }
 
+/// Creates a RX channel
 pub trait RxChannelCreator<'d, T, P>
 where
     P: InputPin,
@@ -401,6 +410,7 @@ where
     }
 }
 
+/// Creates a RX channel in async mode
 #[cfg(feature = "async")]
 pub trait RxChannelCreatorAsync<'d, T, P>
 where
@@ -573,6 +583,7 @@ where
         Ok(self.channel)
     }
 
+    /// Check if the `loopcount` interrupt bit is set
     pub fn is_loopcount_interrupt_set(&self) -> bool {
         <C as private::TxChannelInternal<crate::Blocking>>::is_loopcount_interrupt_set()
     }
@@ -634,6 +645,7 @@ mod impl_for_chip {
     use crate::peripheral::{Peripheral, PeripheralRef};
 
     /// RMT Instance
+    #[allow(missing_docs)]
     pub struct Rmt<'d, M>
     where
         M: crate::Mode,
@@ -700,6 +712,7 @@ mod impl_for_chip {
     use crate::peripheral::{Peripheral, PeripheralRef};
 
     /// RMT Instance
+    #[allow(missing_docs)]
     pub struct Rmt<'d, M>
     where
         M: crate::Mode,
@@ -806,6 +819,7 @@ mod impl_for_chip {
     use crate::peripheral::{Peripheral, PeripheralRef};
 
     /// RMT Instance
+    #[allow(missing_docs)]
     pub struct Rmt<'d, M>
     where
         M: crate::Mode,
@@ -880,6 +894,7 @@ mod impl_for_chip {
     use crate::peripheral::{Peripheral, PeripheralRef};
 
     /// RMT Instance
+    #[allow(missing_docs)]
     pub struct Rmt<'d, M>
     where
         M: crate::Mode,
@@ -972,6 +987,7 @@ where
     phantom: PhantomData<M>,
 }
 
+/// Channel in TX mode
 pub trait TxChannel: private::TxChannelInternal<crate::Blocking> {
     /// Start transmitting the given pulse code sequence.
     /// This returns a [`SingleShotTxTransaction`] which can be used to wait for
@@ -1064,6 +1080,7 @@ where
     }
 }
 
+/// Channel is RX mode
 pub trait RxChannel: private::RxChannelInternal<crate::Blocking> {
     /// Start receiving pulse codes into the given buffer.
     /// This returns a [RxTransaction] which can be used to wait for receive to
@@ -1086,6 +1103,7 @@ pub trait RxChannel: private::RxChannelInternal<crate::Blocking> {
     }
 }
 
+/// Async functionality
 #[cfg(feature = "async")]
 pub mod asynch {
     use core::{
@@ -1141,6 +1159,7 @@ pub mod asynch {
         }
     }
 
+    /// TX channel in async mode
     pub trait TxChannelAsync: private::TxChannelInternal<crate::Async> {
         /// Start transmitting the given pulse code sequence.
         /// The length of sequence cannot exceed the size of the allocated RMT
@@ -1202,6 +1221,7 @@ pub mod asynch {
         }
     }
 
+    /// RX channel in async mode
     pub trait RxChannelAsync: private::RxChannelInternal<crate::Async> {
         /// Start receiving a pulse code sequence.
         /// The length of sequence cannot exceed the size of the allocated RMT

esp-hal/src/rng.rs

@@ -39,9 +39,8 @@
 //! If none of the above conditions are true, the output of the RNG should be
 //! considered pseudo-random only.
 //!
-//! For more information, please refer to the ESP-IDF documentation:  
-//! <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/random.html>
-//!
+//! For more information, please refer to the
+#![doc = concat!("[ESP-IDF documentation](https://docs.espressif.com/projects/esp-idf/en/latest/", crate::soc::chip!(), "/api-reference/system/random.html)")]
 //! # Examples
 //!
 //! ## Initialization

esp-hal/src/soc/esp32/mod.rs

@@ -18,6 +18,14 @@ pub mod peripherals;
 pub mod psram;
 pub mod radio_clocks;
 
+macro_rules! chip {
+    () => {
+        "esp32"
+    };
+}
+
+pub(crate) use chip;
+
 pub(crate) mod constants {
     pub const I2S_SCLK: u32 = 160_000_000;
     pub const I2S_DEFAULT_CLK_SRC: u32 = 2;

esp-hal/src/soc/esp32c2/mod.rs

@@ -13,6 +13,14 @@ pub mod gpio;
 pub mod peripherals;
 pub mod radio_clocks;
 
+macro_rules! chip {
+    () => {
+        "esp32c2"
+    };
+}
+
+pub(crate) use chip;
+
 #[allow(unused)]
 pub(crate) mod registers {
     pub const INTERRUPT_MAP_BASE: u32 = 0x600c2000;

esp-hal/src/soc/esp32c3/mod.rs

@@ -17,6 +17,14 @@ pub mod gpio;
 pub mod peripherals;
 pub mod radio_clocks;
 
+macro_rules! chip {
+    () => {
+        "esp32c2"
+    };
+}
+
+pub(crate) use chip;
+
 #[allow(unused)]
 pub(crate) mod registers {
     pub const INTERRUPT_MAP_BASE: u32 = 0x600c2000;

esp-hal/src/soc/esp32c6/mod.rs

@@ -19,6 +19,14 @@ pub mod lp_core;
 pub mod peripherals;
 pub mod radio_clocks;
 
+macro_rules! chip {
+    () => {
+        "esp32c6"
+    };
+}
+
+pub(crate) use chip;
+
 #[allow(unused)]
 pub(crate) mod registers {
     pub const INTERRUPT_MAP_BASE: u32 = 0x60010000;

esp-hal/src/soc/esp32h2/mod.rs

@@ -18,6 +18,14 @@ pub mod gpio;
 pub mod peripherals;
 pub mod radio_clocks;
 
+macro_rules! chip {
+    () => {
+        "esp32h2"
+    };
+}
+
+pub(crate) use chip;
+
 #[allow(unused)]
 pub(crate) mod registers {
     pub const INTERRUPT_MAP_BASE: u32 = 0x60010000;

esp-hal/src/soc/esp32s2/mod.rs

@@ -23,6 +23,14 @@ pub mod radio_clocks;
 
 pub mod ulp_core;
 
+macro_rules! chip {
+    () => {
+        "esp32s2"
+    };
+}
+
+pub(crate) use chip;
+
 pub(crate) mod constants {
     pub const I2S_SCLK: u32 = 160_000_000;
     pub const I2S_DEFAULT_CLK_SRC: u32 = 2;

esp-hal/src/soc/esp32s3/mod.rs

@@ -24,6 +24,14 @@ pub mod radio_clocks;
 
 pub mod ulp_core;
 
+macro_rules! chip {
+    () => {
+        "esp32s3"
+    };
+}
+
+pub(crate) use chip;
+
 pub(crate) mod constants {
     pub const I2S_SCLK: u32 = 160_000_000;
     pub const I2S_DEFAULT_CLK_SRC: u8 = 2;

esp-hal/src/spi/master.rs

@@ -417,7 +417,7 @@ where
     /// sequential transfers are performed. This function will return before
     /// all bytes of the last chunk to transmit have been sent to the wire. If
     /// you must ensure that the whole messages was written correctly, use
-    /// [`Self::flush`].
+    /// `flush`.
     pub fn write_bytes(&mut self, words: &[u8]) -> Result<(), Error> {
         self.spi.write_bytes(words)?;
         self.spi.flush()?;

esp-hal/src/time.rs

@@ -10,10 +10,10 @@
 ///
 /// The counter won’t measure time in sleep-mode.
 ///
-/// The timer will wrap after:
-/// - ESP32 = 36_558 years,
-/// - ESP32-S2 = 7_311 years,
-/// - others = > 7 years
+/// The timer will wrap after
+#[cfg_attr(esp32, doc = "36_558 years")]
+#[cfg_attr(esp32s2, doc = "7_311 years")]
+#[cfg_attr(not(any(esp32, esp32s2)), doc = "more than 7 years")]
 pub fn current_time() -> fugit::Instant<u64, 1, 1_000_000> {
     #[cfg(esp32)]
     let (ticks, div) = {