diff --git a/API-GUIDELINES.md b/API-GUIDELINES.md
index 82184cbc624..093ac5a2775 100644
--- a/API-GUIDELINES.md
+++ b/API-GUIDELINES.md
@@ -1,4 +1,4 @@
-# esp-rs API Guidelines
+# `esp-rs` API Guidelines
 
 ## About
 
@@ -7,7 +7,7 @@ This is a living document - make sure to check the latest version of this docume
 > [!NOTE]
 > Not all of the currently existing code follows this guideline, yet.
 
-In general, the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines) apply to all projects in the ESP-RS GitHub organization where possible. (`C-RW-VALUE` and `C-SERDE` do not apply) 
+In general, the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines) apply to all projects in the ESP-RS GitHub organization where possible. (`C-RW-VALUE` and `C-SERDE` do not apply)
 
 Especially for public API but if possible also for internal APIs.
 
@@ -42,13 +42,47 @@ The following paragraphs contain additional recommendations.
 - Avoid type states and extraneous generics whenever possible
     - These often lead to usability problems, and tend to just complicate things needlessly - sometimes it can be a good tradeoff to make a type not ZST
     - Common cases of useless type info is storing pin information - this is usually not required after configuring the pins and will bloat the complexity of the type massively. When following the `PeripheralRef` pattern it's not needed in order to keep users from re-using the pin while in use
