From d3f3c425a2192bef2cd5b1fd3f1c342f49639c3d Mon Sep 17 00:00:00 2001
From: Dario Nieuwenhuis <dirbaio@dirbaio.net>
Date: Tue, 19 Dec 2023 00:05:54 +0100
Subject: [PATCH] stm32: more docs.

---
 embassy-nrf/src/lib.rs           |  6 +++++-
 embassy-stm32/src/adc/mod.rs     |  3 ++-
 embassy-stm32/src/can/mod.rs     |  1 +
 embassy-stm32/src/crc/mod.rs     |  1 +
 embassy-stm32/src/dac/mod.rs     |  2 +-
 embassy-stm32/src/dcmi.rs        |  1 +
 embassy-stm32/src/eth/mod.rs     |  1 +
 embassy-stm32/src/exti.rs        |  1 +
 embassy-stm32/src/flash/mod.rs   |  1 +
 embassy-stm32/src/fmc.rs         |  1 +
 embassy-stm32/src/hrtim/mod.rs   |  2 ++
 embassy-stm32/src/i2c/mod.rs     |  1 +
 embassy-stm32/src/i2s.rs         |  1 +
 embassy-stm32/src/lib.rs         | 24 +++++++++++++++++++++++-
 embassy-stm32/src/qspi/mod.rs    |  2 ++
 embassy-stm32/src/rng.rs         |  1 +
 embassy-stm32/src/rtc/mod.rs     |  4 ++--
 embassy-stm32/src/sdmmc/mod.rs   |  1 +
 embassy-stm32/src/spi/mod.rs     |  1 +
 embassy-stm32/src/uid.rs         |  2 ++
 embassy-stm32/src/usart/mod.rs   |  1 +
 embassy-stm32/src/usb_otg/mod.rs |  2 ++
 embassy-stm32/src/wdg/mod.rs     |  1 +
 23 files changed, 55 insertions(+), 6 deletions(-)

diff --git a/embassy-nrf/src/lib.rs b/embassy-nrf/src/lib.rs
index 9093ad91..e3458e2d 100644
--- a/embassy-nrf/src/lib.rs
+++ b/embassy-nrf/src/lib.rs
@@ -354,7 +354,11 @@ unsafe fn uicr_write_masked(address: *mut u32, value: u32, mask: u32) -> WriteRe
     WriteResult::Written
 }
 
-/// Initialize peripherals with the provided configuration. This should only be called once at startup.
+/// Initialize the `embassy-nrf` 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::Config) -> Peripherals {
     // Do this first, so that it panics if user is calling `init` a second time
     // before doing anything important.
diff --git a/embassy-stm32/src/adc/mod.rs b/embassy-stm32/src/adc/mod.rs
index ff523ca3..e4dd35c3 100644
--- a/embassy-stm32/src/adc/mod.rs
+++ b/embassy-stm32/src/adc/mod.rs
@@ -1,4 +1,5 @@
-//! Analog to Digital (ADC) converter driver.
+//! Analog to Digital Converter (ADC)
+
 #![macro_use]
 #![allow(missing_docs)] // TODO
 
diff --git a/embassy-stm32/src/can/mod.rs b/embassy-stm32/src/can/mod.rs
index 425f9ac2..915edb3a 100644
--- a/embassy-stm32/src/can/mod.rs
+++ b/embassy-stm32/src/can/mod.rs
@@ -1,3 +1,4 @@
+//! Controller Area Network (CAN)
 #![macro_use]
 
 #[cfg_attr(can_bxcan, path = "bxcan.rs")]
diff --git a/embassy-stm32/src/crc/mod.rs b/embassy-stm32/src/crc/mod.rs
index 63f7ad9b..29523b92 100644
--- a/embassy-stm32/src/crc/mod.rs
+++ b/embassy-stm32/src/crc/mod.rs
@@ -1,3 +1,4 @@
+//! Cyclic Redundancy Check (CRC)
 #[cfg_attr(crc_v1, path = "v1.rs")]
 #[cfg_attr(crc_v2, path = "v2v3.rs")]
 #[cfg_attr(crc_v3, path = "v2v3.rs")]
diff --git a/embassy-stm32/src/dac/mod.rs b/embassy-stm32/src/dac/mod.rs
index 9c670195..31dedf06 100644
--- a/embassy-stm32/src/dac/mod.rs
+++ b/embassy-stm32/src/dac/mod.rs
@@ -1,4 +1,4 @@
-//! Provide access to the STM32 digital-to-analog converter (DAC).
+//! Digital to Analog Converter (DAC)
 #![macro_use]
 
 use core::marker::PhantomData;
