From 117eb45fa0829239da9152b9cf54c3cf706dc76d Mon Sep 17 00:00:00 2001
From: Ralph Ursprung <ralph.ursprung@gmail.com>
Date: Thu, 15 May 2025 17:53:31 +0200
Subject: [PATCH] add the possibility to document `bind_interrupts` `struct`s

the `bind_interrupts` macro creates a `struct` for the interrupts. it
was so far not possible to document those (except for STM32) and there
was no generic documentation being generated/added either, thus the
`missing_docs` lint was triggered for consumers which enabled it.

with this change it is now possible to manually add a comment on the
`struct` being defined in the macro invocation.

to show that this works one RP example has been modified accordingly.
---
 embassy-imxrt/src/lib.rs   | 12 ++++++++----
 embassy-nrf/src/lib.rs     | 12 ++++++++----
 embassy-rp/src/lib.rs      | 12 ++++++++----
 embassy-stm32/src/lib.rs   | 13 ++++++++-----
 examples/rp/src/bin/adc.rs |  9 ++++++---
 5 files changed, 38 insertions(+), 20 deletions(-)

diff --git a/embassy-imxrt/src/lib.rs b/embassy-imxrt/src/lib.rs
index b1183d8fc..5b7341fbd 100644
--- a/embassy-imxrt/src/lib.rs
+++ b/embassy-imxrt/src/lib.rs
@@ -54,16 +54,20 @@ pub use crate::pac::NVIC_PRIO_BITS;
 /// ```rust,ignore
 /// use embassy_imxrt::{bind_interrupts, flexspi, peripherals};
 ///