-- Avoiding `&mut self` when `&self` is safe to use. `&self` is generally easier to use as an API. Typical applications of this are where the methods just do writes to registers which don't have side effects. 
+- Avoiding `&mut self` when `&self` is safe to use. `&self` is generally easier to use as an API. Typical applications of this are where the methods just do writes to registers which don't have side effects.
     - For example starting a timer is fine for `&self`, worst case a timer will be started twice if two parts of the program call it. You can see a real example of this [here](https://github.com/esp-rs/esp-hal/pull/1500#pullrequestreview-2015911974)
 
 ## Maintainability
 
 - Avoid excessive use of macros unless there is no other option; modification of the PAC crates should be considered before resorting to macros.
 - Every line of code is a liability. Take some time to see if your implementation can be simplified before opening a PR.
-- If your are porting code from ESP-IDF (or anything else), please include a link WITH the commit hash in it, and please highlight the relevant line(s) of code
+- If you are porting code from ESP-IDF (or anything else), please include a link WITH the commit hash in it, and please highlight the relevant line(s) of code
 - If necessary provide further context as comments (consider linking to code, PRs, TRM - make sure to use permanent links, e.g. include the hash when linking to a Git repository, include the revision, page number etc. when linking to TRMs)
-- Generally follow common "good practices" and idiomatic Rust style
+- Generally, follow common "good practices" and idiomatic Rust style
+
+## Modules Documentation
+
+Modules should have the following documentation format:
+```rust
+//! # Peripheral Name (Peripheral Acronym)
+//!
+//! ## Overview
+//! Small description of the peripheral, see ESP-IDF docs or TRM
+//!
+//! ## Configuration
+//! Explain how can the peripheral be configured, and which parameters can be configured
+//!
+//! ## Usage
+//! Explain if we implement any external traits
+//!
+//! ## Examples
+//!
+//! ### Name of the Example
+//! Small description of the example if needed
+//! ```rust, no_run
+//! ...
+//! ```
+//!
+//! ## Implementation State
+//! List unsuported features
+```
+- If any of the headers is empty, remove it
+- When possible, use ESP-IDF docs and TRM as references and include links if possible.
+  - In case of referencing an ESP-IDF link make it chip-specific, for example:
+    ```
+    #![doc = concat!("[ESP-IDF documentation](https://docs.espressif.com/projects/esp-idf/en/latest/", crate::soc::chip!(), "/api-reference/peripherals/etm.html)")]
+    ```
+- Documentation examples should be short and basic, for more complex scenarios, create an example.
diff --git a/esp-hal/src/assist_debug.rs b/esp-hal/src/assist_debug.rs
index 6ea71a3cab4..dafd353e517 100644
--- a/esp-hal/src/assist_debug.rs
+++ b/esp-hal/src/assist_debug.rs
@@ -1,22 +1,27 @@
-//! # Debug Assistant
+//! # Debug Assistant (ASSIST_DEBUG)
 //!
 //! ## Overview
-//! The Assist Debug driver provides functionality for debugging and monitoring
-//! features on ESP chips. It includes capabilities such as monitoring stack
-//! pointer (SP), monitoring memory regions, and handling interrupts related to
-//! debugging.
-//!
 //! Debug Assistant is an auxiliary module that features a set of functions to
-//! help locate bugs and issues during software debugging.
+//! help locate bugs and issues during software debugging. It includes
+//! capabilities such as monitoring stack pointer (SP), monitoring memory
+//! regions, and handling interrupts related to debugging.
+//!
 //!
+//! ## Configuration
 //! While all the targets support program counter (PC) logging it's API is not
 //! exposed here. Instead the ROM bootloader will always enable it and print the
 //! last seen PC (e.g. _Saved PC:0x42002ff2_). Make sure the reset was triggered
 //! by a TIMG watchdog. Not an RTC or SWD watchdog.
 //!
-//! ⚠️ Bus write access logging is not available via this API. ⚠️
+//! ## Examples
+//! Visit the [Debug Assist] example for an example of using the Debug
+//! Assistant.
+//!
+//! [Debug Assist]: https://github.com/esp-rs/esp-hal/blob/main/examples/src/bin/debug_assist.rs
 //!
-//! ⚠️ This driver has only blocking API. ⚠️
+//! ## Implmentation State
+//! - Bus write access logging is not available via this API
+//! - This driver has only blocking API
 
 use crate::{
     interrupt::InterruptHandler,
diff --git a/esp-hal/src/delay.rs b/esp-hal/src/delay.rs
index db121a67c1f..1b85154755d 100644
--- a/esp-hal/src/delay.rs
+++ b/esp-hal/src/delay.rs
@@ -1,16 +1,21 @@
-//! # Delay driver
+//! # Delay
 //!
 //! ## Overview
 //! The Delay driver provides blocking delay functionalities using the
 //! `SYSTIMER` peripheral for RISC-V devices and the built-in Xtensa timer for
-//! Xtensa devices. This module implements the blocking [DelayMs] and [DelayUs]
-//! traits from [embedded-hal].
+//! Xtensa devices.
 //!
+//! ## Configuration
 //! The delays are implemented in a "best-effort" way, meaning that the CPU will
 //! block for at least the amount of time specified, but accuracy can be
 //! affected by many factors, including interrupt usage.
 //!
+//! ## Usage
+//! This module implements the blocking [DelayMs] and [DelayUs] traits from
+//! [embedded-hal], both 0.2.x and 1.x.x.
+//!
 //! ## Examples
+//! ### Delay for 1 second
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::delay::Delay;
@@ -23,7 +28,7 @@
 //! 
 //! [DelayMs]: embedded_hal_02::blocking::delay::DelayMs
 //! [DelayUs]: embedded_hal_02::blocking::delay::DelayUs
-//! [embedded-hal]: https://docs.rs/embedded-hal/0.2.7/embedded_hal/index.html
+//! [embedded-hal]: https://docs.rs/embedded-hal/1.0.0/embedded_hal/delay/index.html
 
 use fugit::HertzU64;
 pub use fugit::MicrosDurationU64;
diff --git a/esp-hal/src/ecc.rs b/esp-hal/src/ecc.rs
index 69e01816c32..e2450aa87fc 100644
--- a/esp-hal/src/ecc.rs
+++ b/esp-hal/src/ecc.rs
@@ -1,6 +1,6 @@
-//! ECC Accelerator
+//! # Elliptic Curve Cryptography (ECC) Accelerator
 //!
-//! # Overview
+//! ## Overview
 //!
 //! Elliptic Curve Cryptography (ECC) is an approach to public-key cryptography
 //! based on the algebraic structure of elliptic curves. ECC allows smaller
@@ -10,22 +10,20 @@
 //! elliptic curves, thus accelerating ECC algorithm and ECC-derived
 //! algorithms (such as ECDSA).
 //!
-//! # Main features
-//!
+//! ## Configuration
 //! ECC Accelerator supports:
 //! - Two different elliptic curves, namely P-192 and P-256 defined in FIPS
 //!   186-3.
 //! - Seven working modes.
 //! - Interrupt upon completion of calculation.
 //!
-//! # Availability on ESP32 family
-//!
-//! The accelerator is available on ESP32-C2 and ESP32-C6.
-//!
-//! # Data representation
-//!
 //! Inputs of the ECC hardware accelerator must be provided in big-endian
 //! representation. The driver handles the inner representation of the blocks.
+//!
+//! ## Examples
+//! Visit the [ECC] test for an example of using the ECC Accelerator.
+//!
+//! [ECC]: https://github.com/esp-rs/esp-hal/blob/main/hil-test/tests/ecc.rs
 
 use core::marker::PhantomData;
 
@@ -84,7 +82,7 @@ pub enum WorkMode {
 impl<'d> Ecc<'d, crate::Blocking> {
     /// Create a new instance in [crate::Blocking] mode.
     ///
-    /// Optionally an interrupt handler can be bound.    
+    /// Optionally an interrupt handler can be bound.
     pub fn new(ecc: impl Peripheral<P = ECC> + 'd, interrupt: Option<InterruptHandler>) -> Self {
         crate::into_ref!(ecc);
 
diff --git a/esp-hal/src/etm.rs b/esp-hal/src/etm.rs
index 9388eb128f2..ea35a9cc70e 100644
--- a/esp-hal/src/etm.rs
+++ b/esp-hal/src/etm.rs
@@ -20,7 +20,7 @@
 //!
 //! For more information, please refer to the
 #![doc = concat!("[ESP-IDF documentation](https://docs.espressif.com/projects/esp-idf/en/latest/", crate::soc::chip!(), "/api-reference/peripherals/etm.html)")]
-//! ## Example
+//! ## Examples
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::gpio::Io;
diff --git a/esp-hal/src/hmac.rs b/esp-hal/src/hmac.rs
index 209d970c83e..f2b37a83048 100644
--- a/esp-hal/src/hmac.rs
+++ b/esp-hal/src/hmac.rs
@@ -1,19 +1,12 @@
-//! HMAC Accelerator
+//! # Hash-based Message Authentication Code (HMAC) Accelerator
 //!
-//! # Overview
+//! ## Overview
+//! HMAC is a secure authentication technique that verifies the authenticity and
+//! integrity of a message with a pre-shared key. This module provides hardware
+//! acceleration for SHA256-HMAC generation using a key burned into an eFuse
+//! block.
 //!
-//! The Hash-based Message Authentication Code (HMAC) module computes Message
-//! Authentication Codes (MACs) using Hash algorithm and keys as described in
-//! RFC 2104. The hash algorithm is SHA-256, the 256-bit HMAC key is stored in
-//! an eFuse key block and can be set as read-protected, i. e., the key is not
-//! accessible from outside the HMAC accelerator itself.
-//!
-//! The HMAC module can be used in two modes - in ”upstream” mode the HMAC
-//! message is supplied by the user and the calculation result is read back by
-//! the user. In ”downstream” mode the HMAC module is used as a Key Derivation
-//! Function (KDF) for other internal hardwares.
-//!
-//! # Main features
+//! Main features:
 //!
 //! - Standard HMAC-SHA-256 algorithm.
 //! - Hash result only accessible by configurable hardware peripheral (in
@@ -23,16 +16,23 @@
 //!   downstream mode).
 //! - Re-enables soft-disabled JTAG (in downstream mode).
 //!
-//! # Availability on ESP32 family
+//! ## Configuration
+//! The HMAC module can be used in two modes - in ”upstream” mode the HMAC
+//! message is supplied by the user and the calculation result is read back by
+//! the user. In ”downstream” mode the HMAC module is used as a Key Derivation
+//! Function (KDF) for other internal hardwares.
+//!
+//! ### HMAC padding
 //!
-//! The accelerator is available on ESP32-S2, ESP32-S3, ESP32-C3 and ESP32-C6.
+//! The HMAC padding is handled by the driver. In downstream mode, users do not
+//! need to input any message or apply padding. The HMAC module uses a default
+//! 32-byte pattern of 0x00 for re-enabling JTAG and a 32-byte pattern of 0xff
+//! for deriving the AES key for the DS module.
 //!
-//! # HMAC padding
+//! ## Examples
+//! Visit the [HMAC] example to learn how to use the HMAC accelerator
 //!
-//! The HMAC padding is handled by the driver. In
-//! downstream mode, users do not need to input any message or apply padding.
-//! The HMAC module uses a default 32-byte pattern of 0x00 for re-enabling JTAG
-//! and a 32-byte pattern of 0xff for deriving the AES key for the DS module.
+//! [HMAC]: https://github.com/esp-rs/esp-hal/blob/main/examples/src/bin/hmac.rs
 
 use core::convert::Infallible;
 
diff --git a/esp-hal/src/i2c.rs b/esp-hal/src/i2c.rs
index e6e3142075a..f39af673853 100644
--- a/esp-hal/src/i2c.rs
+++ b/esp-hal/src/i2c.rs
@@ -45,9 +45,8 @@
 //! from the community. This includes the [embedded-hal] for both 0.2.x and
 //! 1.x.x versions.
 //!
-//! ### Examples
-//!
-//! #### Read Data from a BMP180 Sensor
+//! ## Examples
+//! ### Read Data from a BMP180 Sensor
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::i2c::I2C;
diff --git a/esp-hal/src/i2s.rs b/esp-hal/src/i2s.rs
index d60810860b0..6ecd98293be 100644
--- a/esp-hal/src/i2s.rs
+++ b/esp-hal/src/i2s.rs
@@ -1,15 +1,18 @@
-//! # I2S Master
+//! # Inter-IC Sound (I2S)
 //!
 //! ## Overview
+//! I2S (Inter-IC Sound) is a synchronous serial communication protocol usually
+//! used for transmitting audio data between two digital audio devices.
+//! Espressif devices may contain more than one I2S peripheral(s). These
+//! peripherals can be configured to input and output sample data via the I2S
+//! driver.
 //!
-//! The I2S Master peripheral driver provides support for the I2S (Inter-IC
-//! Sound) Master functionality on ESP chips. It enables audio data transmission
-//! and reception with external audio devices, such as DACs (Digital-to-Analog
-//! Converters) and ADCs (Analog-to-Digital Converters) through the I2S
-//! interface. Also this module supports different data formats, including
-//! varying data and channel widths, different standards, such as the Philips
-//! standard and configurable pin mappings for I2S clock (BCLK), word select
-//! (WS), and data input/output (DOUT/DIN).
+//!
+//! ## Configuration
+//! I2S supports different data formats, including varying data and channel
+//! widths, different standards, such as the Philips standard and configurable
+//! pin mappings for I2S clock (BCLK), word select (WS), and data input/output
+//! (DOUT/DIN).
 //!
 //! The driver uses DMA (Direct Memory Access) for efficient data transfer and
 //! supports various configurations, such as different data formats, standards
@@ -20,8 +23,7 @@
 //!     - `system` (to configure and enable the I2S peripheral)
 //!
 //! ## Examples
-//!
-//! ### initialization
+//! ### Initialization
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::i2s::I2s;
@@ -73,6 +75,10 @@
 //! }
 //! # }
 //! ```
+//! 
+//! ## Implementation State
+//! - Only master mode is supported.
+//! - Only TDM Philips standard is supported.
 
 use core::marker::PhantomData;
 
diff --git a/esp-hal/src/otg_fs.rs b/esp-hal/src/otg_fs.rs
index 91d9b191b0e..63c8c673de2 100644
--- a/esp-hal/src/otg_fs.rs
+++ b/esp-hal/src/otg_fs.rs
@@ -1,11 +1,13 @@
-//! # USB OTG full-speed peripheral
+//! # USB On-The-Go (USB OTG)
 //!
 //! ## Overview
-//! The USB OTG Full-speed peripheral driver provides support for the USB
-//! On-The-Go (OTG) full-speed functionality on ESP chips, allows communication
+//! The USB OTG Full-speed (FS) peripheral allows communication
 //! with USB devices using either blocking (usb-device) or asynchronous
 //! (embassy-usb) APIs.
 //!
+//! It can operate as either a USB Host or Device, and supports full-speed (FS)
+//! and low-speed (LS) data rates of the USB 2.0 specification.
+//!
 //! The blocking driver uses the `esp_synopsys_usb_otg` crate, which provides
 //! the `USB bus` implementation and `USB peripheral traits`.
 //!
@@ -15,6 +17,7 @@
 //! The module also relies on other peripheral modules, such as `GPIO`,
 //! `system`, and `clock control`, to configure and enable the `USB` peripheral.
 //!
+//! ## Configuration
 //! To use the USB OTG Full-speed peripheral driver, you need to initialize the
 //! peripheral and configure its settings. The [`Usb`] struct represents the USB
 //! peripheral and requires the GPIO pins that implement [`UsbDp`], and
@@ -23,6 +26,15 @@
 //! The returned `Usb` instance can be used with the `usb-device` crate, or it
 //! can be further configured with [`asynch::Driver`] to be used with the
 //! `embassy-usb` crate.
+//!
+//! ## Examples
+//! Visit the [USB Serial] example for an example of using the USB OTG
+//! peripheral.
+//!
+//! [USB Serial]: https://github.com/esp-rs/esp-hal/blob/main/examples/src/bin/usb_serial.rs
+//!
+//! ## Implementation State
+//! - Low-speed (LS) is not supported.
 
 pub use esp_synopsys_usb_otg::UsbBus;
 use esp_synopsys_usb_otg::UsbPeripheral;
diff --git a/esp-hal/src/parl_io.rs b/esp-hal/src/parl_io.rs
index a24d07d910b..5b0e17ed91d 100644
--- a/esp-hal/src/parl_io.rs
+++ b/esp-hal/src/parl_io.rs
@@ -1,112 +1,27 @@
-//! # Parallel IO
+//! # Parallel IO (PARL_IO)
 //!
+//! ## Overview
 //! The Parallel IO peripheral is a general purpose parallel interface that can
 //! be used to connect to external devices such as LED matrix, LCD display,
 //! Printer and Camera. The peripheral has independent TX and RX units. Each
 //! unit can have up to 8 or 16 data signals (depending on your target hardware)
 //! plus 1 or 2 clock signals.
 //!
+//! ## Configuration
 //! The driver uses DMA (Direct Memory Access) for efficient data transfer.
 //!
 //! ## Examples
-//!
-//! ### Initialization for TX
-//! ```rust, no_run
-#![doc = crate::before_snippet!()]
-//! # use esp_hal::gpio::Io;
-//! # use esp_hal::dma_buffers;
-//! # use esp_hal::dma::{Dma, DmaPriority};
-//! # use esp_hal::parl_io::{ClkOutPin, no_clk_pin, BitPackOrder, ParlIoTxOnly, SampleEdge, TxFourBits, TxPinConfigWithValidPin};
-//! # use crate::esp_hal::prelude::_fugit_RateExtU32;
-//!
-//! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
-//!
-//! # let dma = Dma::new(peripherals.DMA);
-//! # let dma_channel = dma.channel0;
-//!
-//! let (tx_buffer, tx_descriptors, _, _) = dma_buffers!(32000, 0);
-//! let buffer = tx_buffer;
-//!
-//! // configure the data pins to use
-//! let tx_pins = TxFourBits::new(io.pins.gpio1, io.pins.gpio2, io.pins.gpio3,
-//! io.pins.gpio4);
-//!
-//! // configure the valid pin which will be driven high during a TX transfer
-//! let mut pin_conf = TxPinConfigWithValidPin::new(tx_pins, io.pins.gpio5);
-//!
-//! let mut parl_io = ParlIoTxOnly::new(
-//!     peripherals.PARL_IO,
-//!     dma_channel.configure(
-//!         false,
-//!         DmaPriority::Priority0,
-//!     ),
-//!     tx_descriptors,
-//!     1.MHz(),
-//!     &clocks,
-//! )
-//! .unwrap();
-//!
-//! // configure a pin for the clock signal
-//! let mut cp = ClkOutPin::new(io.pins.gpio6);
-//!
-//! let mut parl_io_tx = parl_io
-//!     .tx
-//!     .with_config(
-//!         &mut pin_conf,
-//!         &mut cp,
-//!         0,
-//!         SampleEdge::Normal,
-//!         BitPackOrder::Msb,
-//!     )
-//!     .unwrap();
-//!
-//! let mut transfer = parl_io_tx.write_dma(&buffer).unwrap();
-//!
-//! transfer.wait().unwrap();
-//! # }
-//! ```
-//! 
 //! ### Initialization for RX
-//! ```rust, no_run
-#![doc = crate::before_snippet!()]
-//! # use esp_hal::gpio::Io;
-//! # use esp_hal::dma_buffers;
-//! # use esp_hal::dma::{Dma, DmaPriority};
-//! # use esp_hal::parl_io::{no_clk_pin, BitPackOrder, ParlIoRxOnly, RxFourBits};
-//! # use crate::esp_hal::prelude::_fugit_RateExtU32;
-//!
-//! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
+//! See the [Parallel IO RX] example to learn how to initialize the RX and
+//! reading data.
 //!
-//! # let dma = Dma::new(peripherals.DMA);
-//! # let dma_channel = dma.channel0;
+//! [Parallel IO RX]: https://github.com/esp-rs/esp-hal/blob/main/examples/src/bin/parl_io_rx.rs
 //!
-//! let mut rx_pins = RxFourBits::new(io.pins.gpio1, io.pins.gpio2,
-//! io.pins.gpio3, io.pins.gpio4);
-//!
-//! let (_, _, rx_buffer, rx_descriptors) = dma_buffers!(0, 32000);
-//! let mut buffer = rx_buffer;
-//!
-//! let parl_io = ParlIoRxOnly::new(
-//!     peripherals.PARL_IO,
-//!     dma_channel.configure(
-//!         false,
-//!         DmaPriority::Priority0,
-//!     ),
-//!     rx_descriptors,
-//!     1.MHz(),
-//!     &clocks,
-//! )
-//! .unwrap();
-//!
-//! let mut parl_io_rx = parl_io
-//!     .rx
-//!     .with_config(&mut rx_pins, no_clk_pin(), BitPackOrder::Msb, Some(0xfff))
-//!     .unwrap();
+//! ### Initialization for TX
+//! See the [Parallel IO TX] example to learn how to initialize the TX and
+//! transferring data.
 //!
-//! let mut transfer = parl_io_rx.read_dma(&mut buffer).unwrap();
-//! transfer.wait().unwrap();
-//! # }
-//! ```
+//! [Parallel IO TX]: https://github.com/esp-rs/esp-hal/blob/main/examples/src/bin/parl_io_tx.rs
 
 #![warn(missing_docs)]
 
diff --git a/esp-hal/src/peripheral.rs b/esp-hal/src/peripheral.rs
index 6aa24f30820..da05b07c551 100644
--- a/esp-hal/src/peripheral.rs
+++ b/esp-hal/src/peripheral.rs
@@ -6,6 +6,7 @@
 //! exclusive reference to a peripheral. It offers memory efficiency benefits
 //! for zero-sized types.
 //!
+//! ## Configuration
 //! The `PeripheralRef` struct is used to access and interact with peripherals.
 //! It implements the `Deref` and `DerefMut` traits, allowing you to dereference
 //! it to access the underlying peripheral. It also provides methods for cloning
diff --git a/esp-hal/src/prelude.rs b/esp-hal/src/prelude.rs
index 216eb3d197c..7dd64ad8581 100644
--- a/esp-hal/src/prelude.rs
+++ b/esp-hal/src/prelude.rs
@@ -1,7 +1,10 @@
-//! The prelude
+//! # The `esp-hal` Prelude
 //!
-//! Re-exports all traits required for interacting with the various peripheral
-//! drivers implemented in this crate.
+//! ## Overview
+//! The prelude is the list of things that `esp-hal` automatically imports into
+//! every program. It’s kept as small as possible, and is focused on
+//! things, particularly traits, which are used in almost every single Rust
+//! program.
 
 pub use embedded_dma::{
     ReadBuffer as _embedded_dma_ReadBuffer,
diff --git a/esp-hal/src/reset.rs b/esp-hal/src/reset.rs
index d50947f1d15..a1b18f62fce 100644
--- a/esp-hal/src/reset.rs
+++ b/esp-hal/src/reset.rs
@@ -1,32 +1,19 @@
 //! # Hardware and Software Reset
 //!
 //! ## Overview
-//! The Hardware and Software Reset module provides functions for performing
-//! hardware and software resets on ESP chips. It also includes functions for
+//! Espressif chips provide four types of reset that occur at different levels,
+//! namely CPU Reset, Core Reset, System Reset, and Chip Reset. All reset types
+//! mentioned above (except Chip Reset) preserve the data stored in internal
+//! memory.
+//!
+//! The Hardware and Software Reset module provides functions for
+//! performing hardware and software resets and includes functions for
 //! retrieving the reset reason and the wakeup cause after a reset.
 //!
 //! The module defines a set of sleep sources (`SleepSource`) that indicate the
-//! source of the wakeup event. These sources include:
-//!     - external signals
-//!     - timers
-//!     - touchpads
-//!     - ULP programs
-//!     - GPIOs
-//!     - UART
-//!     - Wi-Fi
-//!     - COCPU interrupts
-//!     - BT (Bluetooth)
-//!
-//! The module also includes a set of flags (`WakeupReason`) that represent
-//! different wakeup sources and enable/disable wakeup triggers for specific
-//! events such as:
-//!     - GPIO
-//!     - timers
-//!     - UART
-//!     - touch sensors
-//!     - ULP
-//!     - Wi-Fi
-//!     - BT
+//! source of the wakeup event. It also includes a set of flags (`WakeupReason`)
+//! that represent different wakeup sources and enable/disable wakeup triggers
+//! for specific events.
 
 use crate::rtc_cntl::SocResetReason;
 
diff --git a/esp-hal/src/rmt.rs b/esp-hal/src/rmt.rs
index 720d7ff7c63..fc8d9dbb4c1 100644
--- a/esp-hal/src/rmt.rs
+++ b/esp-hal/src/rmt.rs
@@ -1,11 +1,13 @@
 //! # Remote Control Peripheral (RMT)
 //!
 //! ## Overview
-//! The RMT (Remote Control Transceiver) peripheral was designed to act as an
-//! infrared transceiver. However, due to the flexibility of its data format,
-//! RMT can be extended to a versatile and general-purpose transceiver,
-//! transmitting or receiving many other types of signals.
-//!
+//! The RMT (Remote Control) module is designed to send and receive infrared
+//! remote control signals. A variety of remote control protocols can be
+//! encoded/decoded via software based on the RMT module. The RMT module
+//! converts pulse codes stored in the module’s built-in RAM into output
+//! signals, or converts input signals into pulse codes and stores them in RAM.
+//! In addition, the RMT module optionally modulates its output signals with a
+//! carrier wave, or optionally demodulates and filters its input signals.
 //!
 //! Typically, the RMT peripheral can be used in the following scenarios:
 //! - Transmit or receive infrared signals, with any IR protocols, e.g., NEC
@@ -15,7 +17,7 @@
 //! - Modulate the carrier to the output signal or demodulate the carrier from
 //!   the input signal
 //!
-//! ## Channels
+//! ### Channels
 //! There are
 #![cfg_attr(
     esp32,
@@ -36,10 +38,14 @@
 #![doc = "  "]
 //! For more information, please refer to the
 #![doc = concat!("[ESP-IDF documentation](https://docs.espressif.com/projects/esp-idf/en/latest/", crate::soc::chip!(), "/api-reference/peripherals/rmt.html)")]
-//! ## Examples
+//! ## Configuration
+//! Each TX/RX channel has the same functionality controlled by a dedicated set
+//! of registers and is able to independently transmit or receive data. TX
+//! channels are indicated by n which is used as a placeholder for the channel
+//! number, and by m for RX channels.
 //!
+//! ## Examples
 //! ### Initialization
-//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::peripherals::Peripherals;
diff --git a/esp-hal/src/rng.rs b/esp-hal/src/rng.rs
index 3014a15366c..3b3f4a3fe33 100644
--- a/esp-hal/src/rng.rs
+++ b/esp-hal/src/rng.rs
@@ -1,25 +1,10 @@
-//! # Random Number Generator
+//! # Random Number Generator (RNG)
 //!
 //! ## Overview
-//! The Random Number Generator (RNG) Driver for ESP chips is a software module
-//! that provides an interface to generate random numbers using the RNG
-//! peripheral on ESP chips. This driver allows you to generate random numbers
-//! that can be used for various cryptographic, security, or general-purpose
-//! applications.
-//!
-//! The RNG peripheral on ESP chips produces random numbers based on physical
-//! noise sources, which provide true random numbers under specific conditions
-//! (see conditions below).
-//!
-//! To use the [Rng] Driver, you need to initialize it with the RNG peripheral.
-//! Once initialized, you can generate random numbers by calling the `random`
-//! method, which returns a 32-bit unsigned integer.
-//!
-//! Additionally, this driver implements the
-//! [Read](embedded_hal_02::blocking::rng::Read) trait from the `embedded_hal`
-//! crate, allowing you to generate random bytes by calling the `read` method.
-//
-//! # Important Note
+//! The Random Number Generator (RNG) module provides an interface to generate
+//! random numbers using the RNG peripheral on ESP chips. This driver allows you
+//! to generate random numbers that can be used for various cryptographic,
+//! security, or general-purpose applications.
 //!
 //! There are certain pre-conditions which must be met in order for the RNG to
 //! produce *true* random numbers. The hardware RNG produces true random numbers
@@ -41,6 +26,23 @@
 //!
 //! For more information, please refer to the
 #![doc = concat!("[ESP-IDF documentation](https://docs.espressif.com/projects/esp-idf/en/latest/", crate::soc::chip!(), "/api-reference/system/random.html)")]
+//! ## Configuration
+//! To use the [Rng] Driver, you need to initialize it with the RNG peripheral.
+//! Once initialized, you can generate random numbers by calling the `random`
+//! method, which returns a 32-bit unsigned integer.
+//!
+//! ## Usage
+//! This driver implements the [Read](embedded_hal_02::blocking::rng::Read)
+//! trait from the `embedded_hal` crate, allowing you to generate random bytes
+//! by calling the `read` method. The driver also implements the traits from the
+//! [`rand_core`] crate.
+//!
+//! [`rand_core`]: https://crates.io/crates/rand_core
+//!
+//! ## Examples
+//! Visit the [RNG] example for an example of using the RNG peripheral.
+//!
+//! [RNG]: https://github.com/esp-rs/esp-hal/blob/main/examples/src/bin/rng.rs
 
 use core::marker::PhantomData;
 
diff --git a/esp-hal/src/sha.rs b/esp-hal/src/sha.rs
index 092e22a2c3f..9c812087b9b 100644
--- a/esp-hal/src/sha.rs
+++ b/esp-hal/src/sha.rs
@@ -1,11 +1,12 @@
-//! # Secure Hash Algorithm peripheral driver
+//! # Secure Hash Algorithm (SHA) Accelerator
 //!
 //! ## Overview
-//! This SHA (Secure Hash Algorithm) driver for ESP chips is a software module
-//! that provides an interface to interact with the SHA peripheral on ESP
-//! microcontroller chips. This driver allows you to perform cryptographic hash
-//! operations using various hash algorithms supported by the SHA peripheral,
-//! such as:
+//! This SHA accelerator is a hardware device that speeds up the SHA algorithm
+//! significantly, compared to a SHA algorithm implemented solely in software
+//!
+//! ## Configuration
+//! This driver allows you to perform cryptographic hash operations using
+//! various hash algorithms supported by the SHA peripheral, such as:
 //!    * SHA-1
 //!    * SHA-224
 //!    * SHA-256
@@ -14,7 +15,7 @@
 //!
 //! The driver supports two working modes:
 //!    * Typical SHA
-//!    * DMA-SHA (Direct Memory Access SHA is NOT implemented yet).
+//!    * DMA-SHA
 //!
 //! It provides functions to update the hash calculation with input data, finish
 //! the hash calculation and retrieve the resulting hash value. The SHA
@@ -27,7 +28,7 @@
 //! to retrieve the hash value and repeat the process for a new hash calculation
 //! if needed.
 //!
-//! ## Example
+//! ## Examples
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::sha::Sha;
@@ -60,6 +61,8 @@
 //!
 //! # }
 //! ```
+//! ## Implementation State
+//! - DMA-SHA Mode is not supported.
 
 use core::{convert::Infallible, marker::PhantomData};
 
diff --git a/esp-hal/src/system.rs b/esp-hal/src/system.rs
index a741baebad0..dae540b9b65 100755
--- a/esp-hal/src/system.rs
+++ b/esp-hal/src/system.rs
@@ -20,7 +20,7 @@
 //! It provides an `enable()` method to enable and reset specific peripherals.
 //! The available peripherals are represented by the `Peripheral` enum
 //!
-//! ## Example
+//! ## Examples
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! let peripherals = Peripherals::take();
diff --git a/esp-hal/src/time.rs b/esp-hal/src/time.rs
index 8341c676e96..26ad3180359 100644
--- a/esp-hal/src/time.rs
+++ b/esp-hal/src/time.rs
@@ -1,6 +1,9 @@
+//! # Time
+//!
+//! ## Overview
 //! The `time` module offers a way to get the system uptime.
 //!
-//! ### Example
+//! ## Examples
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::time;
diff --git a/esp-hal/src/trace.rs b/esp-hal/src/trace.rs
index 9cdaa317604..ef6d2a35ca0 100644
--- a/esp-hal/src/trace.rs
+++ b/esp-hal/src/trace.rs
@@ -1,7 +1,6 @@
-//! # RISC­V Trace Encoder (TRACE)
+//! # RISC-­V Trace Encoder (TRACE)
 //!
 //! ## Overview
-//!
 //! The high-performance CPU supports instruction trace interface through the
 //! trace encoder. The trace encoder connects to HP CPU’s instruction trace
 //! interface, compresses the information into smaller packets, and then stores
@@ -19,7 +18,7 @@
 //! That is where instruction trace comes in, which provides trace of the
 //! program execution.
 //!
-//! ## Example
+//! ## Examples
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::trace::Trace;
diff --git a/esp-hal/src/uart.rs b/esp-hal/src/uart.rs
index 8c15b8ab256..c33cc2602f3 100644
--- a/esp-hal/src/uart.rs
+++ b/esp-hal/src/uart.rs
@@ -1,5 +1,6 @@
 //! # Universal Asynchronous Receiver/Transmitter (UART)
 //!
+//! ## Overview
 //! The UART is a hardware peripheral which handles communication using serial
 //! communication interfaces, such as RS232 and RS485. This peripheral provides
 //! a cheap and ubiquitous method for full- and half-duplex communication
@@ -12,7 +13,6 @@
 //! protocols.
 //!
 //! ## Configuration
-//!
 //! Each UART controller is individually configurable, and the usual setting
 //! such as baud rate, data bits, parity, and stop bits can easily be
 //! configured. Additionally, the transmit (TX) and receive (RX) pins need to
@@ -35,7 +35,6 @@
 //! UART instance using the inverted pins.
 //!
 //! ## Usage
-//!
 //! The UART driver implements a number of third-party traits, with the
 //! intention of making the HAL inter-compatible with various device drivers
 //! from the community. This includes, but is not limited to, the [embedded-hal]
@@ -46,9 +45,8 @@
 //! available. See the examples below for more information on how to interact
 //! with this driver.
 //!
-//! ### Examples
-//!
-//! #### Sending and Receiving Data
+//! ## Examples
+//! ### Sending and Receiving Data
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::uart::{config::Config, Uart};
@@ -67,7 +65,7 @@
 //! # }
 //! ```
 //! 
-//! #### Splitting the UART into TX and RX Components
+//! ### Splitting the UART into TX and RX Components
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::uart::{config::Config, Uart};
@@ -90,7 +88,7 @@
 //! # }
 //! ```
 //! 
-//! #### Inverting TX and RX Pins
+//! ### Inverting TX and RX Pins
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::uart::{config::Config, Uart};
@@ -103,7 +101,7 @@
 //! # }
 //! ```
 //! 
-//! #### Constructing TX and RX Components
+//! ### Constructing TX and RX Components
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::uart::{config::Config, UartTx, UartRx};
diff --git a/esp-hal/src/usb_serial_jtag.rs b/esp-hal/src/usb_serial_jtag.rs
index 9a8622c2bcb..db30ef9fd16 100644
--- a/esp-hal/src/usb_serial_jtag.rs
+++ b/esp-hal/src/usb_serial_jtag.rs
@@ -1,5 +1,6 @@
-//! USB Serial/JTAG Controller
+//! USB Serial/JTAG Controller (USB_SERIAL_JTAG)
 //!
+//! ## Overview
 //! The USB Serial/JTAG controller can be used to program the SoC's flash, read
 //! program output, or attach a debugger to the running program. This is
 //! possible for any computer with a USB host (hereafter referred to as 'host'),
@@ -26,7 +27,6 @@
 //!   connect to a host computer
 //!
 //! ## Usage
-//!
 //! The USB Serial/JTAG driver implements a number of third-party traits, with
 //! the intention of making the HAL inter-compatible with various device drivers
 //! from the community. This includes, but is not limited to, the [embedded-hal]
@@ -38,9 +38,7 @@
 //! with this driver.
 //!
 //! ## Examples
-//!
 //! ### Sending and Receiving Data
-//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! use esp_hal::usb_serial_jtag::UsbSerialJtag;