Update module documentation (#1763)

* docs: Update GPIO docs

* docs: Update other GPIO modules docs

* docs: Update AES mod documentation

* docs: Update Analog and ADC mod documentation

* docs: Update DAC mod documentation

* docs: Update lib docs

* docs: Update clock  mod documentation

* docs: Update dma  mod documentation

* docs: Update interrupt  mod documentation

* docs: Update lcd_cam  mod documentation

* docs: Update ledc  mod documentation

* docs: Update mcpwm mod documentation

* docs: Update pcnt mod documentation

* docs: Update rom mod documentation

* docs: Update rsa mod documentation

* docs: Update rtc_cntl mod documentation

* docs: Update spi mod documentation

* docs: Update timer mod documentation

* docs: Update twai mod documentation

* docs: Format headers

* style: Fix fmt

* refactor: Change visibility instead of hidding docs

* style: Fix header

* Fix typo

Co-authored-by: Juraj Sadel <jurajsadel@gmail.com>

* Fix typo

Co-authored-by: Juraj Sadel <jurajsadel@gmail.com>

* Fix typo

Co-authored-by: Juraj Sadel <jurajsadel@gmail.com>

* Fix typo

Co-authored-by: Juraj Sadel <jurajsadel@gmail.com>

* Fix typo

Co-authored-by: Juraj Sadel <jurajsadel@gmail.com>

* docs: Add tracking issue

* docs: Remove architecture and simplify sentence

* fix: Update visibilities remove hidden docs

* Fix type

Co-authored-by: Jesse Braham <jessebraham@users.noreply.github.com>

* docs: Improve wording

Co-authored-by: Jesse Braham <jessebraham@users.noreply.github.com>

---------

Co-authored-by: Juraj Sadel <jurajsadel@gmail.com>
Co-authored-by: Jesse Braham <jessebraham@users.noreply.github.com>

esp-hal/src/aes/mod.rs

@@ -1,17 +1,21 @@
-//! # Advanced Encryption Standard (AES) support.
+//! # Advanced Encryption Standard (AES).
 //!
 //! ## Overview
+//! The AES accelerator is a hardware device that speeds up computation
+//! using AES algorithm significantly, compared to AES algorithms implemented
+//! solely in software.  The AES accelerator has two working modes, which are
+//! Typical AES and AES-DMA.
 //!
-//! The AES module provides an interface to interact with the AES peripheral,
-//! provides encryption and decryption capabilities for ESP chips using the AES
-//! algorithm. We currently support the following AES encryption modes:
+//! ## Configuration
+//! The AES peripheral can be configured to encrypt or decrypt data using
+//! different encryption/decryption modes.
 //!
-//! * AES-128
-//! * AES-192
-//! * AES-256
-//!
-//! ## Example
+//! When using AES-DMA, the peripheral can be configured to use different block
+//! cipher modes such as ECB, CBC, OFB, CTR, CFB8, and CFB128.
 //!
+//! ## Examples
+//! ### Encrypting and Decrypting a Message
+//! Simple example of encrypting and decrypting a message using AES-128:
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::aes::{Aes, Mode};
@@ -32,21 +36,15 @@
 //! # }
 //! ```
 //! 
-//! ### Implementation State
-//!
-//! * DMA mode is currently not supported on ESP32 and ESP32S2 ⚠️
-//!
-//! ## DMA-AES Mode
-//!
-//! Supports 6 block cipher modes including `ECB/CBC/OFB/CTR/CFB8/CFB128`.
-//!
-//! * Initialization vector (IV) is currently not supported ⚠️
+//! ### AES-DMA
+//! Visit the [AES-DMA] test for a more advanced example of using AES-DMA
+//! mode.
 //!
-//! ⚠️: The examples for AES with DMA peripheral are quite extensive, so for a more
-//! detailed study of how to use this driver please visit [the repository
-//! with corresponding example].
+//! [AES-DMA]: https://github.com/esp-rs/esp-hal/blob/main/hil-test/tests/aes_dma.rs
 //!
-//! [the repository with corresponding example]: https://github.com/esp-rs/esp-hal/blob/main/hil-test/tests/aes_dma.rs
+//! ## Implementation State
+//! * AES-DMA mode is currently not supported on ESP32 and ESP32S2
+//! * AES-DMA Initialization Vector (IV) is currently not supported
 
 use crate::{
     peripheral::{Peripheral, PeripheralRef},

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

@@ -1,11 +1,24 @@
 //! # Analog to Digital Converter (ADC)
 //!
-//! The Analog to Digital Converter (ADC) is integrated on the chip, and is
-//! capable of measuring analog signals from specific analog I/O pins. One or
-//! more ADC units are available, depending on the device being used.
+//! ## Overview
+//! The ADC is integrated on the chip, and is capable of measuring analog
+//! signals from specific analog I/O pins. One or more ADC units are available,
+//! depending on the device being used.
 //!
-//! ## Example
+//! ## Configuration
+//! The ADC can be configured to measure analog signals from specific pins. The
+//! configuration includes the resolution of the ADC, the attenuation of the
+//! input signal, and the pins to be measured.
 //!
+//! Some targets also support ADC calibration via different schemes like
+//! basic calibration, curve fitting or linear interpolation. The calibration
+//! schemes can be used to improve the accuracy of the ADC readings.
+//!
+//! ## Usage
+//! The ADC driver implements the `embedded-hal@0.2.x` ADC traits.
+//!
+//! ## Examples
+//! #### Read an analog signal from a pin
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::analog::adc::AdcConfig;
@@ -25,8 +38,8 @@
 )]
 //! let mut adc1_config = AdcConfig::new();
 //! let mut pin = adc1_config.enable_pin(analog_pin,
