Get rid of missing docs in a number of modules (#1967)

* Get rid of missing docs in a number of modules

* address reviews

* Address the rest of reviews

* remove all remaining `allows`

* are you serious?

esp-backtrace/src/riscv.rs

@@ -12,45 +12,93 @@ pub(super) const RA_OFFSET: usize = 4;
 
 /// Registers saved in trap handler
 #[doc(hidden)]
-#[allow(missing_docs)]
 #[derive(Default, Clone, Copy)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(C)]
 pub(crate) struct TrapFrame {
+    /// Return address, stores the address to return to after a function call or
+    /// interrupt.
     pub ra: usize,
+    /// Temporary register t0, used for intermediate values.
     pub t0: usize,
+    /// Temporary register t1, used for intermediate values.
     pub t1: usize,
+    /// Temporary register t2, used for intermediate values.
     pub t2: usize,
+    /// Temporary register t3, used for intermediate values.
     pub t3: usize,
+    /// Temporary register t4, used for intermediate values.
     pub t4: usize,
+    /// Temporary register t5, used for intermediate values.
     pub t5: usize,
+    /// Temporary register t6, used for intermediate values.
     pub t6: usize,
+    /// Argument register a0, typically used to pass the first argument to a
+    /// function.
     pub a0: usize,
+    /// Argument register a1, typically used to pass the second argument to a
+    /// function.
     pub a1: usize,
+    /// Argument register a2, typically used to pass the third argument to a
+    /// function.
     pub a2: usize,
+    /// Argument register a3, typically used to pass the fourth argument to a
+    /// function.
     pub a3: usize,
+    /// Argument register a4, typically used to pass the fifth argument to a
+    /// function.
     pub a4: usize,
+    /// Argument register a5, typically used to pass the sixth argument to a
+    /// function.
     pub a5: usize,
+    /// Argument register a6, typically used to pass the seventh argument to a
+    /// function.
     pub a6: usize,
+    /// Argument register a7, typically used to pass the eighth argument to a
+    /// function.
     pub a7: usize,
+    /// Saved register s0, used to hold values across function calls.
     pub s0: usize,
+    /// Saved register s1, used to hold values across function calls.
     pub s1: usize,
+    /// Saved register s2, used to hold values across function calls.
     pub s2: usize,
+    /// Saved register s3, used to hold values across function calls.
     pub s3: usize,
+    /// Saved register s4, used to hold values across function calls.
     pub s4: usize,
+    /// Saved register s5, used to hold values across function calls.
     pub s5: usize,
+    /// Saved register s6, used to hold values across function calls.
     pub s6: usize,
+    /// Saved register s7, used to hold values across function calls.
     pub s7: usize,
+    /// Saved register s8, used to hold values across function calls.
     pub s8: usize,
+    /// Saved register s9, used to hold values across function calls.
     pub s9: usize,
+    /// Saved register s10, used to hold values across function calls.
     pub s10: usize,
+    /// Saved register s11, used to hold values across function calls.
     pub s11: usize,
+    /// Global pointer register, holds the address of the global data area.
     pub gp: usize,
+    /// Thread pointer register, holds the address of the thread-local storage
+    /// area.
     pub tp: usize,
+    /// Stack pointer register, holds the address of the top of the stack.
     pub sp: usize,
+    /// Program counter, stores the address of the next instruction to be
+    /// executed.
     pub pc: usize,
+    /// Machine status register, holds the current status of the processor,
+    /// including interrupt enable bits and privilege mode.
     pub mstatus: usize,
+    /// Machine cause register, contains the reason for the trap (e.g.,
+    /// exception or interrupt number).
     pub mcause: usize,
+    /// Machine trap value register, contains additional information about the
+    /// trap (e.g., faulting address).
     pub mtval: usize,
 }
 

esp-backtrace/src/xtensa.rs

@@ -9,8 +9,8 @@ use crate::MAX_BACKTRACE_ADDRESSES;
 #[cfg(feature = "panic-handler")]
 pub(super) const RA_OFFSET: usize = 3;
 
+/// Exception Cause
 #[doc(hidden)]
-#[allow(missing_docs)]
 #[derive(Debug, Clone, Copy)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(C)]
@@ -95,89 +95,165 @@ pub enum ExceptionCause {
     Cp6Disabled                    = 38,
     /// Access To Coprocessor 7 When Disabled
     Cp7Disabled                    = 39,
-
+    /// None
     None                           = 255,
 }
 
 #[doc(hidden)]
-#[allow(missing_docs, non_snake_case)]
+#[allow(non_snake_case)]
 #[derive(Clone, Copy)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(C)]
 pub struct Context {
+    /// Program counter, stores the address of the next instruction to be
+    /// executed.
     pub PC: u32,
+    /// Processor status, holds various status flags for the CPU.
     pub PS: u32,
+    /// General-purpose register A0 used for data storage and manipulation.
     pub A0: u32,
+    /// General-purpose register A1 used for data storage and manipulation.
     pub A1: u32,
+    /// General-purpose register A2 used for data storage and manipulation.
     pub A2: u32,
+    /// General-purpose register A3 used for data storage and manipulation.
     pub A3: u32,
+    /// General-purpose register A4 used for data storage and manipulation.
     pub A4: u32,
+    /// General-purpose register A5 used for data storage and manipulation.
     pub A5: u32,
+    /// General-purpose register A6 used for data storage and manipulation.
     pub A6: u32,
+    /// General-purpose register A7 used for data storage and manipulation.
     pub A7: u32,
+    /// General-purpose register A8 used for data storage and manipulation.
     pub A8: u32,
+    /// General-purpose register A9 used for data storage and manipulation.
     pub A9: u32,
+    /// General-purpose register A10 used for data storage and manipulation.
     pub A10: u32,
+    /// General-purpose register A11 used for data storage and manipulation.
     pub A11: u32,
+    /// General-purpose register A12 used for data storage and manipulation.
     pub A12: u32,
+    /// General-purpose register A13 used for data storage and manipulation.
     pub A13: u32,
+    /// General-purpose register A14 used for data storage and manipulation.
     pub A14: u32,
+    /// General-purpose register A15 used for data storage and manipulation.
     pub A15: u32,
+    /// Shift amount register, used for shift and rotate instructions.
     pub SAR: u32,
+    /// Exception cause, indicates the reason for the last exception.
     pub EXCCAUSE: u32,
+    /// Exception address, holds the address related to the exception.
     pub EXCVADDR: u32,
+    /// Loop start address, used in loop instructions.
     pub LBEG: u32,
+    /// Loop end address, used in loop instructions.
     pub LEND: u32,
+    /// Loop counter, used to count iterations in loop instructions.
     pub LCOUNT: u32,
+    /// Thread pointer, used for thread-local storage.
     pub THREADPTR: u32,
+    /// Compare register, used for certain compare instructions.
     pub SCOMPARE1: u32,
+    /// Break register, used for breakpoint-related operations.
     pub BR: u32,
+    /// Accumulator low register, used for extended arithmetic operations.
     pub ACCLO: u32,
+    /// Accumulator high register, used for extended arithmetic operations.
     pub ACCHI: u32,
+    /// Additional register M0 used for special operations.
     pub M0: u32,
+    /// Additional register M1 used for special operations.
     pub M1: u32,
+    /// Additional register M2 used for special operations.
     pub M2: u32,
+    /// Additional register M3 used for special operations.
     pub M3: u32,
+    /// 64-bit floating-point register (low part), available if the
+    /// `print-float-registers` feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F64R_LO: u32,
+    /// 64-bit floating-point register (high part), available if the
+    /// `print-float-registers` feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F64R_HI: u32,
+    /// Floating-point status register, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F64S: u32,
+    /// Floating-point control register, available if the
+    /// `print-float-registers` feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub FCR: u32,
+    /// Floating-point status register, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub FSR: u32,
+    /// Floating-point register F0, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F0: u32,
+    /// Floating-point register F1, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F1: u32,
+    /// Floating-point register F2, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F2: u32,
+    /// Floating-point register F3, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F3: u32,
+    /// Floating-point register F4, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F4: u32,
+    /// Floating-point register F5, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F5: u32,
+    /// Floating-point register F6, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F6: u32,
+    /// Floating-point register F7, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F7: u32,
+    /// Floating-point register F8, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F8: u32,
+    /// Floating-point register F9, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F9: u32,
+    /// Floating-point register F10, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F10: u32,
+    /// Floating-point register F11, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F11: u32,
+    /// Floating-point register F12, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F12: u32,
+    /// Floating-point register F13, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F13: u32,
+    /// Floating-point register F14, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F14: u32,
+    /// Floating-point register F15, available if the `print-float-registers`
+    /// feature is enabled.
     #[cfg(feature = "print-float-registers")]
     pub F15: u32,
 }

esp-hal/src/dma/mod.rs

@@ -523,17 +523,26 @@ pub enum DmaError {
 #[cfg(gdma)]
 #[derive(Debug, Clone, Copy, PartialEq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-#[allow(missing_docs)]
 pub enum DmaPriority {
+    /// The lowest priority level (Priority 0).
     Priority0 = 0,
+    /// Priority level 1.
     Priority1 = 1,
+    /// Priority level 2.
     Priority2 = 2,
+    /// Priority level 3.
     Priority3 = 3,
+    /// Priority level 4.
     Priority4 = 4,
+    /// Priority level 5.
     Priority5 = 5,
+    /// Priority level 6.
     Priority6 = 6,
+    /// Priority level 7.
     Priority7 = 7,
+    /// Priority level 8.
     Priority8 = 8,
+    /// The highest priority level (Priority 9).
     Priority9 = 9,
 }
 
@@ -542,8 +551,8 @@ pub enum DmaPriority {
 #[cfg(pdma)]
 #[derive(Debug, Clone, Copy, PartialEq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-#[allow(missing_docs)]
 pub enum DmaPriority {
+    /// The lowest priority level (Priority 0).
     Priority0 = 0,
 }
 
@@ -860,10 +869,12 @@ impl DescriptorChain {
 
 /// Block size for transfers to/from psram
 #[derive(Copy, Clone, Debug, PartialEq)]
-#[allow(missing_docs)]
 pub enum DmaExtMemBKSize {
+    /// External memory block size of 16 bytes.
     Size16 = 0,
+    /// External memory block size of 32 bytes.
     Size32 = 1,
+    /// External memory block size of 64 bytes.
     Size64 = 2,
 }
 

esp-hal/src/ecc.rs

@@ -25,8 +25,6 @@
 //!
 //! [ECC]: https://github.com/esp-rs/esp-hal/blob/main/hil-test/tests/ecc.rs
 
-#![allow(missing_docs)] // TODO: Remove when able
-
 use core::marker::PhantomData;
 
 use crate::{
@@ -55,30 +53,47 @@ pub enum Error {
     PointNotOnSelectedCurve,
 }
 
+/// Represents supported elliptic curves for cryptographic operations.
 pub enum EllipticCurve {
+    /// The P-192 elliptic curve, a 192-bit curve.
     P192 = 0,
+    /// The P-256 elliptic curve. a 256-bit curve.
     P256 = 1,
 }
 
 #[derive(Clone)]
+/// Represents the operational modes for elliptic curve or modular arithmetic
+/// computations.
 pub enum WorkMode {
+    /// Point multiplication mode.
     PointMultiMode          = 0,
     #[cfg(esp32c2)]
+    /// Division mode.
     DivisionMode            = 1,
+    /// Point verification mode.
     PointVerif              = 2,
+    /// Point verification and multiplication mode.
     PointVerifMulti         = 3,
+    /// Jacobian point multiplication mode.
     JacobianPointMulti      = 4,
     #[cfg(esp32h2)]
+    /// Point addition mode.
     PointAdd                = 5,
+    /// Jacobian point verification mode.
     JacobianPointVerif      = 6,
+    /// Point verification and multiplication in Jacobian coordinates.
     PointVerifJacobianMulti = 7,
     #[cfg(esp32h2)]
+    /// Modular addition mode.
     ModAdd                  = 8,
     #[cfg(esp32h2)]
+    /// Modular subtraction mode.
     ModSub                  = 9,
     #[cfg(esp32h2)]
+    /// Modular multiplication mode.
     ModMulti                = 10,
     #[cfg(esp32h2)]
+    /// Modular division mode.
     ModDiv                  = 11,
 }
 
@@ -111,6 +126,7 @@ impl<'d> InterruptConfigurable for Ecc<'d, crate::Blocking> {
 }
 
 impl<'d, DM: crate::Mode> Ecc<'d, DM> {
+    /// Resets the ECC peripheral.
     pub fn reset(&mut self) {
         self.ecc.mult_conf().reset()
     }