diff --git a/embassy-stm32/src/dcmi.rs b/embassy-stm32/src/dcmi.rs
index 139d8fd1..4d02284b 100644
--- a/embassy-stm32/src/dcmi.rs
+++ b/embassy-stm32/src/dcmi.rs
@@ -1,3 +1,4 @@
+//! Digital Camera Interface (DCMI)
 use core::future::poll_fn;
 use core::marker::PhantomData;
 use core::task::Poll;
diff --git a/embassy-stm32/src/eth/mod.rs b/embassy-stm32/src/eth/mod.rs
index dbf91eed..44840550 100644
--- a/embassy-stm32/src/eth/mod.rs
+++ b/embassy-stm32/src/eth/mod.rs
@@ -1,3 +1,4 @@
+//! Ethernet (ETH)
 #![macro_use]
 
 #[cfg_attr(any(eth_v1a, eth_v1b, eth_v1c), path = "v1/mod.rs")]
diff --git a/embassy-stm32/src/exti.rs b/embassy-stm32/src/exti.rs
index 371be913..f83bae3f 100644
--- a/embassy-stm32/src/exti.rs
+++ b/embassy-stm32/src/exti.rs
@@ -1,3 +1,4 @@
+//! External Interrupts (EXTI)
 use core::convert::Infallible;
 use core::future::Future;
 use core::marker::PhantomData;
diff --git a/embassy-stm32/src/flash/mod.rs b/embassy-stm32/src/flash/mod.rs
index 6b6b4d41..cbf5c25b 100644
--- a/embassy-stm32/src/flash/mod.rs
+++ b/embassy-stm32/src/flash/mod.rs
@@ -1,3 +1,4 @@
+//! Flash memory (FLASH)
 use embedded_storage::nor_flash::{NorFlashError, NorFlashErrorKind};
 
 #[cfg(flash_f4)]
diff --git a/embassy-stm32/src/fmc.rs b/embassy-stm32/src/fmc.rs
index 23ac82f6..873c8a70 100644
--- a/embassy-stm32/src/fmc.rs
+++ b/embassy-stm32/src/fmc.rs
@@ -1,3 +1,4 @@
+//! Flexible Memory Controller (FMC) / Flexible Static Memory Controller (FSMC)
 use core::marker::PhantomData;
 
 use embassy_hal_internal::into_ref;
diff --git a/embassy-stm32/src/hrtim/mod.rs b/embassy-stm32/src/hrtim/mod.rs
index 17096d48..6539326b 100644
--- a/embassy-stm32/src/hrtim/mod.rs
+++ b/embassy-stm32/src/hrtim/mod.rs
@@ -1,3 +1,5 @@
+//! High Resolution Timer (HRTIM)
+
 mod traits;
 
 use core::marker::PhantomData;
diff --git a/embassy-stm32/src/i2c/mod.rs b/embassy-stm32/src/i2c/mod.rs
index 0af291e9..9b0b35ec 100644
--- a/embassy-stm32/src/i2c/mod.rs
+++ b/embassy-stm32/src/i2c/mod.rs
@@ -1,3 +1,4 @@
+//! Inter-Integrated-Circuit (I2C)
 #![macro_use]
 
 #[cfg_attr(i2c_v1, path = "v1.rs")]
diff --git a/embassy-stm32/src/i2s.rs b/embassy-stm32/src/i2s.rs
index 372c86db..1f85c0bc 100644
--- a/embassy-stm32/src/i2s.rs
+++ b/embassy-stm32/src/i2s.rs
@@ -1,3 +1,4 @@
+//! Inter-IC Sound (I2S)
 use embassy_hal_internal::into_ref;
 
 use crate::gpio::sealed::{AFType, Pin as _};
diff --git a/embassy-stm32/src/lib.rs b/embassy-stm32/src/lib.rs
index 5d9b4e6a..fd691a73 100644
--- a/embassy-stm32/src/lib.rs
+++ b/embassy-stm32/src/lib.rs
@@ -149,15 +149,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,7 +196,11 @@ 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);
diff --git a/embassy-stm32/src/qspi/mod.rs b/embassy-stm32/src/qspi/mod.rs
index bac91f30..9ea0a726 100644
--- a/embassy-stm32/src/qspi/mod.rs
+++ b/embassy-stm32/src/qspi/mod.rs
@@ -1,3 +1,5 @@
+//! Quad Serial Peripheral Interface (QSPI)
+
 #![macro_use]
 
 pub mod enums;