-//! Attenuation::Attenuation11dB); let mut adc1 = Adc::new(peripherals.ADC1,
-//! adc1_config);
+//!               Attenuation::Attenuation11dB);
+//! let mut adc1 = Adc::new(peripherals.ADC1, adc1_config);
 //!
 //! let mut delay = Delay::new(&clocks);
 //!
@@ -37,7 +50,10 @@
 //! }
 //! # }
 //! ```
-
+//! ## Implementation State
+//! - [ADC calibration is not implemented for all targets].
+//!
+//! [ADC calibration is not implemented for all targets]: https://github.com/esp-rs/esp-hal/issues/326
 use core::marker::PhantomData;
 
 pub use self::implementation::*;

esp-hal/src/analog/dac.rs

@@ -1,16 +1,20 @@
 //! # Digital to Analog Converter (DAC)
 //!
-//! The `dac` module enables users to generate analog output signals with
-//! precise control over voltage levels using one of the onboard
-//! digital-to-analog converters (DAC).
+//! ## Overview
+//! Espressif devices usually have multiple DAC channels. Each DAC channel can
+//! convert the digital value 0~255 to the analog voltage 0~Vref (The reference
+//! voltage 'Vref' here is input from an input pin)
 //!
-//! Two 8-bit DAC channels are available. Each DAC channel can convert the
-//! digital value 0-255 to the analog voltage 0-3.3v. Developers can choose the
-//! DAC channel they want to use based on the GPIO pin assignments for each
-//! channel.
+//! The DAC peripheral supports outputting analog signal in the multiple ways.
 //!
-//! ## Example
+//! Two 8-bit DAC channels are available.
 //!
+//! ## Configuration
+//! Developers can choose the  DAC channel they want to use based on the GPIO
+//! pin assignments for each channel.
+//!
+//! ## Examples
+//! ### Write a value to a DAC channel
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::gpio::Io;

esp-hal/src/analog/mod.rs

@@ -1,5 +1,6 @@
 //! # Analog Peripherals
 //!
+//! ## Overview
 //! The `analog` module provides drivers for the various analog peripherals
 //! available on the device. For more information about a peripheral driver,
 //! please refer to the relevant module documentation.

esp-hal/src/clock/mod.rs

@@ -1,17 +1,25 @@
 //! # Clock Control
 //!
 //! ## Overview
