From fccabc3cc2f0129754bea9d28e85d0f2f43c4317 Mon Sep 17 00:00:00 2001
From: Kirill Mikhailov <konnor1980@yandex.ru>
Date: Thu, 22 Aug 2024 12:56:57 +0200
Subject: [PATCH] Address the rest of reviews

---
 esp-hal/src/gpio/mod.rs   |  6 ++++++
 esp-hal/src/i2c.rs        | 14 ++++++++++++++
 esp-hal/src/peripheral.rs | 11 +++++++++--
 3 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/esp-hal/src/gpio/mod.rs b/esp-hal/src/gpio/mod.rs
index d6e796406e1..11a363b65dc 100644
--- a/esp-hal/src/gpio/mod.rs
+++ b/esp-hal/src/gpio/mod.rs
@@ -182,6 +182,12 @@ pub enum DriveStrength {
 }
 
 /// Alternate functions
+///
+/// GPIO pins can be configured for various functions, such as GPIO
+/// or being directly connected to a peripheral's signal like UART, SPI, etc.
+/// The `AlternateFunction` enum allows to select one of several functions that
+/// a pin can perform, rather than using it as a general-purpose input or
+/// output.
 #[derive(PartialEq)]
 pub enum AlternateFunction {
     /// Alternate function 0.
diff --git a/esp-hal/src/i2c.rs b/esp-hal/src/i2c.rs
index ba774cfba6d..b4c72604fea 100644
--- a/esp-hal/src/i2c.rs
+++ b/esp-hal/src/i2c.rs
@@ -1642,6 +1642,12 @@ pub trait Instance: crate::private::Sealed {
     }
 
     /// Checks for I2C transmission errors and handles them.
+    ///
+    /// This function inspects specific I2C-related interrupts to detect errors
+    /// during communication, such as timeouts, failed acknowledgments, or
+    /// arbitration loss. If an error is detected, the function handles it
+    /// by resetting the I2C peripheral to clear the error condition and then
+    /// returns an appropriate error.
     fn check_errors(&self) -> Result<(), Error> {
         let interrupts = self.register_block().int_raw().read();
 
@@ -1683,6 +1689,14 @@ pub trait Instance: crate::private::Sealed {
     }
 
     /// Updates the configuration of the I2C peripheral.
+    ///
+    /// This function ensures that the configuration values, such as clock
+    /// settings, SDA/SCL filtering, timeouts, and other operational
+    /// parameters, which are configured in other functions, are properly
+    /// propagated to the I2C hardware. This step is necessary to synchronize
+    /// the software-configured settings with the peripheral's internal
+    /// registers, ensuring that the hardware behaves according to the
+    /// current configuration.
     fn update_config(&self) {
         // Ensure that the configuration of the peripheral is correctly propagated
         // (only necessary for C2, C3, C6, H2 and S3 variant)
diff --git a/esp-hal/src/peripheral.rs b/esp-hal/src/peripheral.rs
index fdca2391c20..e2bf8a4494b 100644
--- a/esp-hal/src/peripheral.rs
+++ b/esp-hal/src/peripheral.rs
@@ -353,12 +353,16 @@ mod peripheral_macros {
 
     #[doc(hidden)]
     #[macro_export]
+    /// Macro to create a peripheral structure.
     macro_rules! create_peripheral {
         ($(#[$cfg:meta])? $name:ident <= virtual) => {
             $(#[$cfg])?
             #[derive(Debug)]
             #[allow(non_camel_case_types)]
-            /// Macro to create a peripheral structure.
+            /// Represents a virtual peripheral with no associated hardware.
+            /// 
+            /// This struct is generated by the `create_peripheral!` macro when the peripheral
+            /// is defined as virtual.
             pub struct $name { _inner: () }
 
             $(#[$cfg])?
@@ -389,7 +393,10 @@ mod peripheral_macros {
             $(#[$cfg])?
             #[derive(Debug)]
             #[allow(non_camel_case_types)]
-            /// Macro to create a peripheral structure.
+            /// Represents a concrete hardware peripheral.
+            ///
+            /// This struct is generated by the `create_peripheral!` macro when the peripheral
+            /// is tied to an actual hardware device.
             pub struct $name { _inner: () }
 
             $(#[$cfg])?