Resolve C-EXAMPLE: Gpio and I2c (#3746)

* docs: C-example for i2c

* docs: C-example for gpio

* feat: Mark Flex as unstable

* docs: Remove outdate fixmes

* fix: Clippy lint

* docs: Add time doc examples

* docs: Dont hide imports

* docs: Add link to Peripheral section

* docs: Avoid unsafe when posible

* feat: Generate api baseline

esp-hal/src/clock/mod.rs

@@ -119,6 +119,17 @@ impl Default for CpuClock {
 
 impl CpuClock {
     /// Use the highest possible frequency for a particular chip.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::clock::CpuClock;
+    /// let config = esp_hal::Config::default().with_cpu_clock(CpuClock::max());
+    /// let peripherals = esp_hal::init(config);
+    /// # Ok(())
+    /// # }
+    /// ```
     pub const fn max() -> Self {
         cfg_if::cfg_if! {
             if #[cfg(esp32c2)] {

esp-hal/src/gpio/asynch.rs

@@ -101,6 +101,21 @@ impl Input<'_> {
     ///
     /// Note that calling this function will overwrite previous
     /// [`listen`][Self::listen] operations for this pin.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Event, Input, InputConfig};
+    /// let mut input_pin = Input::new(
+    ///     peripherals.GPIO4,
+    ///     InputConfig::default(),
+    /// );
+    ///
+    /// input_pin.wait_for(Event::LowLevel).await;
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub async fn wait_for(&mut self, event: Event) {
         self.pin.wait_for(event).await
@@ -109,6 +124,21 @@ impl Input<'_> {
     /// Wait until the pin is high.
     ///
     /// See [Self::wait_for] for more information.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Event, Input, InputConfig};
+    /// let mut input_pin = Input::new(
+    ///     peripherals.GPIO4,
+    ///     InputConfig::default(),
+    /// );
+    ///
+    /// input_pin.wait_for_high().await;
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub async fn wait_for_high(&mut self) {
         self.pin.wait_for_high().await
@@ -117,6 +147,21 @@ impl Input<'_> {
     /// Wait until the pin is low.
     ///
     /// See [Self::wait_for] for more information.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Event, Input, InputConfig};
+    /// let mut input_pin = Input::new(
+    ///     peripherals.GPIO4,
+    ///     InputConfig::default(),
+    /// );
+    ///
+    /// input_pin.wait_for_low().await;
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub async fn wait_for_low(&mut self) {
         self.pin.wait_for_low().await
@@ -125,6 +170,21 @@ impl Input<'_> {
     /// Wait for the pin to undergo a transition from low to high.
     ///
     /// See [Self::wait_for] for more information.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Event, Input, InputConfig};
+    /// let mut input_pin = Input::new(
+    ///     peripherals.GPIO4,
+    ///     InputConfig::default(),
+    /// );
+    ///
+    /// input_pin.wait_for_rising_edge().await;
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub async fn wait_for_rising_edge(&mut self) {
         self.pin.wait_for_rising_edge().await
@@ -133,6 +193,21 @@ impl Input<'_> {
     /// Wait for the pin to undergo a transition from high to low.
     ///
     /// See [Self::wait_for] for more information.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Event, Input, InputConfig};
+    /// let mut input_pin = Input::new(
+    ///     peripherals.GPIO4,
+    ///     InputConfig::default(),
+    /// );
+    ///
+    /// input_pin.wait_for_falling_edge().await;
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub async fn wait_for_falling_edge(&mut self) {
         self.pin.wait_for_falling_edge().await
@@ -142,6 +217,21 @@ impl Input<'_> {
     /// to low.
     ///
     /// See [Self::wait_for] for more information.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Event, Input, InputConfig};
+    /// let mut input_pin = Input::new(
+    ///     peripherals.GPIO4,
+    ///     InputConfig::default(),
+    /// );
+    ///
+    /// input_pin.wait_for_any_edge().await;
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub async fn wait_for_any_edge(&mut self) {
         self.pin.wait_for_any_edge().await

esp-hal/src/gpio/mod.rs

@@ -821,6 +821,16 @@ macro_rules! gpio {
             /// # Panics
             ///
             /// Panics if the pin with the given number does not exist.
+            ///
+            /// ## Example
+            ///
+            /// ```rust, no_run
+            #[doc = $crate::before_snippet!()]
+            /// use esp_hal::gpio::AnyPin;
+            /// let pin = unsafe { AnyPin::steal(1) };
+            /// # Ok(())
+            /// # }
+            /// ```
             pub unsafe fn steal(pin: u8) ->  Self {
                 const PINS: &[u8] = &[$($gpionum),*];
                 assert!(PINS.contains(&pin), "Pin {} does not exist", pin);
@@ -832,6 +842,17 @@ macro_rules! gpio {
             /// # Safety
             ///
             /// Ensure that only one instance of a pin is in use at one time.
+            ///
+            /// ## Example
+            ///
+            /// ```rust, no_run
+            #[doc = $crate::before_snippet!()]
+            /// use esp_hal::gpio::{AnyPin, Pin};
+            /// let pin = peripherals.GPIO1.degrade();
+            /// let pin_cloned = unsafe { pin.clone_unchecked() };
+            /// # Ok(())
+            /// # }
+            /// ```
             pub unsafe fn clone_unchecked(&self) -> Self {
                 Self {
                     pin: self.pin,
@@ -841,6 +862,17 @@ macro_rules! gpio {
 
             /// Create a new AnyPin object that is limited to the lifetime of the
             /// passed reference.
+            ///
+            /// ## Example
+            ///
+            /// ```rust, no_run
+            #[doc = $crate::before_snippet!()]
+            /// use esp_hal::gpio::{AnyPin, Pin};
+            /// let mut pin = peripherals.GPIO1.degrade();
+            /// let pin_reborrowed = pin.reborrow();
+            /// # Ok(())
+            /// # }
+            /// ```
             pub fn reborrow(&mut self) -> $crate::gpio::AnyPin<'_> {
                 unsafe { self.clone_unchecked() }
             }
@@ -956,7 +988,6 @@ impl<'d> Output<'d> {
     /// blink_once(&mut led, &mut delay);
     /// # {after_snippet}
     /// ```
-    // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry.
     #[inline]
     pub fn new(pin: impl OutputPin + 'd, initial_level: Level, config: OutputConfig) -> Self {
         // Set up the pin
@@ -979,9 +1010,11 @@ impl<'d> Output<'d> {
     /// Note that the signal returned by this function is
     /// [frozen](interconnect::OutputSignal::freeze).
     ///
+    /// ## Example
+    ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::gpio::{Output, OutputConfig, Level};
+    /// use esp_hal::gpio::{Output, OutputConfig, Level};
     /// # let config = OutputConfig::default();
     /// let pin1_gpio = Output::new(peripherals.GPIO1, Level::High, config);
     /// let output = pin1_gpio.into_peripheral_output();
@@ -995,24 +1028,73 @@ impl<'d> Output<'d> {
     }
 
     /// Change the configuration.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Level, Output, OutputConfig, DriveMode};
+    /// let mut pin = Output::new(peripherals.GPIO5, Level::High, OutputConfig::default());
+    ///
+    /// pin.apply_config(&OutputConfig::default().with_drive_mode(DriveMode::OpenDrain));
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub fn apply_config(&mut self, config: &OutputConfig) {
         self.pin.apply_output_config(config)
     }
 
     /// Set the output as high.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Level, Output, OutputConfig};
+    /// let mut pin = Output::new(peripherals.GPIO5, Level::Low, OutputConfig::default());
+    /// pin.set_high();
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub fn set_high(&mut self) {
         self.set_level(Level::High)
     }
 
     /// Set the output as low.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Level, Output, OutputConfig};
+    /// let mut pin = Output::new(peripherals.GPIO5, Level::High, OutputConfig::default());
+    /// pin.set_low();
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub fn set_low(&mut self) {
         self.set_level(Level::Low)
     }
 
-    /// Set the output level.
+    /// Set the output level.ç
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Level, Output, OutputConfig};
+    /// let mut pin = Output::new(peripherals.GPIO5, Level::High, OutputConfig::default());
+    /// pin.set_level(Level::Low);
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub fn set_level(&mut self, level: Level) {
         self.pin.set_level(level)
@@ -1022,6 +1104,18 @@ impl<'d> Output<'d> {
     ///
     /// This function reads back the value set using `set_level`, `set_high` or
     /// `set_low`. It does not need the input stage to be enabled.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Level, Output, OutputConfig};
+    /// let pin = Output::new(peripherals.GPIO5, Level::High, OutputConfig::default());
+    /// let is_high = pin.is_set_high();
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub fn is_set_high(&self) -> bool {
         self.output_level() == Level::High
@@ -1031,6 +1125,18 @@ impl<'d> Output<'d> {
     ///
     /// This function reads back the value set using `set_level`, `set_high` or
     /// `set_low`. It does not need the input stage to be enabled.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Level, Output, OutputConfig};
+    /// let pin = Output::new(peripherals.GPIO5, Level::High, OutputConfig::default());
+    /// let is_low = pin.is_set_low();
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub fn is_set_low(&self) -> bool {
         self.output_level() == Level::Low
@@ -1040,6 +1146,18 @@ impl<'d> Output<'d> {
     ///
     /// This function reads back the value set using `set_level`, `set_high` or
     /// `set_low`. It does not need the input stage to be enabled.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Level, Output, OutputConfig};
+    /// let pin = Output::new(peripherals.GPIO5, Level::High, OutputConfig::default());
+    /// let level = pin.output_level();
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub fn output_level(&self) -> Level {
         self.pin.output_level()
@@ -1049,6 +1167,18 @@ impl<'d> Output<'d> {
     ///
     /// If the pin was previously set to high, it will be set to low, and vice
     /// versa.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Level, Output, OutputConfig};
+    /// let mut pin = Output::new(peripherals.GPIO5, Level::High, OutputConfig::default());
+    /// pin.toggle();
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub fn toggle(&mut self) {
         self.pin.toggle();
@@ -1128,7 +1258,6 @@ impl<'d> Input<'d> {
     /// print_when_pressed(&mut button, &mut delay);
     /// # {after_snippet}
     /// ```
-    // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry.
     #[inline]
     pub fn new(pin: impl InputPin + 'd, config: InputConfig) -> Self {
         let mut pin = Flex::new(pin);
@@ -1149,10 +1278,12 @@ impl<'d> Input<'d> {
     /// Note that the signal returned by this function is
     /// [frozen](interconnect::InputSignal::freeze).
     ///
+    /// ## Example
+    ///
     /// ```rust, no_run
     /// # {before_snippet}
     /// #
-    /// # use esp_hal::gpio::{Input, InputConfig, Pull};
+    /// use esp_hal::gpio::{Input, InputConfig, Pull};
     /// let config = InputConfig::default().with_pull(Pull::Up);
     /// let pin1_gpio = Input::new(peripherals.GPIO1, config);
     /// let pin1 = pin1_gpio.peripheral_input();
@@ -1166,24 +1297,72 @@ impl<'d> Input<'d> {
     }
 
     /// Get whether the pin input level is high.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Input, InputConfig};
+    /// let pin = Input::new(peripherals.GPIO5, InputConfig::default());
+    /// let is_high = pin.is_high();
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub fn is_high(&self) -> bool {
         self.level() == Level::High
     }
 
     /// Get whether the pin input level is low.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Input, InputConfig};
+    /// let pin = Input::new(peripherals.GPIO5, InputConfig::default());
+    /// let is_low = pin.is_low();
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub fn is_low(&self) -> bool {
         self.level() == Level::Low
     }
 
     /// Get the current pin input level.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Input, InputConfig, Level};
+    /// let pin = Input::new(peripherals.GPIO5, InputConfig::default());
+    /// let level = pin.level();
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub fn level(&self) -> Level {
         self.pin.level()
     }
 
     /// Change the configuration.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::gpio::{Input, InputConfig, Level, Pull};
+    /// let mut pin = Input::new(peripherals.GPIO5, InputConfig::default());
+    /// pin.apply_config(&InputConfig::default().with_pull(Pull::Up));
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn apply_config(&mut self, config: &InputConfig) {
         self.pin.apply_input_config(config)
     }
@@ -1228,10 +1407,10 @@ impl<'d> Input<'d> {
     ///
     /// // Outside of your `main` function:
     ///
-    /// # use esp_hal::gpio::Input;
     /// use core::cell::RefCell;
     ///
     /// use critical_section::Mutex;
+    /// use esp_hal::gpio::Input;
     ///
     /// // You will need to store the `Input` object in a static variable so
     /// // that the interrupt handler can access it.
@@ -1320,6 +1499,7 @@ impl<'d> Input<'d> {
 /// disable the driver.
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[instability::unstable]
 pub struct Flex<'d> {
     pin: AnyPin<'d>,
 }
@@ -1534,7 +1714,7 @@ impl<'d> Flex<'d> {
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::gpio::Flex;
+    /// use esp_hal::gpio::Flex;
     /// let pin1_gpio = Flex::new(peripherals.GPIO1);
     /// // Can be passed as an input.
     /// let pin1 = pin1_gpio.peripheral_input();
@@ -1563,7 +1743,7 @@ impl<'d> Flex<'d> {
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::gpio::Flex;
+    /// use esp_hal::gpio::Flex;
     /// let pin1 = Flex::new(peripherals.GPIO1);
     /// let (input, output) = pin1.split();
     /// # Ok(())
@@ -1628,7 +1808,7 @@ impl<'d> Flex<'d> {
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::gpio::Flex;
+    /// use esp_hal::gpio::Flex;
     /// let pin1_gpio = Flex::new(peripherals.GPIO1);
     /// // Can be passed as an output.
     /// let pin1 = pin1_gpio.into_peripheral_output();
@@ -1716,9 +1896,11 @@ impl<'lt> AnyPin<'lt> {
     ///
     /// This function panics if the pin is not an output pin.
     ///
+    /// ## Example
+    ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::gpio::{AnyPin, Pin};
+    /// use esp_hal::gpio::{AnyPin, Pin};
     /// let pin1 = peripherals.GPIO1.degrade();
     /// let (input, output) = unsafe { pin1.split() };
     /// # Ok(())

esp-hal/src/i2c/master/mod.rs

@@ -621,10 +621,11 @@ impl Default for Config {
 
 /// I2C driver
 ///
-/// ### I2C initialization and communication with the device
+/// ## Example
+///
 /// ```rust, no_run
 #[doc = crate::before_snippet!()]
-/// # use esp_hal::i2c::master::{Config, I2c};
+/// use esp_hal::i2c::master::{Config, I2c};
 /// # const DEVICE_ADDR: u8 = 0x77;
 /// let mut i2c = I2c::new(
 ///     peripherals.I2C0,
@@ -687,10 +688,25 @@ impl<Dm: DriverMode> embedded_hal::i2c::I2c for I2c<'_, Dm> {
 impl<'d> I2c<'d, Blocking> {
     /// Create a new I2C instance.
     ///
-    /// # Errors
+    /// ## Errors
     ///
     /// A [`ConfigError`] variant will be returned if bus frequency or timeout
     /// passed in config is invalid.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::i2c::master::{Config, I2c};
+    /// let i2c = I2c::new(
+    ///     peripherals.I2C0,
+    ///     Config::default(),
+    /// )?
+    /// .with_sda(peripherals.GPIO1)
+    /// .with_scl(peripherals.GPIO2);
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn new(i2c: impl Instance + 'd, config: Config) -> Result<Self, ConfigError> {
         let guard = PeripheralGuard::new(i2c.info().peripheral);
 
@@ -713,7 +729,10 @@ impl<'d> I2c<'d, Blocking> {
         Ok(i2c)
     }
 
-    /// Configures the I2C peripheral to operate in asynchronous mode.
+    /// Reconfigures the driver to operate in [`Async`] mode.
+    ///
+    /// See the [`Async`] documentation for an example on how to use this
+    /// method.
     pub fn into_async(mut self) -> I2c<'d, Async> {
         self.set_interrupt_handler(self.driver().info.async_handler);
 
@@ -915,7 +934,10 @@ impl Drop for I2cFuture<'_> {
 }
 
 impl<'d> I2c<'d, Async> {
-    /// Configure the I2C peripheral to operate in blocking mode.
+    /// Reconfigures the driver to operate in [`Blocking`] mode.
+    ///
+    /// See the [`Blocking`] documentation for an example on how to use this
+    /// method.
     pub fn into_blocking(self) -> I2c<'d, Blocking> {
         self.i2c.disable_peri_interrupt();
 
@@ -928,6 +950,25 @@ impl<'d> I2c<'d, Async> {
     }
 
     /// Writes bytes to slave with given `address`
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::i2c::master::{Config, I2c};
+    /// const DEVICE_ADDR: u8 = 0x77;
+    /// let mut i2c = I2c::new(
+    ///     peripherals.I2C0,
+    ///     Config::default(),
+    /// )?
+    /// .with_sda(peripherals.GPIO1)
+    /// .with_scl(peripherals.GPIO2)
+    /// .into_async();
+    ///
+    /// i2c.write_async(DEVICE_ADDR, &[0xaa]).await?;
+    /// # Ok(())
+    /// # }
+    /// ```
     pub async fn write_async<A: Into<I2cAddress>>(
         &mut self,
         address: A,
@@ -939,10 +980,30 @@ impl<'d> I2c<'d, Async> {
 
     /// Reads enough bytes from slave with `address` to fill `buffer`
     ///
-    /// # Errors
+    /// ## Errors
     ///
     /// The corresponding error variant from [`Error`] will be returned if the
     /// passed buffer has zero length.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::i2c::master::{Config, I2c};
+    /// const DEVICE_ADDR: u8 = 0x77;
+    /// let mut i2c = I2c::new(
+    ///     peripherals.I2C0,
+    ///     Config::default(),
+    /// )?
+    /// .with_sda(peripherals.GPIO1)
+    /// .with_scl(peripherals.GPIO2)
+    /// .into_async();
+    ///
+    /// let mut data = [0u8; 22];
+    /// i2c.read_async(DEVICE_ADDR, &mut data).await?;
+    /// # Ok(())
+    /// # }
+    /// ```
     pub async fn read_async<A: Into<I2cAddress>>(
         &mut self,
         address: A,
@@ -955,10 +1016,30 @@ impl<'d> I2c<'d, Async> {
     /// Writes bytes to slave with given `address` and then reads enough
     /// bytes to fill `buffer` *in a single transaction*
     ///
-    /// # Errors
+    /// ## Errors
     ///
     /// The corresponding error variant from [`Error`] will be returned if the
     /// passed buffer has zero length.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::i2c::master::{Config, I2c};
+    /// const DEVICE_ADDR: u8 = 0x77;
+    /// let mut i2c = I2c::new(
+    ///     peripherals.I2C0,
+    ///     Config::default(),
+    /// )?
+    /// .with_sda(peripherals.GPIO1)
+    /// .with_scl(peripherals.GPIO2)
+    /// .into_async();
+    ///
+    /// let mut data = [0u8; 22];
+    /// i2c.write_read_async(DEVICE_ADDR, &[0xaa], &mut data).await?;
+    /// # Ok(())
+    /// # }
+    /// ```
     pub async fn write_read_async<A: Into<I2cAddress>>(
         &mut self,
         address: A,
@@ -993,10 +1074,33 @@ impl<'d> I2c<'d, Async> {
         any(esp32, esp32s2),
         doc = "\n\nOn ESP32 and ESP32-S2 there might be issues combining large read/write operations with small (<3 bytes) read/write operations.\n\n"
     )]
-    /// # Errors
+    /// ## Errors
     ///
     /// The corresponding error variant from [`Error`] will be returned if the
     /// buffer passed to an [`Operation`] has zero length.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::i2c::master::{Config, I2c, Operation};
+    /// const DEVICE_ADDR: u8 = 0x77;
+    /// let mut i2c = I2c::new(
+    ///     peripherals.I2C0,
+    ///     Config::default(),
+    /// )?
+    /// .with_sda(peripherals.GPIO1)
+    /// .with_scl(peripherals.GPIO2)
+    /// .into_async();
+    ///
+    /// let mut data = [0u8; 22];
+    /// i2c.transaction_async(DEVICE_ADDR, &mut [
+    ///     Operation::Write(&[0xaa]),
+    ///     Operation::Read(&mut data),
+    /// ]).await?;
+    /// # Ok(())
+    /// # }
+    /// ```
     pub async fn transaction_async<'a, A: Into<I2cAddress>>(
         &mut self,
         address: A,
@@ -1045,6 +1149,21 @@ where
     /// Connect a pin to the I2C SCL signal.
     ///
     /// This will replace previous pin assignments for this signal.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::i2c::master::{Config, I2c};
+    /// const DEVICE_ADDR: u8 = 0x77;
+    /// let i2c = I2c::new(
+    ///     peripherals.I2C0,
+    ///     Config::default(),
+    /// )?
+    /// .with_scl(peripherals.GPIO2);
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn with_scl(mut self, scl: impl PeripheralOutput<'d>) -> Self {
         let info = self.driver().info;
         let input = info.scl_input;
@@ -1055,9 +1174,12 @@ where
     }
 
     /// Writes bytes to slave with given `address`
+    ///
+    /// ## Example
+    ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::i2c::master::{Config, I2c};
+    /// use esp_hal::i2c::master::{Config, I2c};
     /// # let mut i2c = I2c::new(
     /// #   peripherals.I2C0,
     /// #   Config::default(),
@@ -1072,9 +1194,12 @@ where
     }
 
     /// Reads enough bytes from slave with `address` to fill `buffer`
+    ///
+    /// ## Example
+    ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::i2c::master::{Config, I2c};
+    /// use esp_hal::i2c::master::{Config, I2c};
     /// # let mut i2c = I2c::new(
     /// #   peripherals.I2C0,
     /// #   Config::default(),
@@ -1086,7 +1211,7 @@ where
     /// # }
     /// ```
     /// 
-    /// # Errors
+    /// ## Errors
     ///
     /// The corresponding error variant from [`Error`] will be returned if the passed buffer has zero length.
     pub fn read<A: Into<I2cAddress>>(
@@ -1099,9 +1224,17 @@ where
 
     /// Writes bytes to slave with given `address` and then reads enough bytes
     /// to fill `buffer` *in a single transaction*
+    ///
+    /// ## Errors
+    ///
+    /// The corresponding error variant from [`Error`] will be returned if the passed buffer has
+    /// zero length.
+    ///
+    /// ## Example
+    ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::i2c::master::{Config, I2c};
+    /// use esp_hal::i2c::master::{Config, I2c};
     /// # let mut i2c = I2c::new(
     /// #   peripherals.I2C0,
     /// #   Config::default(),
@@ -1112,10 +1245,6 @@ where
     /// # Ok(())
     /// # }
     /// ```
-    /// 
-    /// # Errors
-    ///
-    /// The corresponding error variant from [`Error`] will be returned if the passed buffer has zero length.
     pub fn write_read<A: Into<I2cAddress>>(
         &mut self,
         address: A,
@@ -1145,9 +1274,11 @@ where
     /// - `SR` = repeated start condition
     /// - `SP` = stop condition
     ///
+    /// ## Example
+    ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::i2c::master::{Config, I2c, Operation};
+    /// use esp_hal::i2c::master::{Config, I2c, Operation};
     /// # let mut i2c = I2c::new(
     /// #   peripherals.I2C0,
     /// #   Config::default(),
@@ -1166,7 +1297,7 @@ where
         any(esp32, esp32s2),
         doc = "\n\nOn ESP32 and ESP32-S2 it is advisable to not combine large read/write operations with small (<3 bytes) read/write operations.\n\n"
     )]
-    /// # Errors
+    /// ## Errors
     ///
     /// The corresponding error variant from [`Error`] will be returned if the
     /// buffer passed to an [`Operation`] has zero length.
@@ -1182,10 +1313,25 @@ where
 
     /// Applies a new configuration.
     ///
-    /// # Errors
+    /// ## Errors
     ///
     /// A [`ConfigError`] variant will be returned if bus frequency or timeout
     /// passed in config is invalid.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::i2c::master::{Config, I2c};
+    /// let mut i2c = I2c::new(
+    ///     peripherals.I2C0,
+    ///     Config::default(),
+    /// )?;
+    ///
+    /// i2c.apply_config(&Config::default().with_frequency(Rate::from_khz(400)))?;
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> {
         self.config.config = *config;
         self.driver().setup(config)?;

esp-hal/src/interrupt/software.rs

@@ -76,6 +76,10 @@ impl<const NUM: u8> SoftwareInterrupt<'_, NUM> {
     ///
     /// Use this method if you would like to keep working with the peripheral
     /// after you dropped the driver that consumes this.
+    ///
+    /// See [Peripheral singleton] section for more information.
+    ///
+    /// [Peripheral singleton]: crate#peripheral-singletons
     pub fn reborrow(&mut self) -> SoftwareInterrupt<'_, NUM> {
         unsafe { SoftwareInterrupt::steal() }
     }

esp-hal/src/macros.rs

@@ -166,6 +166,11 @@ macro_rules! any_peripheral {
             ///
             /// Use this method if you would like to keep working with the peripheral after
             /// you dropped the driver that consumes this.
+            ///
+            /// See [Peripheral singleton] section for more information.
+            ///
+            /// [Peripheral singleton]: crate#peripheral-singletons
+
             #[inline]
             pub fn reborrow(&mut self) -> $name<'_> {
                 unsafe { self.clone_unchecked() }

esp-hal/src/spi/master.rs

@@ -655,8 +655,8 @@ impl core::fmt::Display for ConfigError {
 ///
 /// ```rust, no_run
 #[doc = crate::before_snippet!()]
-/// # use esp_hal::spi::Mode;
+/// use esp_hal::spi::Mode;
-/// # use esp_hal::spi::master::{Config, Spi};
+/// use esp_hal::spi::master::{Config, Spi};
 /// let mut spi = Spi::new(
 ///     peripherals.SPI2,
 ///     Config::default()
@@ -691,8 +691,8 @@ impl<'d> Spi<'d, Blocking> {
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::spi::Mode;
+    /// use esp_hal::spi::Mode;
-    /// # use esp_hal::spi::master::{Config, Spi};
+    /// use esp_hal::spi::master::{Config, Spi};
     /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?
     /// .with_sck(peripherals.GPIO0)
     /// .with_mosi(peripherals.GPIO1)
@@ -769,10 +769,14 @@ impl<'d> Spi<'d, Blocking> {
     /// operations.
     /// ```rust, no_run
     /// # {before_snippet}
-    /// # use esp_hal::spi::Mode;
+    /// use esp_hal::{
-    /// # use esp_hal::spi::master::{Config, Spi};
+    ///     dma::{DmaRxBuf, DmaTxBuf},
-    /// # use esp_hal::dma::{DmaRxBuf, DmaTxBuf};
+    ///     dma_buffers,
-    /// # use esp_hal::dma_buffers;
+    ///     spi::{
+    ///         Mode,
+    ///         master::{Config, Spi},
+    ///     },
+    /// };
     /// # {dma_channel}
     /// let (rx_buffer, rx_descriptors, tx_buffer, tx_descriptors) = dma_buffers!(32000);
     ///
@@ -850,8 +854,8 @@ impl<'d> Spi<'d, Async> {
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::spi::Mode;
+    /// use esp_hal::spi::Mode;
-    /// # use esp_hal::spi::master::{Config, Spi};
+    /// use esp_hal::spi::master::{Config, Spi};
     /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?
     /// .with_sck(peripherals.GPIO0)
     /// .with_mosi(peripherals.GPIO1)
@@ -880,8 +884,8 @@ impl<'d> Spi<'d, Async> {
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::spi::Mode;
+    /// use esp_hal::spi::Mode;
-    /// # use esp_hal::spi::master::{Config, Spi};
+    /// use esp_hal::spi::master::{Config, Spi};
     /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?
     /// .with_sck(peripherals.GPIO0)
     /// .with_mosi(peripherals.GPIO1)
@@ -964,8 +968,8 @@ where
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::spi::Mode;
+    /// use esp_hal::spi::Mode;
-    /// # use esp_hal::spi::master::{Config, Spi};
+    /// use esp_hal::spi::master::{Config, Spi};
     /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?
     /// .with_sck(peripherals.GPIO0);
     ///
@@ -991,8 +995,8 @@ where
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::spi::Mode;
+    /// use esp_hal::spi::Mode;
-    /// # use esp_hal::spi::master::{Config, Spi};
+    /// use esp_hal::spi::master::{Config, Spi};
     /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?.with_mosi(peripherals.GPIO1);
     ///
     /// # Ok(())
@@ -1016,8 +1020,8 @@ where
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::spi::Mode;
+    /// use esp_hal::spi::Mode;
-    /// # use esp_hal::spi::master::{Config, Spi};
+    /// use esp_hal::spi::master::{Config, Spi};
     /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?.with_miso(peripherals.GPIO2);
     ///
     /// # Ok(())
@@ -1121,8 +1125,10 @@ where
     ///
     /// ```rust, no_run
     /// # {before_snippet}
-    /// # use esp_hal::spi::Mode;
+    /// use esp_hal::spi::{
-    /// # use esp_hal::spi::master::{Config, Spi};
+    ///     Mode,
+    ///     master::{Config, Spi},
+    /// };
     /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?;
     ///
     /// spi.apply_config(&Config::default().with_frequency(Rate::from_khz(100)));
@@ -1140,8 +1146,8 @@ where
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::spi::Mode;
+    /// use esp_hal::spi::Mode;
-    /// # use esp_hal::spi::master::{Config, Spi};
+    /// use esp_hal::spi::master::{Config, Spi};
     /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?
     /// .with_sck(peripherals.GPIO0)
     /// .with_mosi(peripherals.GPIO1)
@@ -1169,8 +1175,8 @@ where
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::spi::Mode;
+    /// use esp_hal::spi::Mode;
-    /// # use esp_hal::spi::master::{Config, Spi};
+    /// use esp_hal::spi::master::{Config, Spi};
     /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?
     /// .with_sck(peripherals.GPIO0)
     /// .with_mosi(peripherals.GPIO1)
@@ -1195,8 +1201,8 @@ where
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::spi::Mode;
+    /// use esp_hal::spi::Mode;
-    /// # use esp_hal::spi::master::{Config, Spi};
+    /// use esp_hal::spi::master::{Config, Spi};
     /// let mut spi = Spi::new(peripherals.SPI2, Config::default())?
     /// .with_sck(peripherals.GPIO0)
     /// .with_mosi(peripherals.GPIO1)
@@ -1374,10 +1380,14 @@ mod dma {
     /// embedded-hal traits.
     /// ```rust, no_run
     /// # {before_snippet}
-    /// # use esp_hal::spi::Mode;
+    /// use esp_hal::{
-    /// # use esp_hal::spi::master::{Config, Spi};
+    ///     dma::{DmaRxBuf, DmaTxBuf},
-    /// # use esp_hal::dma::{DmaRxBuf, DmaTxBuf};
+    ///     dma_buffers,
-    /// # use esp_hal::dma_buffers;
+    ///     spi::{
+    ///         Mode,
+    ///         master::{Config, Spi},
+    ///     },
+    /// };
     /// # {dma_channel}
     /// let (rx_buffer, rx_descriptors, tx_buffer, tx_descriptors) = dma_buffers!(32000);
     ///

esp-hal/src/time.rs

@@ -48,42 +48,116 @@ impl defmt::Format for Rate {
 
 impl Rate {
     /// Shorthand for creating a rate which represents hertz.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Rate;
+    /// let rate = Rate::from_hz(1000);
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub const fn from_hz(val: u32) -> Self {
         Self(InnerRate::Hz(val))
     }
 
     /// Shorthand for creating a rate which represents kilohertz.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Rate;
+    /// let rate = Rate::from_khz(1000);
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub const fn from_khz(val: u32) -> Self {
         Self(InnerRate::kHz(val))
     }
 
     /// Shorthand for creating a rate which represents megahertz.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Rate;
+    /// let rate = Rate::from_mhz(1000);
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub const fn from_mhz(val: u32) -> Self {
         Self(InnerRate::MHz(val))
     }
 
     /// Convert the `Rate` to an interger number of Hz.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Rate;
+    /// let rate = Rate::from_hz(1000);
+    /// let hz = rate.as_hz();
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub const fn as_hz(&self) -> u32 {
         self.0.to_Hz()
     }
 
     /// Convert the `Rate` to an interger number of kHz.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Rate;
+    /// let rate = Rate::from_khz(1000);
+    /// let khz = rate.as_khz();
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub const fn as_khz(&self) -> u32 {
         self.0.to_kHz()
     }
 
     /// Convert the `Rate` to an interger number of MHz.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Rate;
+    /// let rate = Rate::from_mhz(1000);
+    /// let mhz = rate.as_mhz();
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub const fn as_mhz(&self) -> u32 {
         self.0.to_MHz()
     }
 
     /// Convert the `Rate` to a `Duration`.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Rate;
+    /// let rate = Rate::from_hz(1000);
+    /// let duration = rate.as_duration();
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub const fn as_duration(&self) -> Duration {
         Duration::from_micros(1_000_000 / self.as_hz() as u64)
@@ -171,6 +245,16 @@ impl Instant {
     /// The counter won’t measure time in sleep-mode.
     ///
     /// The timer has a 1 microsecond resolution and will wrap after
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Instant;
+    /// let now = Instant::now();
+    /// # Ok(())
+    /// # }
+    /// ```
     #[cfg_attr(esp32, doc = "36_558 years")]
     #[cfg_attr(esp32s2, doc = "7_311 years")]
     #[cfg_attr(not(any(esp32, esp32s2)), doc = "more than 7 years")]
@@ -185,12 +269,34 @@ impl Instant {
     }
 
     /// Returns the elapsed `Duration` since boot.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Instant;
+    /// let now = Instant::now();
+    /// let duration = now.duration_since_epoch();
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub fn duration_since_epoch(&self) -> Duration {
         *self - Self::EPOCH
     }
 
     /// Returns the elapsed `Duration` since this `Instant` was created.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Instant;
+    /// let now = Instant::now();
+    /// let duration = now.elapsed();
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub fn elapsed(&self) -> Duration {
         Self::now() - *self
@@ -279,30 +385,80 @@ impl Duration {
     pub const MAX: Self = Self(InnerDuration::from_ticks(u64::MAX));
 
     /// Creates a duration which represents microseconds.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Duration;
+    /// let duration = Duration::from_micros(1000);
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub const fn from_micros(val: u64) -> Self {
         Self(InnerDuration::micros(val))
     }
 
     /// Creates a duration which represents milliseconds.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Duration;
+    /// let duration = Duration::from_millis(100);
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub const fn from_millis(val: u64) -> Self {
         Self(InnerDuration::millis(val))
     }
 
     /// Creates a duration which represents seconds.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Duration;
+    /// let duration = Duration::from_secs(1);
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub const fn from_secs(val: u64) -> Self {
         Self(InnerDuration::secs(val))
     }
 
     /// Creates a duration which represents minutes.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Duration;
+    /// let duration = Duration::from_minutes(1);
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub const fn from_minutes(val: u64) -> Self {
         Self(InnerDuration::minutes(val))
     }
 
     /// Creates a duration which represents hours.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Duration;
+    /// let duration = Duration::from_hours(1);
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub const fn from_hours(val: u64) -> Self {
         Self(InnerDuration::hours(val))
@@ -312,28 +468,100 @@ impl Duration {
         #[inline]
         to self.0 {
             /// Convert the `Duration` to an interger number of microseconds.
+            ///
+            /// ## Example
+            ///
+            /// ```rust, no_run
+            #[doc = crate::before_snippet!()]
+            /// use esp_hal::time::Duration;
+            /// let duration = Duration::from_micros(1000);
+            /// let micros = duration.as_micros();
+            /// # Ok(())
+            /// # }
+            /// ```
             #[call(to_micros)]
             pub const fn as_micros(&self) -> u64;
 
             /// Convert the `Duration` to an interger number of milliseconds.
+            ///
+            /// ## Example
+            ///
+            /// ```rust, no_run
+            #[doc = crate::before_snippet!()]
+            /// use esp_hal::time::Duration;
+            /// let duration = Duration::from_millis(100);
+            /// let millis = duration.as_millis();
+            /// # Ok(())
+            /// # }
+            /// ```
             #[call(to_millis)]
             pub const fn as_millis(&self) -> u64;
 
             /// Convert the `Duration` to an interger number of seconds.
+            ///
+            /// ## Example
+            ///
+            /// ```rust, no_run
+            #[doc = crate::before_snippet!()]
+            /// use esp_hal::time::Duration;
+            /// let duration = Duration::from_secs(1);
+            /// let secs = duration.as_secs();
+            /// # Ok(())
+            /// # }
+            /// ```
             #[call(to_secs)]
             pub const fn as_secs(&self) -> u64;
 
             /// Convert the `Duration` to an interger number of minutes.
+            ///
+            /// ## Example
+            ///
+            /// ```rust, no_run
+            #[doc = crate::before_snippet!()]
+            /// use esp_hal::time::Duration;
+            /// let duration = Duration::from_minutes(1);
+            /// let minutes = duration.as_minutes();
+            /// # Ok(())
+            /// # }
+            /// ```
             #[call(to_minutes)]
             pub const fn as_minutes(&self) -> u64;
 
             /// Convert the `Duration` to an interger number of hours.
+            ///
+            /// ## Example
+            ///
+            /// ```rust, no_run
+            #[doc = crate::before_snippet!()]
+            /// use esp_hal::time::Duration;
+            /// let duration = Duration::from_hours(1);
+            /// let hours = duration.as_hours();
+            /// # Ok(())
+            /// # }
+            /// ```
             #[call(to_hours)]
             pub const fn as_hours(&self) -> u64;
         }
     }
 
     /// Add two durations while checking for overflow.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Duration;
+    /// let duration = Duration::from_secs(1);
+    /// let duration2 = Duration::from_secs(2);
+    ///
+    /// if let Some(sum) = duration.checked_add(duration2) {
+    ///     println!("Sum: {}", sum);
+    /// } else {
+    ///     println!("Overflow occurred");
+    /// }
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub const fn checked_add(self, rhs: Self) -> Option<Self> {
         if let Some(val) = self.0.checked_add(rhs.0) {
@@ -344,6 +572,23 @@ impl Duration {
     }
 
     /// Subtract two durations while checking for overflow.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Duration;
+    /// let duration = Duration::from_secs(3);
+    /// let duration2 = Duration::from_secs(1);
+    ///
+    /// if let Some(diff) = duration.checked_sub(duration2) {
+    ///     println!("Difference: {}", diff);
+    /// } else {
+    ///     println!("Underflow occurred");
+    /// }
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub const fn checked_sub(self, rhs: Self) -> Option<Self> {
         if let Some(val) = self.0.checked_sub(rhs.0) {
@@ -354,6 +599,19 @@ impl Duration {
     }
 
     /// Add two durations, returning the maximum value if overflow occurred.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Duration;
+    /// let duration = Duration::from_secs(1);
+    /// let duration2 = Duration::from_secs(2);
+    ///
+    /// let sum = duration.saturating_add(duration2);
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub const fn saturating_add(self, rhs: Self) -> Self {
         if let Some(val) = self.checked_add(rhs) {
@@ -365,6 +623,19 @@ impl Duration {
 
     /// Subtract two durations, returning the minimum value if the result would
     /// be negative.
+    ///
+    /// ## Example
+    ///
+    /// ```rust, no_run
+    #[doc = crate::before_snippet!()]
+    /// use esp_hal::time::Duration;
+    /// let duration = Duration::from_secs(3);
+    /// let duration2 = Duration::from_secs(1);
+    ///
+    /// let diff = duration.saturating_sub(duration2);
+    /// # Ok(())
+    /// # }
+    /// ```
     #[inline]
     pub const fn saturating_sub(self, rhs: Self) -> Self {
         if let Some(val) = self.checked_sub(rhs) {

esp-hal/src/timer/systimer.rs

@@ -296,6 +296,10 @@ impl Alarm<'_> {
     ///
     /// Use this method if you would like to keep working with the peripheral
     /// after you dropped the driver that consumes this.
+    ///
+    /// See [Peripheral singleton] section for more information.
+    ///
+    /// [Peripheral singleton]: crate#peripheral-singletons
     pub fn reborrow(&mut self) -> Alarm<'_> {
         unsafe { self.clone_unchecked() }
     }

esp-hal/src/timer/timg.rs

@@ -397,6 +397,10 @@ impl Timer<'_> {
     ///
     /// Use this method if you would like to keep working with the peripheral
     /// after you dropped the driver that consumes this.
+    ///
+    /// See [Peripheral singleton] section for more information.
+    ///
+    /// [Peripheral singleton]: crate#peripheral-singletons
     pub fn reborrow(&mut self) -> Timer<'_> {
         unsafe { self.clone_unchecked() }
     }

esp-hal/src/uart.rs

@@ -477,7 +477,7 @@ where
 ///
 /// ```rust, no_run
 #[doc = crate::before_snippet!()]
-/// # use esp_hal::uart::{Config, Uart};
+/// use esp_hal::uart::{Config, Uart};
 /// let mut uart = Uart::new(
 ///     peripherals.UART0,
 ///     Config::default())?
@@ -616,7 +616,7 @@ impl<'d> UartTx<'d, Blocking> {
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::uart::{Config, UartTx};
+    /// use esp_hal::uart::{Config, UartTx};
     /// let tx = UartTx::new(
     ///     peripherals.UART0,
     ///     Config::default())?
@@ -910,7 +910,7 @@ impl<'d> UartRx<'d, Blocking> {
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::uart::{Config, UartRx};
+    /// use esp_hal::uart::{Config, UartRx};
     /// let rx = UartRx::new(
     ///     peripherals.UART0,
     ///     Config::default())?
@@ -1237,7 +1237,7 @@ impl<'d> Uart<'d, Blocking> {
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::uart::{Config, Uart};
+    /// use esp_hal::uart::{Config, Uart};
     /// let mut uart = Uart::new(
     ///     peripherals.UART0,
     ///     Config::default())?
@@ -1290,8 +1290,8 @@ impl<'d> Uart<'d, Blocking> {
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::delay::Delay;
+    /// use esp_hal::delay::Delay;
-    /// # use esp_hal::uart::{AtCmdConfig, Config, RxConfig, Uart, UartInterrupt};
+    /// use esp_hal::uart::{AtCmdConfig, Config, RxConfig, Uart, UartInterrupt};
     /// # let delay = Delay::new();
     /// # let config = Config::default().with_rx(
     /// #    RxConfig::default().with_fifo_full_threshold(30)
@@ -1314,14 +1314,14 @@ impl<'d> Uart<'d, Blocking> {
     /// }
     /// # }
     ///
-    /// # use core::cell::RefCell;
+    /// use core::cell::RefCell;
-    /// # use critical_section::Mutex;
+    /// use critical_section::Mutex;
-    /// # use esp_hal::uart::Uart;
+    /// use esp_hal::uart::Uart;
     /// static SERIAL: Mutex<RefCell<Option<Uart<esp_hal::Blocking>>>> =
     ///     Mutex::new(RefCell::new(None));
     ///
-    /// # use esp_hal::uart::UartInterrupt;
+    /// use esp_hal::uart::UartInterrupt;
-    /// # use core::fmt::Write;
+    /// use core::fmt::Write;
     /// #[handler]
     /// fn interrupt_handler() {
     ///     critical_section::with(|cs| {
@@ -1402,7 +1402,7 @@ impl<'d> Uart<'d, Async> {
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::uart::{Config, Uart};
+    /// use esp_hal::uart::{Config, Uart};
     /// let mut uart = Uart::new(
     ///     peripherals.UART0,
     ///     Config::default())?
@@ -1433,7 +1433,7 @@ impl<'d> Uart<'d, Async> {
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::uart::{Config, Uart};
+    /// use esp_hal::uart::{Config, Uart};
     /// let mut uart = Uart::new(
     ///     peripherals.UART0,
     ///     Config::default())?
@@ -1474,7 +1474,7 @@ impl<'d> Uart<'d, Async> {
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::uart::{Config, Uart};
+    /// use esp_hal::uart::{Config, Uart};
     /// let mut uart = Uart::new(
     ///     peripherals.UART0,
     ///     Config::default())?
@@ -1554,7 +1554,7 @@ where
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::uart::{Config, Uart};
+    /// use esp_hal::uart::{Config, Uart};
     /// let uart = Uart::new(
     ///     peripherals.UART0,
     ///     Config::default())?
@@ -1577,7 +1577,7 @@ where
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::uart::{Config, Uart};
+    /// use esp_hal::uart::{Config, Uart};
     /// let uart = Uart::new(
     ///     peripherals.UART0,
     ///     Config::default())?
@@ -1597,7 +1597,7 @@ where
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::uart::{Config, Uart};
+    /// use esp_hal::uart::{Config, Uart};
     /// let uart = Uart::new(
     ///     peripherals.UART0,
     ///     Config::default())?
@@ -1618,7 +1618,7 @@ where
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::uart::{Config, Uart};
+    /// use esp_hal::uart::{Config, Uart};
     /// let uart = Uart::new(
     ///     peripherals.UART0,
     ///     Config::default())?
@@ -1664,7 +1664,7 @@ where
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::uart::{Config, Uart};
+    /// use esp_hal::uart::{Config, Uart};
     /// let mut uart = Uart::new(
     ///     peripherals.UART0,
     ///     Config::default())?;
@@ -1684,7 +1684,7 @@ where
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::uart::{Config, Uart};
+    /// use esp_hal::uart::{Config, Uart};
     /// let mut uart = Uart::new(
     ///     peripherals.UART0,
     ///     Config::default())?;
@@ -1729,7 +1729,7 @@ where
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::uart::{Config, Uart};
+    /// use esp_hal::uart::{Config, Uart};
     /// let mut uart = Uart::new(
     ///     peripherals.UART0,
     ///     Config::default())?;
@@ -1759,7 +1759,7 @@ where
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::uart::{Config, Uart};
+    /// use esp_hal::uart::{Config, Uart};
     /// let mut uart = Uart::new(
     ///     peripherals.UART0,
     ///     Config::default())?;
@@ -1786,7 +1786,7 @@ where
     ///
     /// ```rust, no_run
     #[doc = crate::before_snippet!()]
-    /// # use esp_hal::uart::{Config, Uart};
+    /// use esp_hal::uart::{Config, Uart};
     /// let mut uart = Uart::new(
     ///     peripherals.UART0,
     ///     Config::default())?