-//! This `Clock` driver provides an interface for configuring and managing
-//! various clocks present on the `ESP` microcontrollers.
+//! Clocks are mainly sourced from oscillator (OSC), RC, and PLL circuits, and
+//! then processed by the dividers or selectors, which allows most functional
+//! modules to select their working clock according to their power consumption
+//! and performance requirements.
 //!
+//! The clock subsystem  is used to source and distribute system/module clocks
+//! from a range of root clocks. The clock tree driver maintains the basic
+//! functionality of the system clock and the intricate relationship among
+//! module clocks.
+//!
+//! ## Configuration
 //! Proper clock configuration is essential for the correct functioning of the
 //! microcontroller and its peripherals.
 //!
 //! The `Clock` driver supports configuring multiple clocks, including:
 //!   * CPU clock
 //!   * APB (Advanced Peripheral Bus) clock
-//!   * XTAL clock
-//!   * PLL clock
+//!   * XTAL (External Crystal) clock
+//!   * PLL (Phase Lock Loop) clock
 //!
 //! and other specific clocks based on the ESP microcontroller's architecture.
 //!
@@ -26,20 +34,19 @@
 //!
 //! and others, depending on the microcontroller model.
 //!
-//! #### Clock Control
+//! ### Clock Control
 //! The `ClockControl` struct allows users to configure the desired clock
 //! frequencies before applying them. It offers flexibility in selecting
 //! appropriate clock frequencies based on specific application requirements.
 //!
-//! #### Frozen clock frequencies
+//! ### Frozen Clock Frequencies
 //! Once the clock configuration is applied using the `freeze` function of the
 //! ClockControl struct, the clock frequencies become `frozen` and cannot be
 //! changed. The `Clocks` struct is returned after freezing, providing read-only
 //! access to the configured clock frequencies.
 //!
 //! ## Examples
-//!
-//! #### Initialize with default clock frequency for this chip
+//! ### Initialize With Different Clock Frequencies
 //! ```rust, no_run
 //! # #![no_std]
 //! # use esp_hal::peripherals::Peripherals;

esp-hal/src/delay.rs

@@ -10,7 +10,7 @@
 //! block for at least the amount of time specified, but accuracy can be
 //! affected by many factors, including interrupt usage.
 //!
-//! ## Example
+//! ## Examples
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::delay::Delay;

esp-hal/src/dma/gdma.rs

@@ -1,23 +1,21 @@
-//! # Direct Memory Access
+//! # General Direct Memory Access (GMDA)
 //!
 //! ## Overview
+//! GDMA is a feature that allows peripheral-to-memory, memory-to-peripheral,
+//! and memory-to-memory data transfer at high speed. The CPU is not involved in
+//! the GDMA transfer and therefore is more efficient with less workload.
 //!
-//! The GDMA (General DMA) module is a part of the DMA (Direct Memory Access)
-//! driver for ESP chips. Of the Espressif chip range, every chip except of
-//! `ESP32` and `ESP32-S2` uses the `GDMA` type of direct memory access.
+//! The `GDMA` module provides multiple DMA channels, each capable of managing
+//! data transfer for various peripherals.
 //!
-//! DMA is a hardware feature that allows data transfer between memory and
-//! peripherals without involving the CPU, resulting in efficient data movement
-//! and reduced CPU overhead. The `GDMA` module provides multiple DMA channels,
-//! each capable of managing data transfer for various peripherals.
+//! ## Configuration
+//! GDMA peripheral can be initializes using the `new` function, which requires
+//! a DMA peripheral instance and a clock control reference.
 //!
+//! ## Usage
 //! This module implements DMA channels, such as `channel0`, `channel1` and so
 //! on. Each channel struct implements the `ChannelTypes` trait, which provides
 //! associated types for peripheral configuration.