-/// bind_interrupts!(struct Irqs {
-///     FLEXSPI_IRQ => flexspi::InterruptHandler<peripherals::FLEXSPI>;
-/// });
+/// bind_interrupts!(
+///     /// Binds the FLEXSPI interrupt.
+///     struct Irqs {
+///         FLEXSPI_IRQ => flexspi::InterruptHandler<peripherals::FLEXSPI>;
+///     }
+/// );
 /// ```
 ///
 // developer note: this macro can't be in `embassy-hal-internal` due to the use of `$crate`.
 #[macro_export]
 macro_rules! bind_interrupts {
-    ($vis:vis struct $name:ident { $($irq:ident => $($handler:ty),*;)* }) => {
+    ($(#[$attr:meta])* $vis:vis struct $name:ident { $($irq:ident => $($handler:ty),*;)* }) => {
             #[derive(Copy, Clone)]
+            $(#[$attr])*
             $vis struct $name;
 
         $(
diff --git a/embassy-nrf/src/lib.rs b/embassy-nrf/src/lib.rs
index 7d86e1218..0c5dd059d 100644
--- a/embassy-nrf/src/lib.rs
+++ b/embassy-nrf/src/lib.rs
@@ -200,9 +200,12 @@ mod chip;
 /// ```rust,ignore
 /// use embassy_nrf::{bind_interrupts, spim, peripherals};
 ///
-/// bind_interrupts!(struct Irqs {
-///     SPIM3 => spim::InterruptHandler<peripherals::SPI3>;
-/// });
+/// bind_interrupts!(
+///     /// Binds the SPIM3 interrupt.
+///     struct Irqs {
+///         SPIM3 => spim::InterruptHandler<peripherals::SPI3>;
+///     }
+/// );
 /// ```
 ///
 /// Example of how to bind multiple interrupts in a single macro invocation:
@@ -219,7 +222,7 @@ mod chip;
 // developer note: this macro can't be in `embassy-hal-internal` due to the use of `$crate`.
 #[macro_export]
 macro_rules! bind_interrupts {
-    ($vis:vis struct $name:ident {
+    ($(#[$attr:meta])* $vis:vis struct $name:ident {
         $(
             $(#[cfg($cond_irq:meta)])?
             $irq:ident => $(
@@ -229,6 +232,7 @@ macro_rules! bind_interrupts {
         )*
     }) => {
         #[derive(Copy, Clone)]
+        $(#[$attr])*
         $vis struct $name;
 
         $(
diff --git a/embassy-rp/src/lib.rs b/embassy-rp/src/lib.rs
index f549446bc..f3c5a35bb 100644
--- a/embassy-rp/src/lib.rs
+++ b/embassy-rp/src/lib.rs
@@ -160,15 +160,18 @@ embassy_hal_internal::interrupt_mod!(
 /// ```rust,ignore
 /// use embassy_rp::{bind_interrupts, usb, peripherals};
 ///
-/// bind_interrupts!(struct Irqs {
-///     USBCTRL_IRQ => usb::InterruptHandler<peripherals::USB>;
-/// });
+/// bind_interrupts!(
+///     /// Binds the USB Interrupts.
+///     struct Irqs {
+///         USBCTRL_IRQ => usb::InterruptHandler<peripherals::USB>;
+///     }
+/// );
 /// ```
 ///
 // developer note: this macro can't be in `embassy-hal-internal` due to the use of `$crate`.
 #[macro_export]
 macro_rules! bind_interrupts {
-    ($vis:vis struct $name:ident {
+    ($(#[$attr:meta])* $vis:vis struct $name:ident {
         $(
             $(#[cfg($cond_irq:meta)])?
             $irq:ident => $(
@@ -178,6 +181,7 @@ macro_rules! bind_interrupts {
         )*
     }) => {
         #[derive(Copy, Clone)]
+        $(#[$attr])*
         $vis struct $name;
 
         $(
diff --git a/embassy-stm32/src/lib.rs b/embassy-stm32/src/lib.rs
index f8d09413d..973acc9bb 100644
--- a/embassy-stm32/src/lib.rs
+++ b/embassy-stm32/src/lib.rs
@@ -163,11 +163,14 @@ pub use crate::_generated::interrupt;
 /// ```rust,ignore
 /// use embassy_stm32::{bind_interrupts, i2c, peripherals};
 ///
-/// bind_interrupts!(struct Irqs {
-///     I2C1 => i2c::EventInterruptHandler<peripherals::I2C1>, i2c::ErrorInterruptHandler<peripherals::I2C1>;
-///     I2C2_3 => i2c::EventInterruptHandler<peripherals::I2C2>, i2c::ErrorInterruptHandler<peripherals::I2C2>,
-///         i2c::EventInterruptHandler<peripherals::I2C3>, i2c::ErrorInterruptHandler<peripherals::I2C3>;
-/// });
+/// bind_interrupts!(
+///     /// Binds the I2C interrupts.
+///     struct Irqs {
+///         I2C1 => i2c::EventInterruptHandler<peripherals::I2C1>, i2c::ErrorInterruptHandler<peripherals::I2C1>;
+///         I2C2_3 => i2c::EventInterruptHandler<peripherals::I2C2>, i2c::ErrorInterruptHandler<peripherals::I2C2>,
+///             i2c::EventInterruptHandler<peripherals::I2C3>, i2c::ErrorInterruptHandler<peripherals::I2C3>;
+///     }
+/// );
 /// ```
 
 // developer note: this macro can't be in `embassy-hal-internal` due to the use of `$crate`.
diff --git a/examples/rp/src/bin/adc.rs b/examples/rp/src/bin/adc.rs
index 1bb7c2249..015915586 100644
--- a/examples/rp/src/bin/adc.rs
+++ b/examples/rp/src/bin/adc.rs
@@ -12,9 +12,12 @@ use embassy_rp::gpio::Pull;
 use embassy_time::Timer;
 use {defmt_rtt as _, panic_probe as _};
 
-bind_interrupts!(struct Irqs {
-    ADC_IRQ_FIFO => InterruptHandler;
-});
+bind_interrupts!(
+    /// Binds the ADC interrupts.
+    struct Irqs {
+        ADC_IRQ_FIFO => InterruptHandler;
+    }
+);
 
 #[embassy_executor::main]
 async fn main(_spawner: Spawner) {