stm32: more docs.

Author: Dirbaio

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.

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
 

embassy-stm32/src/can/mod.rs

@@ -1,3 +1,4 @@
+//! Controller Area Network (CAN)
 #![macro_use]
 
 #[cfg_attr(can_bxcan, path = "bxcan.rs")]

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")]

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;

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;

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")]

embassy-stm32/src/exti.rs

@@ -1,3 +1,4 @@
+//! External Interrupts (EXTI)
 use core::convert::Infallible;
 use core::future::Future;
 use core::marker::PhantomData;

embassy-stm32/src/flash/mod.rs

@@ -1,3 +1,4 @@
+//! Flash memory (FLASH)
 use embedded_storage::nor_flash::{NorFlashError, NorFlashErrorKind};
 
 #[cfg(flash_f4)]

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;

embassy-stm32/src/hrtim/mod.rs

@@ -1,3 +1,5 @@
+//! High Resolution Timer (HRTIM)
+
 mod traits;
 
 use core::marker::PhantomData;

embassy-stm32/src/i2c/mod.rs

@@ -1,3 +1,4 @@
+//! Inter-Integrated-Circuit (I2C)
 #![macro_use]
 
 #[cfg_attr(i2c_v1, path = "v1.rs")]

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 _};

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);

embassy-stm32/src/qspi/mod.rs

@@ -1,3 +1,5 @@
+//! Quad Serial Peripheral Interface (QSPI)
+
 #![macro_use]
 
 pub mod enums;

embassy-stm32/src/rng.rs

@@ -1,3 +1,4 @@
+//! Random Number Generator (RNG)
 #![macro_use]
 
 use core::future::poll_fn;

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>>>,

embassy-stm32/src/sdmmc/mod.rs

@@ -1,3 +1,4 @@
+//! Secure Digital / MultiMedia Card (SDMMC)
 #![macro_use]
 
 use core::default::Default;

embassy-stm32/src/spi/mod.rs

@@ -1,3 +1,4 @@
+//! Serial Peripheral Interface (SPI)
 #![macro_use]
 
 use core::ptr;

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]>() }

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;

embassy-stm32/src/usb_otg/mod.rs

@@ -1,3 +1,5 @@
+//! USB On The Go (OTG)
+
 use crate::rcc::RccPeripheral;
 use crate::{interrupt, peripherals};
 

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};