-//!
-//! GDMA peripheral can be initializes using the `new` function, which requires
-//! a DMA peripheral instance and a clock control reference.
-//!
 //! <em>PS: Note that the number of DMA channels is chip-specific.</em>
 
 use crate::{

esp-hal/src/dma/mod.rs

@@ -1,20 +1,17 @@
-//! # Direct Memory Access
+//! # Direct Memory Access (DMA)
 //!
 //! ## Overview
-//!
-//! The `DMA` driver provides an interface to efficiently transfer data between
+//! The DMA driver provides an interface to efficiently transfer data between
 //! different memory regions and peripherals within the ESP microcontroller
-//! without involving the CPU. The `Direct Memory Access` (DMA) controller is a
-//! hardware block responsible for managing these data transfers.
+//! without involving the CPU. The DMA controller is reponsible for managing
+//! these data transfers.
 //!
 //! Notice, that this module is a common version of the DMA driver, `ESP32` and
 //! `ESP32-S2` are using older `PDMA` controller, whenever other chips are using
 //! newer `GDMA` controller.
 //!
-//! ## Example
-//!
-//! ### Initialize and utilize DMA controller in `SPI`
-//!
+//! ## Examples
+//! ### Initialize and Utilize DMA Controller in `SPI`
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::dma_buffers;

esp-hal/src/dma/pdma.rs

@@ -1,9 +1,7 @@
 //! # Direct Memory Access
 //!
 //! ## Overview
-//!
-//! The `pdma` module is part of the DMA (Direct Memory Access) driver of
-//! `ESP32` and `ESP32-S2`.
+//! The `pdma` module is part of the DMA driver of `ESP32` and `ESP32-S2`.
 //!
 //! This module provides efficient direct data transfer capabilities between
 //! peripherals and memory without involving the CPU. It enables bidirectional

esp-hal/src/gpio/any_pin.rs

@@ -2,7 +2,7 @@
 //! These are useful to pass them into peripheral drivers.
 //!
 //! If you want a generic pin for GPIO input/output look into
-//! [Output],[OutputOpenDrain] and [Input]
+//! [Output],[OutputOpenDrain], [Input] and [Flex].
 
 use super::*;
 

esp-hal/src/gpio/etm.rs

@@ -1,18 +1,18 @@
-//! # Event Task Matrix Function
+//! # Event Task Matrix (ETM)
 //!
 //! ## Overview
-//!
 //! GPIO supports ETM function, that is, the ETM task of GPIO can be
 //! triggered by the ETM event of any peripheral, or the ETM task of any
 //! peripheral can be triggered by the ETM event of GPIO.
 //!
-//! The GPIO ETM provides eight task channels. The ETM tasks that each task
+//! ## Configuration
+//! The GPIO ETM provides several task channels. The ETM tasks that each task
 //! channel can receive are:
 //! - SET: GPIO goes high when triggered
 //! - CLEAR: GPIO goes low when triggered
 //! - TOGGLE: GPIO toggle level when triggered.
 //!
-//! GPIO has eight event channels, and the ETM events that each event
+//! GPIO has several event channels, and the ETM events that each event
 //! channel can generate are:
 //! - RISE_EDGE: Indicates that the output signal of the corresponding GPIO has
 //!   a rising edge
@@ -21,7 +21,8 @@
 //! - ANY_EDGE: Indicates that the output signal of the corresponding GPIO is
 //!   reversed
 //!
-//! ## Example
+//! ## Examples
+//! ### Toogle an LED When a Button is Pressed
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::gpio::Io;

esp-hal/src/gpio/lp_io.rs

@@ -1,10 +1,11 @@
 //! Low Power IO (LP_IO)
 //!
 //! # Overview
-//!
 //! The hardware provides a couple of GPIO pins with low power (LP)
-//! capabilities and analog functions. These pins can be controlled by
-//! either IO MUX or LP IO MUX.
+//! capabilities and analog functions.
+//!
+//! ## Configuration
+//! These pins can be controlled by either IO MUX or LP IO MUX.
 //!
 //! If controlled by LP IO MUX, these pins will bypass IO MUX and GPIO
 //! matrix for the use by ULP and peripherals in LP system.
@@ -14,6 +15,7 @@
 //! chip from Deep-sleep.
 //!
 //! # Example
+//! ## Configure a LP Pin as Output
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! use esp_hal::gpio::Io;