Update module documentation - Part 2

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.

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,

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;

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

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;

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;
 

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;

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;
 

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;