Add more docs

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,

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

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