diff --git a/embassy-stm32/src/rng.rs b/embassy-stm32/src/rng.rs
index b2196b0d..6ee89a92 100644
--- a/embassy-stm32/src/rng.rs
+++ b/embassy-stm32/src/rng.rs
@@ -1,3 +1,4 @@
+//! Random Number Generator (RNG)
 #![macro_use]
 
 use core::future::poll_fn;
diff --git a/embassy-stm32/src/rtc/mod.rs b/embassy-stm32/src/rtc/mod.rs
index fa359cda..11b25213 100644
--- a/embassy-stm32/src/rtc/mod.rs
+++ b/embassy-stm32/src/rtc/mod.rs
@@ -1,4 +1,4 @@
-//! RTC peripheral abstraction
+//! Real Time Clock (RTC)
 mod datetime;
 
 #[cfg(feature = "low-power")]
@@ -163,7 +163,7 @@ impl RtcTimeProvider {
     }
 }
 
-/// RTC Abstraction
+/// RTC driver.
 pub struct Rtc {
     #[cfg(feature = "low-power")]
     stop_time: Mutex<CriticalSectionRawMutex, Cell<Option<RtcInstant>>>,
diff --git a/embassy-stm32/src/sdmmc/mod.rs b/embassy-stm32/src/sdmmc/mod.rs
index 27a12062..6099b9f4 100644
--- a/embassy-stm32/src/sdmmc/mod.rs
+++ b/embassy-stm32/src/sdmmc/mod.rs
@@ -1,3 +1,4 @@
+//! Secure Digital / MultiMedia Card (SDMMC)
 #![macro_use]
 
 use core::default::Default;
diff --git a/embassy-stm32/src/spi/mod.rs b/embassy-stm32/src/spi/mod.rs
index 92599c75..5a1ad3e9 100644
--- a/embassy-stm32/src/spi/mod.rs
+++ b/embassy-stm32/src/spi/mod.rs
@@ -1,3 +1,4 @@
+//! Serial Peripheral Interface (SPI)
 #![macro_use]
 
 use core::ptr;
diff --git a/embassy-stm32/src/uid.rs b/embassy-stm32/src/uid.rs
index 6dcfcb96..aa13586f 100644
--- a/embassy-stm32/src/uid.rs
+++ b/embassy-stm32/src/uid.rs
@@ -1,3 +1,5 @@
+//! Unique ID (UID)
+
 /// Get this device's unique 96-bit ID.
 pub fn uid() -> &'static [u8; 12] {
     unsafe { &*crate::pac::UID.uid(0).as_ptr().cast::<[u8; 12]>() }
diff --git a/embassy-stm32/src/usart/mod.rs b/embassy-stm32/src/usart/mod.rs
index dfa1f3a6..e2e3bd3e 100644
--- a/embassy-stm32/src/usart/mod.rs
+++ b/embassy-stm32/src/usart/mod.rs
@@ -1,3 +1,4 @@
+//! Universal Synchronous/Asynchronous Receiver Transmitter (USART, UART, LPUART)
 #![macro_use]
 
 use core::future::poll_fn;
diff --git a/embassy-stm32/src/usb_otg/mod.rs b/embassy-stm32/src/usb_otg/mod.rs
index be54a3d1..1abd031d 100644
--- a/embassy-stm32/src/usb_otg/mod.rs
+++ b/embassy-stm32/src/usb_otg/mod.rs
@@ -1,3 +1,5 @@
+//! USB On The Go (OTG)
+
 use crate::rcc::RccPeripheral;
 use crate::{interrupt, peripherals};
 
diff --git a/embassy-stm32/src/wdg/mod.rs b/embassy-stm32/src/wdg/mod.rs
index c7c2694e..5751a9ff 100644
--- a/embassy-stm32/src/wdg/mod.rs
+++ b/embassy-stm32/src/wdg/mod.rs
@@ -1,3 +1,4 @@
+//! Watchdog Timer (IWDG, WWDG)
 use core::marker::PhantomData;
 
 use embassy_hal_internal::{into_ref, Peripheral};