Add more docs

3 files changed, 9 insertions, 0 deletions

diff --git a/embassy-stm32/src/i2c/timeout.rs b/embassy-stm32/src/i2c/timeout.rs
index fd9a753a5..4fca1ca2b 100644
--- a/embassy-stm32/src/i2c/timeout.rs
+++ b/embassy-stm32/src/i2c/timeout.rs
@@ -3,6 +3,9 @@ use embassy_time::{Duration, Instant};
 use super::{Error, I2c, Instance};
 
 /// An I2C wrapper, which provides `embassy-time` based timeouts for all `embedded-hal` trait methods.
+///
+/// This is useful for recovering from a shorted bus or a device stuck in a clock stretching state.
+/// A regular [I2c] would freeze until condition is removed.
 pub struct TimeoutI2c<'d, T: Instance, TXDMA, RXDMA> {
     i2c: &'d mut I2c<'d, T, TXDMA, RXDMA>,
     timeout: Duration,
diff --git a/examples/stm32f4/src/bin/i2c.rs b/examples/stm32f4/src/bin/i2c.rs
index 12965d2b8..6e51c211d 100644
--- a/examples/stm32f4/src/bin/i2c.rs
+++ b/examples/stm32f4/src/bin/i2c.rs
@@ -30,6 +30,9 @@ async fn main(_spawner: Spawner) -> ! {
         Hertz(100_000),
         Default::default(),
     );
+
+    // I2C bus can freeze if SCL line is shorted or due to a broken device that clock stretches for too long.
+    // TimeoutI2c allows recovering from such errors by throwing `Error::Timeout` after a given delay.
     let mut timeout_i2c = TimeoutI2c::new(&mut i2c, Duration::from_millis(1000));
 
     let mut data = [0u8; 1];
diff --git a/examples/stm32h7/src/bin/i2c.rs b/examples/stm32h7/src/bin/i2c.rs
index 7a314b996..d44319ae6 100644
--- a/examples/stm32h7/src/bin/i2c.rs
+++ b/examples/stm32h7/src/bin/i2c.rs
@@ -29,6 +29,9 @@ async fn main(_spawner: Spawner) -> ! {
         Hertz(100_000),
         Default::default(),
     );
+
+    // I2C bus can freeze if SCL line is shorted or due to a broken device that clock stretches for too long.
+    // TimeoutI2c allows recovering from such errors by throwing `Error::Timeout` after a given delay.
     let mut timeout_i2c = TimeoutI2c::new(&mut i2c, Duration::from_millis(1000));
 
     let mut data = [0u8; 1];