Add #![deny(missing_docs)] to the aes, analog, clock, and dma modules (#1849)

* Deny missing documentation within the `analog` module

* Deny missing documentation in the `dma` module

* Remove unused `ENCRYPT_MODE`/`DECRYPT_MODE` constants from `AesFlavour` trait

* Deny missing documentation in the `aes` module

* Deny missing documentation in the `clock` module

* Update `CHANGELOG.md`

esp-hal/CHANGELOG.md

@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Removed
 
 - This package no longer re-exports the `esp_hal_procmacros::main` macro (#1828)
+- The `AesFlavour` trait no longer has the `ENCRYPT_MODE`/`DECRYPT_MODE` associated constants (#1849)
 
 ## [0.19.0] - 2024-07-15
 

esp-hal/src/aes/esp32.rs

@@ -73,18 +73,12 @@ impl<'d> Aes<'d> {
 
 impl AesFlavour for Aes128 {
     type KeyType<'b> = &'b [u8; 16];
-    const ENCRYPT_MODE: u32 = 0;
-    const DECRYPT_MODE: u32 = 4;
 }
 
 impl AesFlavour for Aes192 {
     type KeyType<'b> = &'b [u8; 24];
-    const ENCRYPT_MODE: u32 = 1;
-    const DECRYPT_MODE: u32 = 5;
 }
 
 impl AesFlavour for Aes256 {
     type KeyType<'b> = &'b [u8; 32];
-    const ENCRYPT_MODE: u32 = 2;
-    const DECRYPT_MODE: u32 = 6;
 }

esp-hal/src/aes/esp32cX.rs

@@ -50,12 +50,8 @@ impl<'d> Aes<'d> {
 
 impl AesFlavour for Aes128 {
     type KeyType<'b> = &'b [u8; 16];
-    const ENCRYPT_MODE: u32 = 0;
-    const DECRYPT_MODE: u32 = 4;
 }
 
 impl AesFlavour for Aes256 {
     type KeyType<'b> = &'b [u8; 32];
-    const ENCRYPT_MODE: u32 = 2;
-    const DECRYPT_MODE: u32 = 6;
 }

esp-hal/src/aes/esp32s2.rs

@@ -87,18 +87,12 @@ impl<'d> Aes<'d> {
 
 impl AesFlavour for Aes128 {
     type KeyType<'b> = &'b [u8; 16];
-    const ENCRYPT_MODE: u32 = 0;
-    const DECRYPT_MODE: u32 = 4;
 }
 
 impl AesFlavour for Aes192 {
     type KeyType<'b> = &'b [u8; 24];
-    const ENCRYPT_MODE: u32 = 1;
-    const DECRYPT_MODE: u32 = 5;
 }
 
 impl AesFlavour for Aes256 {
     type KeyType<'b> = &'b [u8; 32];
-    const ENCRYPT_MODE: u32 = 2;
-    const DECRYPT_MODE: u32 = 6;
 }

esp-hal/src/aes/esp32s3.rs

@@ -59,12 +59,8 @@ impl<'d> Aes<'d> {
 
 impl AesFlavour for Aes128 {
     type KeyType<'b> = &'b [u8; 16];
-    const ENCRYPT_MODE: u32 = 0;
-    const DECRYPT_MODE: u32 = 4;
 }
 
 impl AesFlavour for Aes256 {
     type KeyType<'b> = &'b [u8; 32];
-    const ENCRYPT_MODE: u32 = 2;
-    const DECRYPT_MODE: u32 = 6;
 }

esp-hal/src/aes/mod.rs

@@ -46,6 +46,8 @@
 //! * AES-DMA mode is currently not supported on ESP32 and ESP32S2
 //! * AES-DMA Initialization Vector (IV) is currently not supported
 
+#![deny(missing_docs)]
+
 use crate::{
     peripheral::{Peripheral, PeripheralRef},
     peripherals::AES,
@@ -179,9 +181,11 @@ impl<'d> Aes<'d> {
 
 /// Specifications for AES flavours
 pub trait AesFlavour: crate::private::Sealed {
+    /// Type of the AES key, a fixed-size array of bytes
+    ///
+    /// The size of this type depends on various factors, such as the device
+    /// being targeted and the desired key size.
     type KeyType<'b>;
-    const ENCRYPT_MODE: u32;
-    const DECRYPT_MODE: u32;
 }
 
 /// Marker type for AES-128
@@ -202,7 +206,9 @@ impl crate::private::Sealed for Aes256 {}
 /// State matrix endianness
 #[cfg(any(esp32, esp32s2))]
 pub enum Endianness {
+    /// Big endian (most-significant byte at the smallest address)
     BigEndian    = 1,
+    /// Little endian (least-significant byte at the smallest address)
     LittleEndian = 0,
 }
 
@@ -258,6 +264,7 @@ pub mod dma {
         C: DmaChannel,
         C::P: AesPeripheral,
     {
+        /// The underlying [`Aes`](super::Aes) driver
         pub aes: super::Aes<'d>,
 
         pub(crate) channel: Channel<'d, C, crate::Blocking>,
@@ -265,11 +272,13 @@ pub mod dma {
         rx_chain: DescriptorChain,
     }
 
+    /// Functionality for using AES with DMA.
     pub trait WithDmaAes<'d, C>
     where
         C: DmaChannel,
         C::P: AesPeripheral,
     {
+        /// Enable DMA for the current instance of the AES driver
         fn with_dma(
             self,
             channel: Channel<'d, C, crate::Blocking>,

esp-hal/src/analog/adc/esp32.rs

@@ -9,9 +9,13 @@ pub(super) const NUM_ATTENS: usize = 10;
 /// The sampling/readout resolution of the ADC.
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub enum Resolution {
+    /// 9-bit resolution
     Resolution9Bit  = 0b00,
+    /// 10-bit resolution
     Resolution10Bit = 0b01,
+    /// 11-bit resolution
     Resolution11Bit = 0b10,
+    /// 12-bit resolution
     #[default]
     Resolution12Bit = 0b11,
 }
@@ -324,15 +328,15 @@ where
 }
 
 impl<'d, ADC1> Adc<'d, ADC1> {
+    /// Enable the Hall sensor
     pub fn enable_hall_sensor() {
-        // Connect hall sensor
         unsafe { &*RTC_IO::ptr() }
             .hall_sens()
             .modify(|_, w| w.xpd_hall().set_bit());
     }
 
+    /// Disable the Hall sensor
     pub fn disable_hall_sensor() {
-        // Disconnect hall sensor
         unsafe { &*RTC_IO::ptr() }
             .hall_sens()
             .modify(|_, w| w.xpd_hall().clear_bit());

esp-hal/src/analog/adc/mod.rs

@@ -87,13 +87,17 @@ pub enum Attenuation {
 #[cfg(not(esp32))]
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AdcCalSource {
+    /// Use Ground as the calibration source
     Gnd,
+    /// Use Vref as the calibration source
     Ref,
 }
 
 /// An I/O pin which can be read using the ADC.
 pub struct AdcPin<PIN, ADCI, CS = ()> {
+    /// The underlying GPIO pin
     pub pin: PIN,
+    /// Calibration scheme used for the configured ADC pin
     #[cfg_attr(esp32, allow(unused))]
     pub cal_scheme: CS,
     _phantom: PhantomData<ADCI>,
@@ -113,8 +117,9 @@ where
 
 /// Configuration for the ADC.
 pub struct AdcConfig<ADCI> {
-    pub resolution: Resolution,
+    #[cfg_attr(not(esp32), allow(unused))]
-    pub attenuations: [Option<Attenuation>; NUM_ATTENS],
+    resolution: Resolution,
+    attenuations: [Option<Attenuation>; NUM_ATTENS],
     _phantom: PhantomData<ADCI>,
 }
 
@@ -190,6 +195,7 @@ pub trait CalibrationAccess: RegisterAccess {
 
 /// A helper trait to get the ADC channel of a compatible GPIO pin.
 pub trait AdcChannel {
+    /// Channel number used by the ADC
     const CHANNEL: u8;
 }
 

esp-hal/src/analog/adc/riscv.rs

@@ -103,6 +103,7 @@ cfg_if::cfg_if! {
 /// The sampling/readout resolution of the ADC.
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub enum Resolution {
+    /// 12-bit resolution
     #[default]
     Resolution12Bit,
 }

esp-hal/src/analog/adc/xtensa.rs

@@ -74,6 +74,7 @@ cfg_if::cfg_if! {
 /// The sampling/readout resolution of the ADC.
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub enum Resolution {
+    /// 13-bit resolution
     #[default]
     Resolution13Bit,
 }

esp-hal/src/analog/dac.rs

@@ -41,8 +41,6 @@
 //! # }
 //! ```
 
-#![deny(missing_docs)]
-
 use crate::{
     gpio::{self, AnalogPin},
     peripheral::{Peripheral, PeripheralRef},

esp-hal/src/analog/mod.rs

@@ -5,6 +5,8 @@
 //! available on the device. For more information about a peripheral driver,
 //! please refer to the relevant module documentation.
 
+#![deny(missing_docs)]
+
 #[cfg(adc)]
 pub mod adc;
 #[cfg(dac)]

esp-hal/src/clock/mod.rs

@@ -70,6 +70,8 @@
 //! # }
 //! ```
 
+#![deny(missing_docs)]
+
 use fugit::HertzU32;
 
 #[cfg(any(esp32, esp32c2))]
@@ -88,13 +90,17 @@ use crate::{
 #[cfg_attr(esp32s3, path = "clocks_ll/esp32s3.rs")]
 pub(crate) mod clocks_ll;
 
+/// Clock properties
 pub trait Clock {
+    /// Frequency of the clock in [Hertz](fugit::HertzU32), using [fugit] types.
     fn frequency(&self) -> HertzU32;
 
+    /// Frequency of the clock in Megahertz
     fn mhz(&self) -> u32 {
         self.frequency().to_MHz()
     }
 
+    /// Frequency of the clock in Hertz
     fn hz(&self) -> u32 {
         self.frequency().to_Hz()
     }
@@ -103,14 +109,19 @@ pub trait Clock {
 /// CPU clock speed
 #[derive(Debug, Clone, Copy)]
 pub enum CpuClock {
+    /// 80MHz CPU clock
     #[cfg(not(esp32h2))]
     Clock80MHz,
+    /// 96MHz CPU clock
     #[cfg(esp32h2)]
     Clock96MHz,
+    /// 120MHz CPU clock
     #[cfg(esp32c2)]
     Clock120MHz,
+    /// 160MHz CPU clock
     #[cfg(not(any(esp32c2, esp32h2)))]
     Clock160MHz,
+    /// 240MHz CPU clock
     #[cfg(xtensa)]
     Clock240MHz,
 }
@@ -133,15 +144,20 @@ impl Clock for CpuClock {
     }
 }
 
+/// XTAL clock speed
 #[derive(Debug, Clone, Copy)]
 #[non_exhaustive]
 pub enum XtalClock {
+    /// 26MHz XTAL clock
     #[cfg(any(esp32, esp32c2))]
     RtcXtalFreq26M,
+    /// 32MHz XTAL clock
     #[cfg(any(esp32c3, esp32h2, esp32s3))]
     RtcXtalFreq32M,
+    /// 40MHz XTAL clock
     #[cfg(not(esp32h2))]
     RtcXtalFreq40M,
+    /// Other XTAL clock
     RtcXtalFreqOther(u32),
 }
 
@@ -239,23 +255,32 @@ impl Clock for ApbClock {
 
 /// Frozen clock frequencies
 ///
-/// The existence of this value indicates that the clock configuration can no
+/// The instantiation of this type indicates that the clock configuration can no
 /// longer be changed
 pub struct Clocks<'d> {
     _private: PeripheralRef<'d, SystemClockControl>,
+    /// CPU clock frequency
     pub cpu_clock: HertzU32,
+    /// APB clock frequency
     pub apb_clock: HertzU32,
+    /// XTAL clock frequency
     pub xtal_clock: HertzU32,
+    /// I2C clock frequency
     #[cfg(esp32)]
     pub i2c_clock: HertzU32,
+    /// PWM clock frequency
     #[cfg(esp32)]
     pub pwm_clock: HertzU32,
+    /// Crypto PWM  clock frequency
     #[cfg(esp32s3)]
     pub crypto_pwm_clock: HertzU32,
+    /// Crypto clock frequency
     #[cfg(any(esp32c6, esp32h2))]
     pub crypto_clock: HertzU32,
+    /// PLL 48M clock frequency (fixed)
     #[cfg(esp32h2)]
     pub pll_48m_clock: HertzU32,
+    /// PLL 96M clock frequency (fixed)
     #[cfg(esp32h2)]
     pub pll_96m_clock: HertzU32,
 }

esp-hal/src/dma/mod.rs

@@ -49,7 +49,8 @@
 //! on esp32s3.
 //!
 //! For convenience you can use the [crate::dma_buffers] macro.
-#![warn(missing_docs)]
+
+#![deny(missing_docs)]
 
 use core::{fmt::Debug, marker::PhantomData, ptr::addr_of_mut, sync::atomic::compiler_fence};