1 files changed, 49 insertions, 27 deletions

diff --git a/embassy-stm32/src/lib.rs b/embassy-stm32/src/lib.rs
index 5d9b4e6a0..f10e9d50d 100644
--- a/embassy-stm32/src/lib.rs
+++ b/embassy-stm32/src/lib.rs
@@ -1,5 +1,6 @@
 #![cfg_attr(not(test), no_std)]
 #![allow(async_fn_in_trait)]
+#![warn(missing_docs)]
 
 //! ## Feature flags
 #![doc = document_features::document_features!(feature_label = r#"<span class="stab portability"><code>{feature}</code></span>"#)]
@@ -79,6 +80,7 @@ pub(crate) mod _generated {
     #![allow(dead_code)]
     #![allow(unused_imports)]
     #![allow(non_snake_case)]
+    #![allow(missing_docs)]
 
     include!(concat!(env!("OUT_DIR"), "/_generated.rs"));
 }
@@ -149,15 +151,33 @@ use crate::interrupt::Priority;
 pub use crate::pac::NVIC_PRIO_BITS;
 use crate::rcc::sealed::RccPeripheral;
 
+/// `embassy-stm32` global configuration.
 #[non_exhaustive]
 pub struct Config {
+    /// RCC config.
     pub rcc: rcc::Config,
+
+    /// Enable debug during sleep.
+    ///
+    /// May incrase power consumption. Defaults to true.
     #[cfg(dbgmcu)]
     pub enable_debug_during_sleep: bool,
+
+    /// BDMA interrupt priority.
+    ///
+    /// Defaults to P0 (highest).
     #[cfg(bdma)]
     pub bdma_interrupt_priority: Priority,
+
+    /// DMA interrupt priority.
+    ///
+    /// Defaults to P0 (highest).
     #[cfg(dma)]
     pub dma_interrupt_priority: Priority,
+
+    /// GPDMA interrupt priority.
+    ///
+    /// Defaults to P0 (highest).
     #[cfg(gpdma)]
     pub gpdma_interrupt_priority: Priority,
 }
@@ -178,38 +198,40 @@ impl Default for Config {
     }
 }
 
-/// Initialize embassy.
+/// Initialize the `embassy-stm32` HAL with the provided configuration.
+///
+/// This returns the peripheral singletons that can be used for creating drivers.
+///
+/// This should only be called once at startup, otherwise it panics.
 pub fn init(config: Config) -> Peripherals {
     critical_section::with(|cs| {
         let p = Peripherals::take_with_cs(cs);
 
         #[cfg(dbgmcu)]
-        if config.enable_debug_during_sleep {
-            crate::pac::DBGMCU.cr().modify(|cr| {
-                #[cfg(any(dbgmcu_f0, dbgmcu_c0, dbgmcu_g0, dbgmcu_u5, dbgmcu_wba))]
-                {
-                    cr.set_dbg_stop(true);
-                    cr.set_dbg_standby(true);
-                }
-                #[cfg(any(
-                    dbgmcu_f1, dbgmcu_f2, dbgmcu_f3, dbgmcu_f4, dbgmcu_f7, dbgmcu_g4, dbgmcu_f7, dbgmcu_l0, dbgmcu_l1,
-                    dbgmcu_l4, dbgmcu_wb, dbgmcu_wl
-                ))]
-                {
-                    cr.set_dbg_sleep(true);
-                    cr.set_dbg_stop(true);
-                    cr.set_dbg_standby(true);
-                }
-                #[cfg(dbgmcu_h7)]
-                {
-                    cr.set_d1dbgcken(true);
-                    cr.set_d3dbgcken(true);
-                    cr.set_dbgsleep_d1(true);
-                    cr.set_dbgstby_d1(true);
-                    cr.set_dbgstop_d1(true);
-                }
-            });
-        }
+        crate::pac::DBGMCU.cr().modify(|cr| {
+            #[cfg(any(dbgmcu_f0, dbgmcu_c0, dbgmcu_g0, dbgmcu_u5, dbgmcu_wba))]
+            {
+                cr.set_dbg_stop(config.enable_debug_during_sleep);
+                cr.set_dbg_standby(config.enable_debug_during_sleep);
+            }
+            #[cfg(any(
+                dbgmcu_f1, dbgmcu_f2, dbgmcu_f3, dbgmcu_f4, dbgmcu_f7, dbgmcu_g4, dbgmcu_f7, dbgmcu_l0, dbgmcu_l1,
+                dbgmcu_l4, dbgmcu_wb, dbgmcu_wl
+            ))]
+            {
+                cr.set_dbg_sleep(config.enable_debug_during_sleep);
+                cr.set_dbg_stop(config.enable_debug_during_sleep);
+                cr.set_dbg_standby(config.enable_debug_during_sleep);
+            }
+            #[cfg(dbgmcu_h7)]
+            {
+                cr.set_d1dbgcken(config.enable_debug_during_sleep);
+                cr.set_d3dbgcken(config.enable_debug_during_sleep);
+                cr.set_dbgsleep_d1(config.enable_debug_during_sleep);
+                cr.set_dbgstby_d1(config.enable_debug_during_sleep);
+                cr.set_dbgstop_d1(config.enable_debug_during_sleep);
+            }
+        });
 
         #[cfg(not(any(stm32f1, stm32wb, stm32wl)))]
         peripherals::SYSCFG::enable_and_reset_with_cs(cs);