From dd1b2bef86b7d72749d701f3731af419aaf1eaa3 Mon Sep 17 00:00:00 2001
From: liebman <liebman@zod.com>
Date: Thu, 29 Aug 2024 07:43:31 -0700
Subject: [PATCH] small cleanup and add a few internal docs

---
 esp-hal/src/i2c.rs | 60 ++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 50 insertions(+), 10 deletions(-)

diff --git a/esp-hal/src/i2c.rs b/esp-hal/src/i2c.rs
index 20b0b09af8..a04a1224bd 100644
--- a/esp-hal/src/i2c.rs
+++ b/esp-hal/src/i2c.rs
@@ -304,7 +304,7 @@ where
                         address,
                         bytes,
                         last_op != Op::Write,
-                        op_iter.peek().is_none(),
+                        next_op == Op::None,
                         cmd_iterator,
                     )?;
                     last_op = Op::Write;
@@ -318,7 +318,7 @@ where
                         address,
                         buffer,
                         last_op != Op::Read,
-                        op_iter.peek().is_none(),
+                        next_op == Op::None,
                         next_op == Op::Read,
                         cmd_iterator,
                     )?;
@@ -770,6 +770,14 @@ mod asynch {
             Ok(())
         }
 
+        /// Executes an async I2C write operation.
+        /// - `addr` is the address of the slave device.
+        /// - `bytes` is the data two be sent.
+        /// - `start` indicates whether the operation should start by a START
+        ///   condition and sending the address.
+        /// - `stop` indicates whether the operation should end with a STOP
+        ///   condition.
+        /// - `cmd_iterator` is an iterator over the command registers.
         async fn write_operation<'a, I>(
             &self,
             address: u8,
@@ -802,6 +810,16 @@ mod asynch {
             Ok(())
         }
 
+        /// Executes an async I2C read operation.
+        /// - `addr` is the address of the slave device.
+        /// - `buffer` is the buffer to store the read data.
+        /// - `start` indicates whether the operation should start by a START
+        ///   condition and sending the address.
+        /// - `stop` indicates whether the operation should end with a STOP
+        ///   condition.
+        /// - `will_continue` indicates whether there is another read operation
+        ///   following this one and we should not nack the last byte.
+        /// - `cmd_iterator` is an iterator over the command registers.
         async fn read_operation<'a, I>(
             &self,
             address: u8,
@@ -960,7 +978,7 @@ mod asynch {
                             address,
                             bytes,
                             last_op != Op::Write,
-                            op_iter.peek().is_none(),
+                            next_op == Op::None,
                             cmd_iterator,
                         )
                         .await?;
@@ -974,7 +992,7 @@ mod asynch {
                             address,
                             buffer,
                             last_op != Op::Read,
-                            op_iter.peek().is_none(),
+                            next_op == Op::None,
                             next_op == Op::Read,
                             cmd_iterator,
                         )
@@ -1493,6 +1511,11 @@ pub trait Instance: crate::private::Sealed {
     }
 
     /// Configures the I2C peripheral for a write operation.
+    /// - `addr` is the address of the slave device.
+    /// - `bytes` is the data two be sent.
+    /// - `start` indicates whether the operation should start by a START
+    ///   condition and sending the address.
+    /// - `cmd_iterator` is an iterator over the command registers.
     fn setup_write<'a, I>(
         &self,
         addr: u8,
@@ -1533,12 +1556,13 @@ pub trait Instance: crate::private::Sealed {
     }
 
     /// Configures the I2C peripheral for a read operation.
-    /// `addr` is the address of the slave device.
-    /// `buffer` is the buffer to store the read data.
-    /// `start` indicates whether the operation should start by writing the
-    /// address `will_continue` indicates whether there is another read
-    /// operation following this one and we should not nack the last byte.
-    /// The `cmd_iterator` parameter is an iterator over the command registers.
+    /// - `addr` is the address of the slave device.
+    /// - `buffer` is the buffer to store the read data.
+    /// - `start` indicates whether the operation should start by a START
+    ///   condition and sending the address.
+    /// - `will_continue` indicates whether there is another read operation
+    ///   following this one and we should not nack the last byte.
+    /// - `cmd_iterator` is an iterator over the command registers.
     fn setup_read<'a, I>(
         &self,
         addr: u8,
@@ -1945,6 +1969,13 @@ pub trait Instance: crate::private::Sealed {
     }
 
     /// Executes an I2C write operation.
+    /// - `addr` is the address of the slave device.
+    /// - `bytes` is the data two be sent.
+    /// - `start` indicates whether the operation should start by a START
+    ///   condition and sending the address.
+    /// - `stop` indicates whether the operation should end with a STOP
+    ///   condition.
+    /// - `cmd_iterator` is an iterator over the command registers.
     fn write_operation<'a, I>(
         &self,
         address: u8,
@@ -1978,6 +2009,15 @@ pub trait Instance: crate::private::Sealed {
     }
 
     /// Executes an I2C read operation.
+    /// - `addr` is the address of the slave device.
+    /// - `buffer` is the buffer to store the read data.
+    /// - `start` indicates whether the operation should start by a START
+    ///   condition and sending the address.
+    /// - `stop` indicates whether the operation should end with a STOP
+    ///   condition.
+    /// - `will_continue` indicates whether there is another read operation
+    ///   following this one and we should not nack the last byte.
+    /// - `cmd_iterator` is an iterator over the command registers.
     fn read_operation<'a, I>(
         &self,
         address: u8,