Update some modules documentation (#1726)

* docs: Add inverting documentation and examples

* docs: Update I2C mod docs

* docs: Update LEDC documentation

* docs: FIx format

* Fix a typo in docstring in `esp-hal/src/uart.rs`

---------

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

esp-hal/src/i2c.rs

@@ -1,26 +1,60 @@
-//! # I2C Driver
+//! # Inter-Integrated Circuit (I2C)
 //!
-//! ## Overview
-//! The I2C Peripheral Driver for ESP chips is a software module that
-//! facilitates communication with I2C devices using ESP microcontroller chips.
-//! It provides an interface to initialize, configure, and perform read and
-//! write operations over the I2C bus.
+//! I2C is a serial, synchronous, multi-device, half-duplex communication
+//! protocol that allows co-existence of multiple masters and slaves on the
+//! same bus. I2C uses two bidirectional open-drain lines: serial data line
+//! (SDA) and serial clock line (SCL), pulled up by resistors.
 //!
-//! The driver supports features such as handling transmission errors,
-//! asynchronous operations, and interrupt-based communication, also supports
-//! multiple I2C peripheral instances on `ESP32`, `ESP32H2`, `ESP32S2`, and
-//! `ESP32S3` chips
+//! Espressif devices sometimes have more than one I2C controller (also called
+//! port), responsible for handling communication on the I2C bus. A single I2C
+//! controller can be a master or a slave.
 //!
-//! ## Example
-//! Following code shows how to read data from a BMP180 sensor using I2C.
+//! Typically, an I2C slave device has a 7-bit address or 10-bit address.
+//! Espressif devices supports both I2C Standard-mode (Sm) and Fast-mode
+//! (Fm) which can go up to 100KHz and 400KHz respectively.
 //!
+//! ## Configuration
+//!
+//! Each I2C controller is individually configurable, and the usual setting
+//! such as frequency, timeout, and SDA/SCL pins can easily be configured.
+//!
+//! ```rust, no_run
+#![doc = crate::before_snippet!()]
+//! # use esp_hal::i2c::I2C;
+//! # use esp_hal::gpio::Io;
+//! # use core::option::Option::None;
+//! # use crate::esp_hal::prelude::_fugit_RateExtU32;
+//! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
+//! // Create a new peripheral object with the described wiring
+//! // and standard I2C clock speed
+//! let mut i2c = I2C::new(
+//!     peripherals.I2C0,
+//!     io.pins.gpio1,
+//!     io.pins.gpio2,
+//!     100.kHz(),
+//!     &clocks,
+//!     None,
+//! );
+//! # }
+//! ```
+//! 
+//! ## Usage
+//!
+//! The I2C 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 the [embedded-hal] for both 0.2.x and
+//! 1.x.x versions.
+//!
+//! ### Examples
+//!
+//! #### Read Data from a BMP180 Sensor
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::i2c::I2C;
 //! # use esp_hal::gpio::Io;
 //! # use core::option::Option::None;
 //! # use crate::esp_hal::prelude::_fugit_RateExtU32;
-//! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
+//! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 //! // Create a new peripheral object with the described wiring
 //! // and standard I2C clock speed
 //! let mut i2c = I2C::new(

esp-hal/src/ledc/mod.rs

@@ -1,10 +1,22 @@
-//! # LEDC (LED PWM Controller) peripheral control
+//! # LED Controller (LEDC)
 //!
-//! Currently only supports fixed-frequency output. Interrupts are not currently
-//! implemented. High Speed channels are available for the ESP32 only, while Low
-//! Speed channels are available for all supported chips.
+//! The LED control (LEDC) peripheral is primarily designed to control the
+//! intensity of LEDs, although it can also be used to generate PWM signals for
+//! other purposes. It has multiple channels which can generate independent
+//! waveforms that can be used, for example, to drive RGB LED devices.
 //!
-//! # LowSpeed Example:
+//! The PWM controller can automatically increase or decrease the duty cycle
+//! gradually, allowing for fades without any processor interference.
+//!
+//! ## Configuration
+//!
+//! Currently only supports fixed-frequency output. High Speed channels are
+//! available for the ESP32 only, while Low Speed channels are available for all
+//! supported chips.
+//!
+//! ### Examples
+//!
+//! #### Low Speed Channel
 //!
 //! The following will configure the Low Speed Channel0 to 24kHz output with
 //! 10% duty using the ABPClock
@@ -47,7 +59,8 @@
 //! # }
 //! ```
 //! 
-//! # Unsupported
+//! ## Unsupported
+//!
 //! - Source clock selection
 //! - Interrupts
 

esp-hal/src/parl_io.rs

@@ -1,6 +1,5 @@
 //! # Parallel 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

esp-hal/src/uart.rs

@@ -1,4 +1,4 @@
-//! Universal Asynchronous Receiver/Transmitter (UART)
+//! # Universal Asynchronous Receiver/Transmitter (UART)
 //!
 //! The UART is a hardware peripheral which handles communication using serial
 //! communication interfaces, such as RS232 and RS485. This peripheral provides
@@ -15,8 +15,8 @@
 //!
 //! 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 can be
-//! specified.
+//! configured. Additionally, the transmit (TX) and receive (RX) pins need to
+//! be specified.
 //!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
@@ -30,6 +30,10 @@
 //! # }
 //! ```
 //! 
+//! The UART controller can be configured to invert the polarity of the pins.
+//! This is achived by inverting the desired pins, and then constucting the
+//! UART instance using the inverted pins.
+//!
 //! ## Usage
 //!
 //! The UART driver implements a number of third-party traits, with the
@@ -86,6 +90,33 @@
 //! # }
 //! ```
 //! 
+//! #### Inverting TX and RX Pins
+//! ```rust, no_run
+#![doc = crate::before_snippet!()]
+//! # use esp_hal::uart::{config::Config, Uart};
+//! use esp_hal::gpio::{Io, any_pin::AnyPin};
+//! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
+//!
+//! let tx = AnyPin::new_inverted(io.pins.gpio1);
+//! let rx = AnyPin::new_inverted(io.pins.gpio2);
+//! let mut uart1 = Uart::new(peripherals.UART1, &clocks, tx, rx).unwrap();
+//! # }
+//! ```
+//! 
+//! #### Constructing TX and RX Components
+//! ```rust, no_run
+#![doc = crate::before_snippet!()]
+//! # use esp_hal::uart::{config::Config, UartTx, UartRx};
+//! use esp_hal::gpio::{Io, any_pin::AnyPin};
+//! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
+//!
+//! let tx = UartTx::new(peripherals.UART0, &clocks, None,
+//!     io.pins.gpio1).unwrap();
+//! let rx = UartRx::new(peripherals.UART1, &clocks, None,
+//!     io.pins.gpio2).unwrap();
+//! # }
+//! ```
+//! 
 //! [embedded-hal]: https://docs.rs/embedded-hal/latest/embedded_hal/
 //! [embedded-io]: https://docs.rs/embedded-io/latest/embedded_io/
 //! [embedded-hal-async]: https://docs.rs/embedded-hal-async/latest/embedded_hal_async/

hil-test/README.md

@@ -92,7 +92,7 @@ Our self hosted runners have the following setup:
 
 [`hil.yml`]: https://github.com/esp-rs/esp-hal/blob/main/.github/workflows/hil.yml
 
-#### VM Setup
+#### RPi Setup
 ```bash
 # Install Rust:
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --default-toolchain stable -y --profile minimal
@@ -123,4 +123,5 @@ sudo reboot
 //% CHIPS: esp32 esp32c3 esp32c6 esp32h2 esp32s2 esp32s3
 ```
 If the test is supported by all the targets, you can omit the header.
+
 6. Write some documentation at the top of the `tests/$PERIPHERAL.rs` file with the pins being used and the required connections, if applicable.