Use doc_replace more (#3786)

* Use `doc_replace` more

* Fix

* Fix

esp-hal/src/aes/mod.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Advanced Encryption Standard (AES).
 //!
 //! ## Overview
@@ -22,7 +23,7 @@
 //! Simple example of encrypting and decrypting a message using AES-128:
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::aes::{Aes, Mode};
 //! # let keytext = b"SUp4SeCp@sSw0rd";
 //! # let plaintext = b"message";
@@ -40,10 +41,9 @@
 //! aes.process(&mut block, Mode::Decryption128, keybuf);
 //!
 //! // The decryption happens in-place, so the plaintext is in `block`
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
-//! 
+//!
 //! ### AES-DMA
 //!
 //! Visit the [AES-DMA] test for a more advanced example of using AES-DMA

esp-hal/src/analog/adc/mod.rs

@@ -1,3 +1,10 @@
+#![cfg_attr(docsrs, procmacros::doc_replace(
+    "analog_pin" => {
+        cfg(esp32) => "let analog_pin = peripherals.GPIO32;",
+        cfg(any(esp32s2, esp32s3)) => "let analog_pin = peripherals.GPIO3;",
+        cfg(not(any(esp32, esp32s2, esp32s3)))  => "let analog_pin = peripherals.GPIO2;"
+    }
+))]
 //! # Analog to Digital Converter (ADC)
 //!
 //! ## Overview
@@ -21,23 +28,15 @@
 //! ### Read an analog signal from a pin
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::analog::adc::AdcConfig;
 //! # use esp_hal::peripherals::ADC1;
 //! # use esp_hal::analog::adc::Attenuation;
 //! # use esp_hal::analog::adc::Adc;
 //! # use esp_hal::delay::Delay;
-#![cfg_attr(esp32, doc = "let analog_pin = peripherals.GPIO32;")]
+//! # {analog_pin}
-#![cfg_attr(any(esp32s2, esp32s3), doc = "let analog_pin = peripherals.GPIO3;")]
-#![cfg_attr(
-    not(any(esp32, esp32s2, esp32s3)),
-    doc = "let analog_pin = peripherals.GPIO2;"
-)]
 //! let mut adc1_config = AdcConfig::new();
-//! let mut pin = adc1_config.enable_pin(
+//! let mut pin = adc1_config.enable_pin(analog_pin, Attenuation::_11dB);
-//!     analog_pin,
-//!     Attenuation::_11dB,
-//! );
 //! let mut adc1 = Adc::new(peripherals.ADC1, adc1_config);
 //!
 //! let mut delay = Delay::new();
@@ -49,7 +48,7 @@
 //! }
 //! # }
 //! ```
-//! 
+//!
 //! ## Implementation State
 //!
 //!  - [ADC calibration is not implemented for all targets].

esp-hal/src/analog/dac.rs

@@ -1,3 +1,9 @@
+#![cfg_attr(docsrs, procmacros::doc_replace(
+    "dac1_pin" => {
+        cfg(esp32) => "let dac1_pin = peripherals.GPIO25;",
+        cfg(esp32s2) => "let dac1_pin = peripherals.GPIO17;"
+    }
+))]
 //! # Digital to Analog Converter (DAC)
 //!
 //! ## Overview
@@ -16,12 +22,11 @@
 //! ## Examples
 //! ### Write a value to a DAC channel
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::analog::dac::Dac;
 //! # use esp_hal::delay::Delay;
 //! # use embedded_hal::delay::DelayNs;
-#![cfg_attr(esp32, doc = "let dac1_pin = peripherals.GPIO25;")]
+//! # {dac1_pin}
-#![cfg_attr(esp32s2, doc = "let dac1_pin = peripherals.GPIO17;")]
 //! let mut dac1 = Dac::new(peripherals.DAC1, dac1_pin);
 //!
 //! let mut delay = Delay::new();

esp-hal/src/dma/mod.rs

@@ -1,3 +1,9 @@
+#![cfg_attr(docsrs, procmacros::doc_replace(
+    "dma_channel" => {
+        cfg(pdma) => "let dma_channel = peripherals.DMA_SPI2;",
+        cfg(gdma) => "let dma_channel = peripherals.DMA_CH0;"
+    }
+))]
 //! # Direct Memory Access (DMA)
 //!
 //! ## Overview
@@ -16,11 +22,10 @@
 //! ### Initialize and utilize DMA controller in `SPI`
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::dma_buffers;
 //! # use esp_hal::spi::{master::{Config, Spi}, Mode};
-#![cfg_attr(pdma, doc = "let dma_channel = peripherals.DMA_SPI2;")]
+//! # {dma_channel}
-#![cfg_attr(gdma, doc = "let dma_channel = peripherals.DMA_CH0;")]
 //! let sclk = peripherals.GPIO0;
 //! let miso = peripherals.GPIO2;
 //! let mosi = peripherals.GPIO4;
@@ -28,8 +33,10 @@
 //!
 //! let mut spi = Spi::new(
 //!     peripherals.SPI2,
-//!     Config::default().with_frequency(Rate::from_khz(100)).
+//!     Config::default()
-//! with_mode(Mode::_0) )?
+//!         .with_frequency(Rate::from_khz(100))
+//!         .with_mode(Mode::_0),
+//! )?
 //! .with_sck(sclk)
 //! .with_mosi(mosi)
 //! .with_miso(miso)
@@ -38,7 +45,7 @@
 //! # Ok(())
 //! # }
 //! ```
-//! 
+//!
 //! ⚠️ Note: Descriptors should be sized as `(max_transfer_size + CHUNK_SIZE - 1) / CHUNK_SIZE`.
 //! I.e., to transfer buffers of size `1..=CHUNK_SIZE`, you need 1 descriptor.
 //!
@@ -1645,6 +1652,12 @@ impl<DEG: DmaChannel> DmaChannelConvert<DEG> for DEG {
     }
 }
 
+#[procmacros::doc_replace(
+    "dma_channel" => {
+        cfg(pdma) => "let dma_channel = peripherals.DMA_SPI2;",
+        cfg(gdma) => "let dma_channel = peripherals.DMA_CH0;"
+    }
+)]
 /// Trait implemented for DMA channels that are compatible with a particular
 /// peripheral.
 ///
@@ -1662,12 +1675,12 @@ impl<DEG: DmaChannel> DmaChannelConvert<DEG> for DEG {
 /// types compatible with a specific peripheral.
 ///
 /// ```rust,no_run
-#[doc = crate::before_snippet!()]
+/// # {before_snippet}
-/// use esp_hal::spi::master::{
+/// use esp_hal::{
-///     AnySpi, Spi, SpiDma, Config, Instance as SpiInstance
+///     Blocking,
+///     dma::DmaChannelFor,
+///     spi::master::{AnySpi, Config, Instance as SpiInstance, Spi, SpiDma},
 /// };
-/// use esp_hal::dma::DmaChannelFor;
-/// use esp_hal::Blocking;
 ///
 /// fn configures_spi_dma<'d>(
 ///     spi: Spi<'d, Blocking>,
@@ -1675,13 +1688,10 @@ impl<DEG: DmaChannel> DmaChannelConvert<DEG> for DEG {
 /// ) -> SpiDma<'d, Blocking> {
 ///     spi.with_dma(channel)
 /// }
-#[cfg_attr(pdma, doc = "let dma_channel = peripherals.DMA_SPI2;")]
+///
-#[cfg_attr(gdma, doc = "let dma_channel = peripherals.DMA_CH0;")]
+/// # {dma_channel}
-#[doc = ""]
+///
-/// let spi = Spi::new(
+/// let spi = Spi::new(peripherals.SPI2, Config::default())?;
-///     peripherals.SPI2,
-///     Config::default(),
-/// )?;
 ///
 /// let spi_dma = configures_spi_dma(spi, dma_channel);
 /// # Ok(())

esp-hal/src/etm.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Event Task Matrix (ETM)
 //!
 //! ## Overview
@@ -24,7 +25,7 @@
 //!
 //! ### Control LED by the button via ETM
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::gpio::etm::{Channels, InputConfig, OutputConfig};
 //! # use esp_hal::etm::Etm;
 //! # use esp_hal::gpio::Pull;
@@ -44,8 +45,8 @@
 //!     },
 //! );
 //! let button_event = gpio_ext
-//! .channel0_event
+//!     .channel0_event
-//! .falling_edge(button, InputConfig { pull: Pull::Down });
+//!     .falling_edge(button, InputConfig { pull: Pull::Down });
 //!
 //! let etm = Etm::new(peripherals.ETM);
 //! let channel0 = etm.channel0;
@@ -58,10 +59,10 @@
 //! loop {}
 //! # }
 //! ```
-//! 
+//!
 //! ### Control LED by the systimer via ETM
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::gpio::etm::{Channels, InputConfig, OutputConfig};
 //! # use esp_hal::etm::Etm;
 //! # use esp_hal::gpio::Pull;

esp-hal/src/gpio/etm.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Event Task Matrix (ETM)
 //!
 //! ## Overview
@@ -21,7 +22,7 @@
 //! ## Examples
 //! ### Toggle an LED When a Button is Pressed
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::gpio::etm::Channels;
 //! # use esp_hal::etm::Etm;
 //! # use esp_hal::gpio::etm::InputConfig;
@@ -44,8 +45,7 @@
 //! let button_event = gpio_ext
 //!     .channel0_event
 //!     .falling_edge(button, InputConfig { pull: Pull::Down });
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
 
 use core::marker::PhantomData;

esp-hal/src/gpio/interconnect.rs

@@ -912,6 +912,7 @@ impl NoOp {
     }
 }
 
+#[procmacros::doc_replace]
 /// ```rust,compile_fail
 /// // Regression test for <https://github.com/esp-rs/esp-hal/issues/3313>
 /// // This test case is expected to generate the following error:
@@ -926,7 +927,7 @@ impl NoOp {
 /// //    | |_______________________^ the trait `InputPin` is not implemented for `Output<'_>`
 /// // FIXME: due to <https://github.com/rust-lang/rust/issues/139924> this test may be ineffective.
 /// //        It can be manually verified by changing it to `no_run` for a `run-doc-tests` run.
-#[doc = crate::before_snippet!()]
+/// # {before_snippet}
 /// use esp_hal::gpio::{Output, Level, interconnect::PeripheralInput};
 ///
 /// fn function_expects_input<'d>(_: impl PeripheralInput<'d>) {}
@@ -937,7 +938,6 @@ impl NoOp {
 ///     Default::default()),
 /// );
 ///
-/// # Ok(())
+/// # {after_snippet}
-/// # }
 /// ```
 fn _compile_tests() {}

esp-hal/src/gpio/lp_io.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! Low Power IO (LP_IO)
 //!
 //! # Overview
@@ -19,13 +20,11 @@
 //! ## Configure a LP Pin as Output
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! use esp_hal::gpio::lp_io::LowPowerOutput;
 //! // configure GPIO 1 as LP output pin
-//! let lp_pin: LowPowerOutput<'_, 1> =
+//! let lp_pin: LowPowerOutput<'_, 1> = LowPowerOutput::new(peripherals.GPIO1);
-//!     LowPowerOutput::new(peripherals.GPIO1);
+//! # {after_snippet}
-//! # Ok(())
-//! # }
 //! ```
 
 use core::marker::PhantomData;

esp-hal/src/gpio/rtc_io.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! RTC IO
 //!
 //! # Overview
@@ -21,12 +22,11 @@
 //! ### Configure a ULP Pin as Output
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::gpio::rtc_io::LowPowerOutput;
 //! // configure GPIO 1 as ULP output pin
 //! let lp_pin = LowPowerOutput::<'static, 1>::new(peripherals.GPIO1);
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
 
 use core::marker::PhantomData;

esp-hal/src/i2s/master.rs

@@ -1,3 +1,14 @@
+#![cfg_attr(docsrs, procmacros::doc_replace(
+    "dma_channel" => {
+        cfg(any(esp32, esp32s2)) => "let dma_channel = peripherals.DMA_I2S0;",
+        cfg(not(any(esp32, esp32s2))) => "let dma_channel = peripherals.DMA_CH0;"
+    },
+    "mclk" => {
+        cfg(not(esp32)) => "let i2s = i2s.with_mclk(peripherals.GPIO0);",
+        _ => ""
+    }
+
+))]
 //! # Inter-IC Sound (I2S)
 //!
 //! ## Overview
@@ -28,14 +39,10 @@
 //! ### I2S Read
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::i2s::master::{I2s, Standard, DataFormat};
 //! # use esp_hal::dma_buffers;
-#![cfg_attr(any(esp32, esp32s2), doc = "let dma_channel = peripherals.DMA_I2S0;")]
+//! # {dma_channel}
-#![cfg_attr(
-    not(any(esp32, esp32s2)),
-    doc = "let dma_channel = peripherals.DMA_CH0;"
-)]
 //! let (mut rx_buffer, rx_descriptors, _, _) = dma_buffers!(4 * 4092, 0);
 //!
 //! let i2s = I2s::new(
@@ -45,8 +52,9 @@
 //!     Rate::from_hz(44100),
 //!     dma_channel,
 //! );
-#![cfg_attr(not(esp32), doc = "let i2s = i2s.with_mclk(peripherals.GPIO0);")]
+//! # {mclk}
-//! let mut i2s_rx = i2s.i2s_rx
+//! let mut i2s_rx = i2s
+//!     .i2s_rx
 //!     .with_bclk(peripherals.GPIO1)
 //!     .with_ws(peripherals.GPIO2)
 //!     .with_din(peripherals.GPIO5)
@@ -64,7 +72,7 @@
 //! }
 //! # }
 //! ```
-//! 
+//!
 //! ## Implementation State
 //!
 //! - Only TDM Philips standard is supported.

esp-hal/src/i2s/parallel.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Parallel Interface (via I2S)
 //!
 //! ## Overview
@@ -36,7 +37,7 @@
 //! ## Examples
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::dma::DmaTxBuf;
 //! # use esp_hal::dma_buffers;
 //! # use esp_hal::delay::Delay;
@@ -61,13 +62,8 @@
 //! );
 //!
 //! let (_, _, tx_buffer, tx_descriptors) = dma_buffers!(0, BUFFER_SIZE);
-//! let mut parallel = I2sParallel::new(
+//! let mut parallel =
-//!     i2s,
+//!     I2sParallel::new(i2s, dma_channel, Rate::from_mhz(1), pins, clock).into_async();
-//!     dma_channel,
-//!     Rate::from_mhz(1),
-//!     pins,
-//!     clock,
-//! ).into_async();
 //!
 //! for (i, data) in tx_buffer.chunks_mut(4).enumerate() {
 //!     let offset = i * 4;
@@ -94,7 +90,6 @@
 //! }
 //! # }
 //! ```
-//!
 use core::{
     mem::ManuallyDrop,
     ops::{Deref, DerefMut},

esp-hal/src/interrupt/mod.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Interrupt support
 //!
 //! ## Overview
@@ -29,9 +30,8 @@
 //! ### Using the peripheral driver to register an interrupt handler
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
-//! let mut sw_int =
+//! let mut sw_int = SoftwareInterruptControl::new(peripherals.SW_INTERRUPT);
-//!     SoftwareInterruptControl::new(peripherals.SW_INTERRUPT);
 //! critical_section::with(|cs| {
 //!     sw_int
 //!         .software_interrupt0
@@ -42,7 +42,7 @@
 //! });
 //!
 //! critical_section::with(|cs| {
-//!     if let Some(swint) = SWINT0.borrow_ref(cs).as_ref(){
+//!     if let Some(swint) = SWINT0.borrow_ref(cs).as_ref() {
 //!         swint.raise();
 //!     }
 //! });
@@ -57,8 +57,7 @@
 //! # use esp_hal::interrupt::Priority;
 //! # use esp_hal::interrupt::InterruptHandler;
 //! #
-//! static SWINT0: Mutex<RefCell<Option<SoftwareInterrupt<0>>>> =
+//! static SWINT0: Mutex<RefCell<Option<SoftwareInterrupt<0>>>> = Mutex::new(RefCell::new(None));
-//!     Mutex::new(RefCell::new(None));
 //!
 //! #[handler(priority = Priority::Priority1)]
 //! fn swint0_handler() {

esp-hal/src/interrupt/software.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Software Interrupts
 //!
 //! The [`SoftwareInterruptControl`] struct gives access to the available
@@ -10,9 +11,8 @@
 //! ## Examples
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
-//! let sw_ints =
+//! let sw_ints = SoftwareInterruptControl::new(peripherals.SW_INTERRUPT);
-//!     SoftwareInterruptControl::new(peripherals.SW_INTERRUPT);
 //!
 //! // Take the interrupt you want to use.
 //! let mut int0 = sw_ints.software_interrupt0;
@@ -23,8 +23,7 @@
 //!     int0.set_interrupt_handler(swint0_handler);
 //!     SWINT0.borrow_ref_mut(cs).replace(int0);
 //! });
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //!
 //! # use core::cell::RefCell;
 //! # use critical_section::Mutex;
@@ -32,8 +31,7 @@
 //! // ... somewhere outside of your main function
 //!
 //! // Define a shared handle to the software interrupt.
-//! static SWINT0: Mutex<RefCell<Option<SoftwareInterrupt<0>>>> =
+//! static SWINT0: Mutex<RefCell<Option<SoftwareInterrupt<0>>>> = Mutex::new(RefCell::new(None));
-//!     Mutex::new(RefCell::new(None));
 //!
 //! #[handler]
 //! fn swint0_handler() {

esp-hal/src/lcd_cam/cam.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Camera - Master or Slave Mode
 //!
 //! ## Overview
@@ -15,7 +16,7 @@
 //! Following code shows how to receive some bytes from an 8 bit DVP stream in
 //! master mode.
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::lcd_cam::{cam::{Camera, Config}, LcdCam};
 //! # use esp_hal::dma_rx_stream_buffer;
 //!
@@ -29,28 +30,23 @@
 //! let config = Config::default().with_frequency(Rate::from_mhz(20));
 //!
 //! let lcd_cam = LcdCam::new(peripherals.LCD_CAM);
-//! let mut camera = Camera::new(
+//! let mut camera = Camera::new(lcd_cam.cam, peripherals.DMA_CH0, config)?
-//!     lcd_cam.cam,
+//!     .with_master_clock(mclk_pin) // Remove this for slave mode
-//!     peripherals.DMA_CH0,
+//!     .with_pixel_clock(pclk_pin)
-//!     config,
+//!     .with_vsync(vsync_pin)
-//! )?
+//!     .with_h_enable(href_pin)
-//! .with_master_clock(mclk_pin) // Remove this for slave mode
+//!     .with_data0(peripherals.GPIO11)
-//! .with_pixel_clock(pclk_pin)
+//!     .with_data1(peripherals.GPIO9)
-//! .with_vsync(vsync_pin)
+//!     .with_data2(peripherals.GPIO8)
-//! .with_h_enable(href_pin)
+//!     .with_data3(peripherals.GPIO10)
-//! .with_data0(peripherals.GPIO11)
+//!     .with_data4(peripherals.GPIO12)
-//! .with_data1(peripherals.GPIO9)
+//!     .with_data5(peripherals.GPIO18)
-//! .with_data2(peripherals.GPIO8)
+//!     .with_data6(peripherals.GPIO17)
-//! .with_data3(peripherals.GPIO10)
+//!     .with_data7(peripherals.GPIO16);
-//! .with_data4(peripherals.GPIO12)
-//! .with_data5(peripherals.GPIO18)
-//! .with_data6(peripherals.GPIO17)
-//! .with_data7(peripherals.GPIO16);
 //!
 //! let transfer = camera.receive(dma_buf).map_err(|e| e.0)?;
 //!
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
 
 use core::{

esp-hal/src/lcd_cam/lcd/dpi.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # LCD - RGB/Digital Parallel Interface Mode
 //!
 //! ## Overview
@@ -14,7 +15,7 @@
 //! display.
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::gpio::Level;
 //! # use esp_hal::lcd_cam::{
 //! #     LcdCam,
@@ -91,8 +92,7 @@
 //!
 //! let transfer = dpi.send(false, dma_buf).map_err(|e| e.0)?;
 //! transfer.wait();
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
 
 use core::{

esp-hal/src/lcd_cam/lcd/i8080.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # LCD - I8080/MOTO6800 Mode.
 //!
 //! ## Overview
@@ -14,7 +15,7 @@
 //! the I8080 protocol.
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::lcd_cam::{LcdCam, lcd::i8080::{Config, I8080, TxEightBits}};
 //! # use esp_hal::dma_tx_buffer;
 //! # use esp_hal::dma::DmaTxBuf;
@@ -35,19 +36,13 @@
 //!
 //! let config = Config::default().with_frequency(Rate::from_mhz(20));
 //!
-//! let mut i8080 = I8080::new(
+//! let mut i8080 = I8080::new(lcd_cam.lcd, peripherals.DMA_CH0, tx_pins, config)?
-//!     lcd_cam.lcd,
+//!     .with_ctrl_pins(peripherals.GPIO0, peripherals.GPIO47);
-//!     peripherals.DMA_CH0,
-//!     tx_pins,
-//!     config,
-//! )?
-//! .with_ctrl_pins(peripherals.GPIO0, peripherals.GPIO47);
 //!
 //! dma_buf.fill(&[0x55]);
 //! let transfer = i8080.send(0x3Au8, 0, dma_buf)?; // RGB565
 //! transfer.wait();
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
 
 use core::{

esp-hal/src/ledc/mod.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # LED Controller (LEDC)
 //!
 //! ## Overview
@@ -25,7 +26,7 @@
 //! range 0..100.
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::ledc::Ledc;
 //! # use esp_hal::ledc::LSGlobalClkSource;
 //! # use esp_hal::ledc::timer::{self, TimerIFace};
@@ -37,20 +38,18 @@
 //! ledc.set_global_slow_clock(LSGlobalClkSource::APBClk);
 //!
 //! let mut lstimer0 = ledc.timer::<LowSpeed>(timer::Number::Timer0);
-//! lstimer0
+//! lstimer0.configure(timer::config::Config {
-//!     .configure(timer::config::Config {
+//!     duty: timer::config::Duty::Duty5Bit,
-//!         duty: timer::config::Duty::Duty5Bit,
+//!     clock_source: timer::LSClockSource::APBClk,
-//!         clock_source: timer::LSClockSource::APBClk,
+//!     frequency: Rate::from_khz(24),
-//!         frequency: Rate::from_khz(24),
+//! })?;
-//!     })?;
 //!
 //! let mut channel0 = ledc.channel(channel::Number::Channel0, led);
-//! channel0
+//! channel0.configure(channel::config::Config {
-//!     .configure(channel::config::Config {
+//!     timer: &lstimer0,
-//!         timer: &lstimer0,
+//!     duty_pct: 10,
-//!         duty_pct: 10,
+//!     pin_config: channel::config::PinConfig::PushPull,
-//!         pin_config: channel::config::PinConfig::PushPull,
+//! })?;
-//!     })?;
 //!
 //! loop {
 //!     // Set up a breathing LED: fade from off to on over a second, then
@@ -62,7 +61,7 @@
 //! }
 //! # }
 //! ```
-//! 
+//!
 //! ## Implementation State
 //! - Source clock selection is not supported
 //! - Interrupts are not supported

esp-hal/src/mcpwm/mod.rs

@@ -1,3 +1,9 @@
+#![cfg_attr(docsrs, procmacros::doc_replace(
+    "clock_cfg" => {
+        cfg(not(esp32h2)) => "let clock_cfg = PeripheralClockConfig::with_frequency(Rate::from_mhz(40))?;",
+        cfg(esp32h2) => "let clock_cfg = PeripheralClockConfig::with_frequency(Rate::from_mhz(32))?;"
+    }
+))]
 //! # Motor Control Pulse Width Modulator (MCPWM)
 //!
 //! ## Overview
@@ -48,19 +54,12 @@
 //! `pin`.
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::mcpwm::{operator::{DeadTimeCfg, PWMStream, PwmPinConfig}, timer::PwmWorkingMode, McPwm, PeripheralClockConfig};
 //! # let pin = peripherals.GPIO0;
 //!
 //! // initialize peripheral
-#![cfg_attr(
+//! # {clock_cfg}
-    not(esp32h2),
-    doc = "let clock_cfg = PeripheralClockConfig::with_frequency(Rate::from_mhz(40))?;"
-)]
-#![cfg_attr(
-    esp32h2,
-    doc = "let clock_cfg = PeripheralClockConfig::with_frequency(Rate::from_mhz(32))?;"
-)]
 //! let mut mcpwm = McPwm::new(peripherals.MCPWM0, clock_cfg);
 //!
 //! // connect operator0 to timer0
@@ -78,8 +77,7 @@
 //!
 //! // pin will be high 50% of the time
 //! pwm_pin.set_timestamp(50);
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
 
 use operator::Operator;

esp-hal/src/mcpwm/operator.rs

@@ -440,6 +440,12 @@ impl<PWM: PwmPeripheral, const OP: u8, const IS_A: bool> embedded_hal::pwm::SetD
     }
 }
 
+#[procmacros::doc_replace(
+    "clock_cfg" => {
+        cfg(not(esp32h2)) => "let clock_cfg = PeripheralClockConfig::with_frequency(Rate::from_mhz(40))?;",
+        cfg(esp32h2) => "let clock_cfg = PeripheralClockConfig::with_frequency(Rate::from_mhz(32))?;"
+    }
+)]
 /// Two pins driven by the same timer and operator
 ///
 /// Useful for complementary or mirrored signals with or without
@@ -448,22 +454,14 @@ impl<PWM: PwmPeripheral, const OP: u8, const IS_A: bool> embedded_hal::pwm::SetD
 /// # H-Bridge example
 ///
 /// ```rust, no_run
-#[doc = crate::before_snippet!()]
+/// # {before_snippet}
 /// # use esp_hal::mcpwm::{McPwm, PeripheralClockConfig};
 /// # use esp_hal::mcpwm::operator::{DeadTimeCfg, PwmPinConfig, PWMStream};
 /// // active high complementary using PWMA input
 /// let bridge_active = DeadTimeCfg::new_ahc();
 /// // use PWMB as input for both outputs
-/// let bridge_off = DeadTimeCfg::new_bypass().set_output_swap(PWMStream::PWMA,
+/// let bridge_off = DeadTimeCfg::new_bypass().set_output_swap(PWMStream::PWMA, true);
-/// true);
+/// # {clock_cfg}
-#[cfg_attr(
-    esp32h2,
-    doc = "let clock_cfg = PeripheralClockConfig::with_frequency(Rate::from_mhz(40))?;"
-)]
-#[cfg_attr(
-    not(esp32h2),
-    doc = "let clock_cfg = PeripheralClockConfig::with_frequency(Rate::from_mhz(32))?;"
-)]
 /// let mut mcpwm = McPwm::new(peripherals.MCPWM0, clock_cfg);
 ///
 /// let mut pins = mcpwm.operator0.with_linked_pins(
@@ -482,8 +480,7 @@ impl<PWM: PwmPeripheral, const OP: u8, const IS_A: bool> embedded_hal::pwm::SetD
 /// pins.set_deadtime_cfg(bridge_active);
 /// // pin_a: _______-------_____________-------______
 /// // pin_b: ------_________-----------_________-----
-/// # Ok(())
+/// # {after_snippet}
-/// # }
 /// ```
 pub struct LinkedPins<'d, PWM, const OP: u8> {
     pin_a: PwmPin<'d, PWM, OP, true>,

esp-hal/src/parl_io.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Parallel IO (PARL_IO)
 //!
 //! ## Overview
@@ -14,7 +15,7 @@
 //! ### Initialization for RX
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::delay::Delay;
 //! # use esp_hal::dma_buffers;
 //! # use esp_hal::dma::DmaRxBuf;
@@ -37,23 +38,14 @@
 //!
 //! // Set up Parallel IO for 1MHz data input, with DMA and bit packing
 //! //  configuration
-//!  let parl_io = ParlIo::new(
+//! let parl_io = ParlIo::new(peripherals.PARL_IO, dma_channel)?;
-//!     peripherals.PARL_IO,
-//!     dma_channel,
-//! )?;
 //!
 //! let config = RxConfig::default()
 //!     .with_frequency(Rate::from_mhz(1))
 //!     .with_bit_order(BitPackOrder::Msb)
 //!     .with_timeout_ticks(0xfff);
 //!
-//! let mut parl_io_rx = parl_io
+//! let mut parl_io_rx = parl_io.rx.with_config(rx_pins, rx_clk_pin, config)?;
-//!     .rx
-//!     .with_config(
-//!         rx_pins,
-//!         rx_clk_pin,
-//!         config,
-//!     )?;
 //!
 //! // Initialize the buffer and delay
 //! dma_rx_buf.as_mut_slice().fill(0u8);
@@ -68,10 +60,10 @@
 //! }
 //! # }
 //! ```
-//! 
+//!
 //! ### Initialization for TX
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::delay::Delay;
 //! # use esp_hal::dma_tx_buffer;
 //! # use esp_hal::parl_io::{BitPackOrder, ParlIo, TxFourBits, ClkOutPin, TxConfig, TxPinConfigWithValidPin};

esp-hal/src/pcnt/mod.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Pulse Counter (PCNT)
 //!
 //! ## Overview
@@ -16,7 +17,7 @@
 //! ### Decoding a quadrature encoder
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::gpio::{Input, InputConfig, Pull};
 //! # use esp_hal::interrupt::Priority;
 //! # use esp_hal::pcnt::{channel, unit, Pcnt};
@@ -24,8 +25,8 @@
 //! # use critical_section::Mutex;
 //! # use portable_atomic::AtomicI32;
 //!
-//! static UNIT0: Mutex<RefCell<Option<unit::Unit<'static, 1>>>> =
+//! static UNIT0: Mutex<RefCell<Option<unit::Unit<'static, 1>>>> = Mutex::new(RefCell::new(None));
-//! Mutex::new(RefCell::new(None)); static VALUE: AtomicI32 = AtomicI32::new(0);
+//! static VALUE: AtomicI32 = AtomicI32::new(0);
 //!
 //! // Initialize Pulse Counter (PCNT) unit with limits and filter settings
 //! let mut pcnt = Pcnt::new(peripherals.PCNT);
@@ -46,15 +47,13 @@
 //! ch0.set_ctrl_signal(input_a.clone());
 //! ch0.set_edge_signal(input_b.clone());
 //! ch0.set_ctrl_mode(channel::CtrlMode::Reverse, channel::CtrlMode::Keep);
-//! ch0.set_input_mode(channel::EdgeMode::Increment,
+//! ch0.set_input_mode(channel::EdgeMode::Increment, channel::EdgeMode::Decrement);
-//! channel::EdgeMode::Decrement);
 //!
 //! let ch1 = &u0.channel1;
 //! ch1.set_ctrl_signal(input_b);
 //! ch1.set_edge_signal(input_a);
 //! ch1.set_ctrl_mode(channel::CtrlMode::Reverse, channel::CtrlMode::Keep);
-//! ch1.set_input_mode(channel::EdgeMode::Decrement,
+//! ch1.set_input_mode(channel::EdgeMode::Decrement, channel::EdgeMode::Increment);
-//! channel::EdgeMode::Increment);
 //!
 //! // Enable interrupts and resume pulse counter unit
 //! u0.listen();
@@ -91,7 +90,7 @@
 //! }
 //! # }
 //! ```
-//! 
+//!
 //! [channel]: channel/index.html
 //! [unit]: unit/index.html
 

esp-hal/src/rmt.rs

@@ -1,3 +1,9 @@
+#![cfg_attr(docsrs, procmacros::doc_replace(
+    "freq" => {
+        cfg(esp32h2) => "let freq = Rate::from_mhz(32);",
+        cfg(not(esp32h2)) => "let freq = Rate::from_mhz(80);"
+    }
+))]
 //! # Remote Control Peripheral (RMT)
 //!
 //! ## Overview
@@ -48,35 +54,31 @@
 //! ### Initialization
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::gpio::Level;
 //! # use esp_hal::peripherals::Peripherals;
 //! # use esp_hal::rmt::TxChannelConfig;
 //! # use esp_hal::rmt::Rmt;
 //! # use crate::esp_hal::rmt::TxChannelCreator;
-#![cfg_attr(esp32h2, doc = "let freq = Rate::from_mhz(32);")]
+//! # {freq}
-#![cfg_attr(not(esp32h2), doc = "let freq = Rate::from_mhz(80);")]
 //! let rmt = Rmt::new(peripherals.RMT, freq)?;
-//! let mut channel = rmt
+//! let mut channel = rmt.channel0.configure_tx(
-//!     .channel0
+//!     peripherals.GPIO1,
-//!     .configure_tx(
+//!     TxChannelConfig::default()
-//!         peripherals.GPIO1,
+//!         .with_clk_divider(1)
-//!         TxChannelConfig::default()
+//!         .with_idle_output_level(Level::Low)
-//!             .with_clk_divider(1)
+//!         .with_idle_output(false)
-//!             .with_idle_output_level(Level::Low)
+//!         .with_carrier_modulation(false)
-//!             .with_idle_output(false)
+//!         .with_carrier_high(1)
-//!             .with_carrier_modulation(false)
+//!         .with_carrier_low(1)
-//!             .with_carrier_high(1)
+//!         .with_carrier_level(Level::Low),
-//!             .with_carrier_low(1)
+//! )?;
-//!             .with_carrier_level(Level::Low),
+//! # {after_snippet}
-//!     )?;
-//! # Ok(())
-//! # }
 //! ```
-//! 
+//!
 //! ### TX operation
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::delay::Delay;
 //! # use esp_hal::gpio::Level;
 //! # use esp_hal::rmt::{PulseCode, Rmt, TxChannel, TxChannelConfig, TxChannelCreator};
@@ -108,7 +110,7 @@
 //! 
 //! ### RX operation
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::rmt::{PulseCode, Rmt, RxChannel, RxChannelConfig, RxChannelCreator};
 //! # use esp_hal::delay::Delay;
 //! # use esp_hal::gpio::{Level, Output, OutputConfig};

esp-hal/src/rng.rs

@@ -1,3 +1,9 @@
+#![cfg_attr(docsrs, procmacros::doc_replace(
+    "analog_pin" => {
+        cfg(esp32) => "let analog_pin = peripherals.GPIO32;",
+        cfg(not(esp32)) => "let analog_pin = peripherals.GPIO3;"
+    }
+))]
 //! # Random Number Generator (RNG)
 //!
 //! ## Overview
@@ -39,7 +45,7 @@
 //! ### Basic RNG operation
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::rng::Rng;
 //!
 //! let mut rng = Rng::new(peripherals.RNG);
@@ -54,10 +60,10 @@
 //! loop {}
 //! # }
 //! ```
-//! 
+//!
 //! ### TRNG operation
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::Blocking;
 //! # use esp_hal::rng::Trng;
 //! # use esp_hal::peripherals::Peripherals;
@@ -72,20 +78,15 @@
 //! let mut true_rand = trng.random();
 //! let mut rng = trng.downgrade();
 //! // ADC is available now
-#![cfg_attr(esp32, doc = "let analog_pin = peripherals.GPIO32;")]
+//! # {analog_pin}
-#![cfg_attr(not(esp32), doc = "let analog_pin = peripherals.GPIO3;")]
 //! let mut adc1_config = AdcConfig::new();
-//! let mut adc1_pin = adc1_config.enable_pin(
+//! let mut adc1_pin = adc1_config.enable_pin(analog_pin, Attenuation::_11dB);
-//!     analog_pin,
-//!     Attenuation::_11dB
-//! );
 //! let mut adc1 = Adc::<ADC1, Blocking>::new(peripherals.ADC1, adc1_config);
 //! let pin_value: u16 = nb::block!(adc1.read_oneshot(&mut adc1_pin))?;
 //! rng.read(&mut buf);
 //! true_rand = rng.random();
 //! let pin_value: u16 = nb::block!(adc1.read_oneshot(&mut adc1_pin))?;
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
 
 use crate::{

esp-hal/src/rtc_cntl/mod.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Real-Time Control and Low-power Management (RTC_CNTL)
 //!
 //! ## Overview
@@ -11,17 +12,17 @@
 //! sources and low-power management. The driver provides the following features
 //! and functionalities:
 //!
-//!    * Clock Configuration
+//! * Clock Configuration
-//!    * Calibration
+//! * Calibration
-//!    * Low-Power Management
+//! * Low-Power Management
-//!    * Handling Watchdog Timers
+//! * Handling Watchdog Timers
 //!
 //! ## Examples
 //!
 //! ### Get time in ms from the RTC Timer
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use core::time::Duration;
 //! # use esp_hal::{delay::Delay, rtc_cntl::Rtc};
 //!
@@ -39,10 +40,10 @@
 //! }
 //! # }
 //! ```
-//! 
+//!
 //! ### RWDT usage
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use core::cell::RefCell;
 //! # use critical_section::Mutex;
 //! # use esp_hal::delay::Delay;
@@ -55,12 +56,12 @@
 //! let mut rtc = Rtc::new(peripherals.LPWR);
 //!
 //! rtc.set_interrupt_handler(interrupt_handler);
-//! rtc.rwdt.set_timeout(RwdtStage::Stage0, Duration::from_millis(2000));
+//! rtc.rwdt
+//!     .set_timeout(RwdtStage::Stage0, Duration::from_millis(2000));
 //! rtc.rwdt.listen();
 //!
 //! critical_section::with(|cs| RWDT.borrow_ref_mut(cs).replace(rtc.rwdt));
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //!
 //! // Where the `LP_WDT` interrupt handler is defined as:
 //! # use core::cell::RefCell;
@@ -81,19 +82,16 @@
 //!
 //!             println!("Restarting in 5 seconds...");
 //!
-//!             rwdt.set_timeout(
+//!             rwdt.set_timeout(RwdtStage::Stage0, Duration::from_millis(5000));
-//!                 RwdtStage::Stage0,
-//!                 Duration::from_millis(5000),
-//!             );
 //!             rwdt.unlisten();
 //!         }
 //!     });
 //! }
 //! ```
-//! 
+//!
 //! ### Get time in ms from the RTC Timer
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use core::time::Duration;
 //! # use esp_hal::{delay::Delay, rtc_cntl::Rtc};
 //!
@@ -396,6 +394,7 @@ impl<'d> Rtc<'d> {
         h.write(|w| unsafe { w.bits((boot_time_us >> 32) as u32) });
     }
 
+    #[procmacros::doc_replace]
     /// Get the current time in microseconds.
     ///
     /// # Example
@@ -405,19 +404,19 @@ impl<'d> Rtc<'d> {
     /// environments without dynamic memory allocation.
     ///
     /// ```rust, no_run
-    #[doc = crate::before_snippet!()]
+    /// # {before_snippet}
     /// # use esp_hal::rtc_cntl::Rtc;
-    /// use jiff::{Timestamp, tz::{self, TimeZone}};
+    /// use jiff::{
+    ///     Timestamp,
+    ///     tz::{self, TimeZone},
+    /// };
     ///
     /// static TZ: TimeZone = tz::get!("America/New_York");
     ///
     /// let rtc = Rtc::new(peripherals.LPWR);
-    /// let now = Timestamp::from_microsecond(
+    /// let now = Timestamp::from_microsecond(rtc.current_time_us() as i64)?;
-    ///     rtc.current_time_us() as i64,
-    /// )?;
     /// let weekday_in_new_york = now.to_zoned(TZ.clone()).weekday();
-    /// # Ok(())
+    /// # {after_snippet}
-    /// # }
     /// ```
     pub fn current_time_us(&self) -> u64 {
         // Current time is boot time + time since boot

esp-hal/src/rtc_cntl/sleep/mod.rs

@@ -44,11 +44,12 @@ pub enum WakeupLevel {
     High,
 }
 
+#[procmacros::doc_replace]
 /// Represents a timer wake-up source, triggering an event after a specified
 /// duration.
 ///
 /// ```rust, no_run
-#[doc = crate::before_snippet!()]
+/// # {before_snippet}
 /// # use core::time::Duration;
 /// # use esp_hal::delay::Delay;
 /// # use esp_hal::rtc_cntl::{reset_reason, sleep::TimerWakeupSource, wakeup_cause, Rtc, SocResetReason};
@@ -66,7 +67,7 @@ pub enum WakeupLevel {
 /// delay.delay_millis(100);
 /// rtc.sleep_deep(&[&timer]);
 ///
-/// # }
+/// # {after_snippet}
 /// ```
 #[derive(Debug, Default, Clone, Copy)]
 #[cfg(any(esp32, esp32c3, esp32s2, esp32s3, esp32c6, esp32c2))]
@@ -93,10 +94,11 @@ pub enum Error {
     TooManyWakeupSources,
 }
 
+#[procmacros::doc_replace]
 /// External wake-up source (Ext0).
 ///
 /// ```rust, no_run
-#[doc = crate::before_snippet!()]
+/// # {before_snippet}
 /// # use core::time::Duration;
 /// # use esp_hal::delay::Delay;
 /// # use esp_hal::rtc_cntl::{reset_reason, sleep::{Ext0WakeupSource, TimerWakeupSource, WakeupLevel}, wakeup_cause, Rtc, SocResetReason};
@@ -145,10 +147,11 @@ impl<P: RtcIoWakeupPinType> Ext0WakeupSource<P> {
     }
 }
 
+#[procmacros::doc_replace]
 /// External wake-up source (Ext1).
 ///
 /// ```rust, no_run
-#[doc = crate::before_snippet!()]
+/// # {before_snippet}
 /// # use core::time::Duration;
 /// # use esp_hal::delay::Delay;
 /// # use esp_hal::rtc_cntl::{reset_reason, sleep::{Ext1WakeupSource, TimerWakeupSource, WakeupLevel}, wakeup_cause, Rtc, SocResetReason};
@@ -202,9 +205,10 @@ impl<'a, 'b> Ext1WakeupSource<'a, 'b> {
     }
 }
 
+#[procmacros::doc_replace]
 /// External wake-up source (Ext1).
 /// ```rust, no_run
-#[doc = crate::before_snippet!()]
+/// # {before_snippet}
 /// # use core::time::Duration;
 /// # use esp_hal::delay::Delay;
 /// # use esp_hal::rtc_cntl::{reset_reason, sleep::{Ext1WakeupSource, TimerWakeupSource, WakeupLevel}, wakeup_cause, Rtc, SocResetReason};
@@ -257,6 +261,7 @@ impl<'a, 'b> Ext1WakeupSource<'a, 'b> {
     }
 }
 
+#[procmacros::doc_replace]
 /// RTC_IO wakeup source
 ///
 /// RTC_IO wakeup allows configuring any combination of RTC_IO pins with
@@ -264,7 +269,7 @@ impl<'a, 'b> Ext1WakeupSource<'a, 'b> {
 /// can be used to wake up from both light and deep sleep.
 ///
 /// ```rust, no_run
-#[doc = crate::before_snippet!()]
+/// # {before_snippet}
 /// # use core::time::Duration;
 /// # use esp_hal::delay::Delay;
 /// # use esp_hal::gpio::{self, Input, InputConfig, Pull};

esp-hal/src/sha.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Secure Hash Algorithm (SHA) Accelerator
 //!
 //! ## Overview
@@ -30,7 +31,7 @@
 //!
 //! ## Examples
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::sha::Sha;
 //! # use esp_hal::sha::Sha256;
 //! # use nb::block;
@@ -51,8 +52,7 @@
 //! // the output.
 //! block!(hasher.finish(output.as_mut_slice()))?;
 //!
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
 //! ## Implementation State
 //! - DMA-SHA Mode is not supported.

esp-hal/src/soc/esp32/cpu_control.rs

@@ -99,11 +99,12 @@ pub enum Error {
     CoreAlreadyRunning,
 }
 
+#[procmacros::doc_replace]
 /// Control CPU Cores
 ///
 /// ## Examples
 /// ```rust, no_run
-#[doc = crate::before_snippet!()]
+/// # {before_snippet}
 /// # use esp_hal::delay::Delay;
 /// # use esp_hal::system::{CpuControl, Stack};
 /// # use core::{cell::RefCell, ptr::addr_of_mut};
@@ -117,11 +118,8 @@ pub enum Error {
 /// let cpu1_fnctn = || {
 ///     cpu1_task(&delay, &counter);
 /// };
-/// let _guard = cpu_control
+/// let _guard =
-///     .start_app_core(
+///     cpu_control.start_app_core(unsafe { &mut *addr_of_mut!(APP_CORE_STACK) }, cpu1_fnctn)?;
-///         unsafe { &mut *addr_of_mut!(APP_CORE_STACK) },
-///         cpu1_fnctn
-///     )?;
 ///
 /// loop {
 ///     delay.delay(Duration::from_secs(1));
@@ -133,10 +131,7 @@ pub enum Error {
 /// # use esp_hal::delay::Delay;
 /// # use core::cell::RefCell;
 ///
-/// fn cpu1_task(
+/// fn cpu1_task(delay: &Delay, counter: &critical_section::Mutex<RefCell<i32>>) -> ! {
-///     delay: &Delay,
-///     counter: &critical_section::Mutex<RefCell<i32>>,
-/// ) -> ! {
 ///     loop {
 ///         delay.delay(Duration::from_millis(500));
 ///

esp-hal/src/soc/esp32/efuse/mod.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Reading of eFuses (ESP32)
 //!
 //! ## Overview
@@ -22,7 +23,7 @@
 //! ### Read data from the eFuse storage.
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::efuse::Efuse;
 //!
 //! let mac_address = Efuse::read_base_mac_address();
@@ -43,8 +44,7 @@
 //! println!("Bluetooth enabled {}", Efuse::is_bluetooth_enabled());
 //! println!("Chip type {:?}", Efuse::chip_type());
 //! println!("Max CPU clock {:?}", Efuse::max_cpu_frequency());
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
 
 pub use self::fields::*;

esp-hal/src/soc/esp32/psram.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # PSRAM "virtual peripheral" driver (ESP32)
 //!
 //! ## Overview
@@ -18,7 +19,7 @@
 //! Notice that PSRAM example **must** be built in release mode!
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # extern crate alloc;
 //! # use alloc::{string::String, vec::Vec};
 //! # use esp_alloc as _;
@@ -36,8 +37,7 @@
 //! }
 //!
 //! // Initialize PSRAM and add it to the heap
-//! let (start, size) = psram::init_psram(peripherals.PSRAM,
+//! let (start, size) = psram::init_psram(peripherals.PSRAM, psram::PsramConfig::default());
-//!     psram::PsramConfig::default());
 //!
 //! init_psram_heap(start, size);
 //!

esp-hal/src/soc/esp32c2/efuse/mod.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Reading of eFuses (ESP32-C2)
 //!
 //! ## Overview
@@ -19,7 +20,7 @@
 //! ### Read data from the eFuse storage.
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::efuse::Efuse;
 //!
 //! let mac_address = Efuse::read_base_mac_address();
@@ -36,8 +37,7 @@
 //!
 //! println!("MAC address {:02x?}", Efuse::mac_address());
 //! println!("Flash Encryption {:?}", Efuse::flash_encryption());
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
 
 pub use self::fields::*;

esp-hal/src/soc/esp32c3/efuse/mod.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Reading of eFuses (ESP32-C3)
 //!
 //! ## Overview
@@ -20,7 +21,7 @@
 //! ### Read data from the eFuse storage.
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::efuse::Efuse;
 //!
 //! let mac_address = Efuse::read_base_mac_address();
@@ -37,8 +38,7 @@
 //!
 //! println!("MAC address {:02x?}", Efuse::mac_address());
 //! println!("Flash Encryption {:?}", Efuse::flash_encryption());
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
 
 pub use self::fields::*;

esp-hal/src/soc/esp32c6/efuse/mod.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Reading of eFuses (ESP32-C6)
 //!
 //! ## Overview
@@ -20,7 +21,7 @@
 //! ### Read data from the eFuse storage.
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::efuse::Efuse;
 //!
 //! let mac_address = Efuse::read_base_mac_address();
@@ -37,8 +38,7 @@
 //!
 //! println!("MAC address {:02x?}", Efuse::mac_address());
 //! println!("Flash Encryption {:?}", Efuse::flash_encryption());
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
 
 pub use self::fields::*;

esp-hal/src/soc/esp32h2/efuse/mod.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Reading of eFuses (ESP32-H2)
 //!
 //! ## Overview
@@ -20,7 +21,7 @@
 //! ### Read data from the eFuse storage.
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::efuse::Efuse;
 //!
 //! let mac_address = Efuse::read_base_mac_address();
@@ -37,8 +38,7 @@
 //!
 //! println!("MAC address {:02x?}", Efuse::mac_address());
 //! println!("Flash Encryption {:?}", Efuse::flash_encryption());
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
 
 pub use self::fields::*;

esp-hal/src/soc/esp32s2/efuse/mod.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Reading of eFuses (ESP32-S2)
 //!
 //! ## Overview
@@ -22,7 +23,7 @@
 //! ### Read data from the eFuse storage.
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::efuse::Efuse;
 //!
 //! let mac_address = Efuse::read_base_mac_address();
@@ -39,8 +40,7 @@
 //!
 //! println!("MAC address {:02x?}", Efuse::mac_address());
 //! println!("Flash Encryption {:?}", Efuse::flash_encryption());
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
 
 pub use self::fields::*;

esp-hal/src/soc/esp32s2/psram.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # PSRAM "virtual peripheral" driver (ESP32-S2)
 //!
 //! ## Overview
@@ -18,7 +19,7 @@
 //! Notice that PSRAM example **must** be built in release mode!
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # extern crate alloc;
 //! # use alloc::{string::String, vec::Vec};
 //! # use esp_alloc as _;
@@ -36,8 +37,7 @@
 //! }
 //!
 //! // Initialize PSRAM and add it to the heap
-//! let (start, size) = psram::init_psram(peripherals.PSRAM,
+//! let (start, size) = psram::init_psram(peripherals.PSRAM, psram::PsramConfig::default());
-//!     psram::PsramConfig::default());
 //!
 //! init_psram_heap(start, size);
 //!

esp-hal/src/soc/esp32s2/ulp_core.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Control the ULP core
 //!
 //! ## Overview
@@ -14,23 +15,18 @@
 //!
 //! ## Examples
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! const CODE: &[u8] = &[
-//!     0x17, 0x05, 0x00, 0x00, 0x13, 0x05, 0x05, 0x01, 0x81, 0x45, 0x85, 0x05,
+//!     0x17, 0x05, 0x00, 0x00, 0x13, 0x05, 0x05, 0x01, 0x81, 0x45, 0x85, 0x05, 0x0c, 0xc1, 0xf5,
-//!     0x0c, 0xc1, 0xf5, 0xbf, 0x00, 0x00, 0x00, 0x00,
+//!     0xbf, 0x00, 0x00, 0x00, 0x00,
 //! ];
-//! let mut ulp_core =
+//! let mut ulp_core = esp_hal::ulp_core::UlpCore::new(peripherals.ULP_RISCV_CORE);
-//!     esp_hal::ulp_core::UlpCore::new(peripherals.ULP_RISCV_CORE);
 //! // ulp_core.stop(); currently not implemented
 //!
 //! // copy code to RTC ram
 //! let lp_ram = 0x5000_0000 as *mut u8;
 //! unsafe {
-//!     core::ptr::copy_nonoverlapping(
+//!     core::ptr::copy_nonoverlapping(CODE as *const _ as *const u8, lp_ram, CODE.len());
-//!         CODE as *const _ as *const u8,
-//!         lp_ram,
-//!         CODE.len(),
-//!     );
 //! }
 //!
 //! // start ULP core

esp-hal/src/soc/esp32s3/cpu_control.rs

@@ -100,11 +100,12 @@ pub enum Error {
     CoreAlreadyRunning,
 }
 
+#[procmacros::doc_replace]
 /// Control CPU Cores
 ///
 /// ## Examples
 /// ```rust, no_run
-#[doc = crate::before_snippet!()]
+/// # {before_snippet}
 /// # use esp_hal::delay::Delay;
 /// # use esp_hal::system::{CpuControl, Stack};
 /// # use core::{cell::RefCell, ptr::addr_of_mut};
@@ -118,11 +119,8 @@ pub enum Error {
 /// let cpu1_fnctn = || {
 ///     cpu1_task(&delay, &counter);
 /// };
-/// let _guard = cpu_control
+/// let _guard =
-///     .start_app_core(
+///     cpu_control.start_app_core(unsafe { &mut *addr_of_mut!(APP_CORE_STACK) }, cpu1_fnctn)?;
-///         unsafe { &mut *addr_of_mut!(APP_CORE_STACK) },
-///         cpu1_fnctn
-///     )?;
 ///
 /// loop {
 ///     delay.delay(Duration::from_secs(1));
@@ -134,10 +132,7 @@ pub enum Error {
 /// # use esp_hal::delay::Delay;
 /// # use core::cell::RefCell;
 ///
-/// fn cpu1_task(
+/// fn cpu1_task(delay: &Delay, counter: &critical_section::Mutex<RefCell<i32>>) -> ! {
-///     delay: &Delay,
-///     counter: &critical_section::Mutex<RefCell<i32>>,
-/// ) -> ! {
 ///     loop {
 ///         delay.delay(Duration::from_millis(500));
 ///

esp-hal/src/soc/esp32s3/efuse/mod.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Reading of eFuses (ESP32-S3)
 //!
 //! ## Overview
@@ -20,7 +21,7 @@
 //! ### Read data from the eFuse storage.
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::efuse::Efuse;
 //!
 //! let mac_address = Efuse::read_base_mac_address();
@@ -37,8 +38,7 @@
 //!
 //! println!("MAC address {:02x?}", Efuse::mac_address());
 //! println!("Flash Encryption {:?}", Efuse::flash_encryption());
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
 
 pub use self::fields::*;

esp-hal/src/soc/esp32s3/psram.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # PSRAM "virtual peripheral" driver (ESP32-S3)
 //!
 //! ## Overview
@@ -24,7 +25,7 @@
 //! Notice that PSRAM example **must** be built in release mode!
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # extern crate alloc;
 //! # use alloc::{string::String, vec::Vec};
 //! # use esp_alloc as _;
@@ -42,8 +43,7 @@
 //! }
 //!
 //! // Initialize PSRAM and add it to the heap
-//! let (start, size) = psram::init_psram(peripherals.PSRAM,
+//! let (start, size) = psram::init_psram(peripherals.PSRAM, psram::PsramConfig::default());
-//!     psram::PsramConfig::default());
 //!
 //! init_psram_heap(start, size);
 //!

esp-hal/src/soc/esp32s3/ulp_core.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! Control the ULP core
 //!
 //! ## Overview
@@ -15,24 +16,19 @@
 //! ## Examples
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! const CODE: &[u8] = &[
-//!     0x17, 0x05, 0x00, 0x00, 0x13, 0x05, 0x05, 0x01, 0x81, 0x45, 0x85, 0x05,
+//!     0x17, 0x05, 0x00, 0x00, 0x13, 0x05, 0x05, 0x01, 0x81, 0x45, 0x85, 0x05, 0x0c, 0xc1, 0xf5,
-//!     0x0c, 0xc1, 0xf5, 0xbf, 0x00, 0x00, 0x00, 0x00,
+//!     0xbf, 0x00, 0x00, 0x00, 0x00,
 //! ];
 //!
-//! let mut ulp_core =
+//! let mut ulp_core = esp_hal::ulp_core::UlpCore::new(peripherals.ULP_RISCV_CORE);
-//!     esp_hal::ulp_core::UlpCore::new(peripherals.ULP_RISCV_CORE);
 //! ulp_core.stop();
 //!
 //! // copy code to RTC ram
 //! let lp_ram = 0x5000_0000 as *mut u8;
 //! unsafe {
-//!     core::ptr::copy_nonoverlapping(
+//!     core::ptr::copy_nonoverlapping(CODE as *const _ as *const u8, lp_ram, CODE.len());
-//!         CODE as *const _ as *const u8,
-//!         lp_ram,
-//!         CODE.len(),
-//!     );
 //! }
 //!
 //! // start ULP core

esp-hal/src/spi/slave.rs

@@ -1,3 +1,9 @@
+#![cfg_attr(docsrs, procmacros::doc_replace(
+    "dma_channel" => {
+        cfg(any(esp32, esp32s2)) => "let dma_channel = peripherals.DMA_SPI2;",
+        _ => "let dma_channel = peripherals.DMA_CH0;"
+    },
+))]
 //! # Serial Peripheral Interface - Slave Mode
 //!
 //! ## Overview
@@ -14,49 +20,42 @@
 //! ### SPI Slave with DMA
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::dma_buffers;
 //! # use esp_hal::dma::{DmaRxBuf, DmaTxBuf};
 //! # use esp_hal::spi::Mode;
 //! # use esp_hal::spi::slave::Spi;
-#![cfg_attr(pdma, doc = "let dma_channel = peripherals.DMA_SPI2;")]
+//! # {dma_channel}
-#![cfg_attr(gdma, doc = "let dma_channel = peripherals.DMA_CH0;")]
 //! let sclk = peripherals.GPIO0;
 //! let miso = peripherals.GPIO1;
 //! let mosi = peripherals.GPIO2;
 //! let cs = peripherals.GPIO3;
 //!
-//! let (rx_buffer, rx_descriptors, tx_buffer, tx_descriptors) =
+//! let (rx_buffer, rx_descriptors, tx_buffer, tx_descriptors) = dma_buffers!(32000);
-//! dma_buffers!(32000);
 //! let dma_rx_buf = DmaRxBuf::new(rx_descriptors, rx_buffer).unwrap();
 //! let dma_tx_buf = DmaTxBuf::new(tx_descriptors, tx_buffer).unwrap();
-//! let mut spi = Spi::new(
+//! let mut spi = Spi::new(peripherals.SPI2, Mode::_0)
-//!     peripherals.SPI2,
+//!     .with_sck(sclk)
-//!     Mode::_0,
+//!     .with_mosi(mosi)
-//! )
+//!     .with_miso(miso)
-//! .with_sck(sclk)
+//!     .with_cs(cs)
-//! .with_mosi(mosi)
+//!     .with_dma(dma_channel);
-//! .with_miso(miso)
-//! .with_cs(cs)
-//! .with_dma(dma_channel);
 //!
-//! let transfer = spi
+//! let transfer = spi.transfer(50, dma_rx_buf, 50, dma_tx_buf)?;
-//!     .transfer(50, dma_rx_buf, 50, dma_tx_buf)?;
 //!
 //! transfer.wait();
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
-//! 
+//!
 //! ## Implementation State
 //!
 //! This driver is currently **unstable**.
 //!
 //! There are several options for working with the SPI peripheral in slave mode,
 //! but the code currently only supports:
-//! - Single transfers (not segmented transfers)
+//!     - Single transfers (not segmented transfers)
-//! - Full duplex, single bit (not dual or quad SPI)
+//!     - Full duplex, single bit (not dual or quad SPI)
-//! - DMA mode (not CPU mode).
+//!     - DMA mode (not CPU mode).
 #![cfg_attr(esp32, doc = "- ESP32 only supports SPI mode 1 and 3.\n\n")]
 //! It also does not support blocking operations, as the actual
 //! transfer is controlled by the SPI master; if these are necessary,

esp-hal/src/timer/mod.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # General-purpose Timers
 //!
 //! ## Overview
@@ -15,20 +16,19 @@
 //! ### One-shot Timer
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::timer::{OneShotTimer, PeriodicTimer, timg::TimerGroup};
 //! #
 //! let timg0 = TimerGroup::new(peripherals.TIMG0);
 //! let mut one_shot = OneShotTimer::new(timg0.timer0);
 //!
 //! one_shot.delay_millis(500);
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
-//! 
+//!
 //! ### Periodic Timer
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::timer::{PeriodicTimer, timg::TimerGroup};
 //! #
 //! let timg0 = TimerGroup::new(peripherals.TIMG0);
@@ -36,7 +36,7 @@
 //!
 //! periodic.start(Duration::from_secs(1));
 //! loop {
-//!    periodic.wait();
+//!     periodic.wait();
 //! }
 //! # }
 //! ```

esp-hal/src/timer/systimer.rs

@@ -665,6 +665,7 @@ mod asynch {
 
 #[cfg(soc_has_etm)]
 pub mod etm {
+    #![cfg_attr(docsrs, procmacros::doc_replace)]
     //! # Event Task Matrix Function
     //!
     //! ## Overview
@@ -673,11 +674,11 @@ pub mod etm {
     //! allows the system timer’s ETM events to trigger any peripherals’ ETM
     //! tasks.
     //!
-    //!    The system timer can generate the following ETM events:
+    //! The system timer can generate the following ETM events:
-    //!    - SYSTIMER_EVT_CNT_CMPx: Indicates the alarm pulses generated by COMPx
+    //! - SYSTIMER_EVT_CNT_CMPx: Indicates the alarm pulses generated by COMPx
     //! ## Example
     //! ```rust, no_run
-    #![doc = crate::before_snippet!()]
+    //! # {before_snippet}
     //! # use esp_hal::timer::systimer::{etm::Event, SystemTimer};
     //! # use esp_hal::timer::PeriodicTimer;
     //! # use esp_hal::etm::Etm;
@@ -702,14 +703,12 @@ pub mod etm {
     //!     },
     //! );
     //!
-    //! let _configured_etm_channel = etm.channel0.setup(&timer_event,
+    //! let _configured_etm_channel = etm.channel0.setup(&timer_event, &led_task);
-    //! &led_task);
     //!
     //! let timer = PeriodicTimer::new(alarm0);
     //! // configure the timer as usual
     //! // when it fires it will toggle the GPIO
-    //! # Ok(())
+    //! # {after_snippet}
-    //! # }
     //! ```
 
     use super::*;

esp-hal/src/timer/timg.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Timer Group (TIMG)
 //!
 //! ## Overview
@@ -25,9 +26,8 @@
 //! ### General-purpose Timer
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
-//! use esp_hal::timer::timg::TimerGroup;
+//! use esp_hal::timer::{Timer, timg::TimerGroup};
-//! use esp_hal::timer::Timer;
 //!
 //! let timg0 = TimerGroup::new(peripherals.TIMG0);
 //! let timer0 = timg0.timer0;
@@ -44,16 +44,16 @@
 //! }
 //!
 //! timer0.clear_interrupt();
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
-//! 
+//!
 //! ### Watchdog Timer
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
-//! use esp_hal::timer::timg::TimerGroup;
+//! use esp_hal::timer::{
-//! use esp_hal::timer::timg::MwdtStage;
+//!     Timer,
-//! use esp_hal::timer::Timer;
+//!     timg::{MwdtStage, TimerGroup},
+//! };
 //!
 //! let timg0 = TimerGroup::new(peripherals.TIMG0);
 //! let mut wdt = timg0.wdt;

esp-hal/src/touch.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Capacitive Touch Sensor
 //!
 //! ## Overview
@@ -8,17 +9,16 @@
 //! ## Examples
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::touch::{Touch, TouchPad};
 //! let touch_pin0 = peripherals.GPIO2;
 //! let touch = Touch::continuous_mode(peripherals.TOUCH, None);
 //! let mut touchpad = TouchPad::new(touch_pin0, &touch);
 //! // ... give the peripheral some time for the measurement
 //! let touch_val = touchpad.read();
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
-//! 
+//!
 //! ## Implementation State:
 //!
 //! Mostly feature complete, missing:
@@ -179,21 +179,21 @@ impl<Tm: TouchMode, Dm: DriverMode> Touch<'_, Tm, Dm> {
 }
 // Async mode and OneShot does not seem to be a sensible combination....
 impl<'d> Touch<'d, OneShot, Blocking> {
+    #[procmacros::doc_replace]
     /// Initializes the touch peripheral and returns this marker struct.
     /// Optionally accepts configuration options.
     ///
     /// ## Example
     ///
     /// ```rust, no_run
-    #[doc = crate::before_snippet!()]
+    /// # {before_snippet}
     /// # use esp_hal::touch::{Touch, TouchConfig};
     /// let touch_cfg = Some(TouchConfig {
     ///     measurement_duration: Some(0x2000),
     ///     ..Default::default()
     /// });
     /// let touch = Touch::one_shot_mode(peripherals.TOUCH, touch_cfg);
-    /// # Ok(())
+    /// # {after_snippet}
-    /// # }
     /// ```
     pub fn one_shot_mode(touch_peripheral: TOUCH<'d>, config: Option<TouchConfig>) -> Self {
         let rtccntl = LPWR::regs();
@@ -236,21 +236,21 @@ impl<'d> Touch<'d, OneShot, Blocking> {
     }
 }
 impl<'d> Touch<'d, Continuous, Blocking> {
+    #[procmacros::doc_replace]
     /// Initializes the touch peripheral in continuous mode and returns this
     /// marker struct. Optionally accepts configuration options.
     ///
     /// ## Example
     ///
     /// ```rust, no_run
-    #[doc = crate::before_snippet!()]
+    /// # {before_snippet}
     /// # use esp_hal::touch::{Touch, TouchConfig};
     /// let touch_cfg = Some(TouchConfig {
     ///     measurement_duration: Some(0x3000),
     ///     ..Default::default()
     /// });
     /// let touch = Touch::continuous_mode(peripherals.TOUCH, touch_cfg);
-    /// # Ok(())
+    /// # {after_snippet}
-    /// # }
     /// ```
     pub fn continuous_mode(touch_peripheral: TOUCH<'d>, config: Option<TouchConfig>) -> Self {
         Self::initialize_common_continuous(config);
@@ -263,6 +263,7 @@ impl<'d> Touch<'d, Continuous, Blocking> {
     }
 }
 impl<'d> Touch<'d, Continuous, Async> {
+    #[procmacros::doc_replace]
     /// Initializes the touch peripheral in continuous async mode and returns
     /// this marker struct.
     ///
@@ -282,13 +283,12 @@ impl<'d> Touch<'d, Continuous, Async> {
     /// ## Example
     ///
     /// ```rust, no_run
-    #[doc = crate::before_snippet!()]
+    /// # {before_snippet}
     /// # use esp_hal::rtc_cntl::Rtc;
     /// # use esp_hal::touch::{Touch, TouchConfig};
     /// let mut rtc = Rtc::new(peripherals.LPWR);
     /// let touch = Touch::async_mode(peripherals.TOUCH, &mut rtc, None);
-    /// # Ok(())
+    /// # {after_snippet}
-    /// # }
     /// ```
     pub fn async_mode(
         touch_peripheral: TOUCH<'d>,

esp-hal/src/trace.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # RISC-­V Trace Encoder (TRACE)
 //!
 //! ## Overview
@@ -20,7 +21,7 @@
 //!
 //! ## Examples
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::trace::Trace;
 //! let mut buffer = [0_u8; 1024];
 //! let mut trace = Trace::new(peripherals.TRACE0);
@@ -30,8 +31,7 @@
 //! // end traced code
 //! let res = trace.stop_trace()?;
 //! // transfer the trace result to the host and decode it there
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
 
 use crate::{pac::trace::RegisterBlock, peripherals::TRACE0, system::PeripheralGuard};

esp-hal/src/tsens.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Temperature Sensor (tsens)
 //!
 //! ## Overview
@@ -22,23 +23,21 @@
 //! second, and print it
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::tsens::{TemperatureSensor, Config};
 //! # use esp_hal::delay::Delay;
 //!
-//! let temperature_sensor = TemperatureSensor::new(
+//! let temperature_sensor = TemperatureSensor::new(peripherals.TSENS, Config::default())?;
-//!         peripherals.TSENS,
-//!         Config::default())?;
 //! let delay = Delay::new();
 //! delay.delay_micros(200);
 //! loop {
-//!   let temp = temperature_sensor.get_temperature();
+//!     let temp = temperature_sensor.get_temperature();
-//!   println!("Temperature: {:.2}°C", temp.to_celcius());
+//!     println!("Temperature: {:.2}°C", temp.to_celcius());
-//!   delay.delay_millis(1_000);
+//!     delay.delay_millis(1_000);
 //! }
 //! # }
 //! ```
-//! 
+//!
 //! ## Implementation State
 //!
 //! - Temperature calibration range is not supported

esp-hal/src/twai/filter.rs

@@ -102,6 +102,7 @@ pub struct SingleStandardFilter {
 }
 
 impl SingleStandardFilter {
+    #[procmacros::doc_replace]
     /// Create a new filter that matches against a single 11-bit standard id.
     /// The filter can match against the packet's id, RTR bit, and first two
     /// bytes of the payload.
@@ -109,16 +110,11 @@ impl SingleStandardFilter {
     /// Example matching only even IDs, allowing any rtr value and any payload
     /// data:
     /// ```rust, no_run
-    #[doc = crate::before_snippet!()]
+    /// # {before_snippet}
     /// # use esp_hal::twai::filter::SingleStandardFilter;
     /// const FILTER: SingleStandardFilter =
-    ///     SingleStandardFilter::new(
+    ///     SingleStandardFilter::new(b"xxxxxxxxxx0", b"x", [b"xxxxxxxx", b"xxxxxxxx"]);
-    ///         b"xxxxxxxxxx0",
+    /// # {after_snippet}
-    ///         b"x",
-    ///         [b"xxxxxxxx", b"xxxxxxxx"]
-    ///     );
-    /// # Ok(())
-    /// # }
     /// ```
     pub const fn new(id: &BitFilter<11>, rtr: &BitFilter<1>, payload: [&BitFilter<8>; 2]) -> Self {
         // The bit values we desire to match against. This determines whether we want a

esp-hal/src/twai/mod.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! # Two-wire Automotive Interface (TWAI)
 //!
 //! ## Overview
@@ -24,7 +25,7 @@
 //! ### Transmitting and Receiving Messages
 //!
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::twai;
 //! # use esp_hal::twai::filter;
 //! # use esp_hal::twai::filter::SingleStandardFilter;
@@ -47,13 +48,14 @@
 //!     twai_rx_pin,
 //!     twai_tx_pin,
 //!     TWAI_BAUDRATE,
-//!     TwaiMode::Normal
+//!     TwaiMode::Normal,
 //! );
 //!
 //! // Partially filter the incoming messages to reduce overhead of receiving
 //! // undesired messages
-//! twai_config.set_filter(const { SingleStandardFilter::new(b"xxxxxxxxxx0",
+//! twai_config.set_filter(
-//! b"x", [b"xxxxxxxx", b"xxxxxxxx"]) });
+//!     const { SingleStandardFilter::new(b"xxxxxxxxxx0", b"x", [b"xxxxxxxx", b"xxxxxxxx"]) },
+//! );
 //!
 //! // Start the peripheral. This locks the configuration settings of the
 //! // peripheral and puts it into operation mode, allowing packets to be sent
@@ -69,10 +71,10 @@
 //! }
 //! # }
 //! ```
-//! 
+//!
 //! ### Self-testing (self reception of transmitted messages)
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::twai;
 //! # use esp_hal::twai::filter;
 //! # use esp_hal::twai::filter::SingleStandardFilter;

esp-hal/src/usb_serial_jtag.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, procmacros::doc_replace)]
 //! USB Serial/JTAG Controller (USB_SERIAL_JTAG)
 //!
 //! ## Overview
@@ -42,20 +43,19 @@
 //!
 //! ### Sending and Receiving Data
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! use esp_hal::usb_serial_jtag::UsbSerialJtag;
 //!
 //! let mut usb_serial = UsbSerialJtag::new(peripherals.USB_DEVICE);
 //!
 //! // Write bytes out over the USB Serial/JTAG:
 //! usb_serial.write(b"Hello, world!")?;
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
-//! 
+//!
 //! ### Splitting the USB Serial/JTAG into TX and RX Components
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! use esp_hal::usb_serial_jtag::UsbSerialJtag;
 //!
 //! let mut usb_serial = UsbSerialJtag::new(peripherals.USB_DEVICE);
@@ -67,13 +67,12 @@
 //! // Serial/JTAG:
 //! tx.write(&[42u8])?;
 //! let byte = rx.read_byte()?;
-//! # Ok(())
+//! # {after_snippet}
-//! # }
 //! ```
-//! 
+//!
 //! ### How to output text using USB Serial/JTAG.
 //! ```rust, no_run
-#![doc = crate::before_snippet!()]
+//! # {before_snippet}
 //! # use esp_hal::{delay::Delay, usb_serial_jtag::UsbSerialJtag, Blocking};
 //!
 //! let delay = Delay::new();
@@ -82,8 +81,7 @@
 //! usb_serial.set_interrupt_handler(usb_device);
 //! usb_serial.listen_rx_packet_recv_interrupt();
 //!
-//! critical_section::with(|cs|
+//! critical_section::with(|cs| USB_SERIAL.borrow_ref_mut(cs).replace(usb_serial));
-//! USB_SERIAL.borrow_ref_mut(cs).replace(usb_serial));
 //!
 //! loop {
 //!     println!("Send keystrokes to see the interrupt trigger");
@@ -94,9 +92,8 @@
 //! # use critical_section::Mutex;
 //! # use core::{cell::RefCell, fmt::Write};
 //! # use esp_hal::usb_serial_jtag::UsbSerialJtag;
-//! static USB_SERIAL:
+//! static USB_SERIAL: Mutex<RefCell<Option<UsbSerialJtag<'static, esp_hal::Blocking>>>> =
-//!     Mutex<RefCell<Option<UsbSerialJtag<'static, esp_hal::Blocking>>>> =
+//!     Mutex::new(RefCell::new(None));
-//!         Mutex::new(RefCell::new(None));
 //!
 //! #[handler]
 //! fn usb_device() {
@@ -114,7 +111,7 @@
 //!     });
 //! }
 //! ```
-//! 
+//!
 //! [embedded-hal]: https://docs.rs/embedded-hal/latest/embedded_hal/
 //! [embedded-io]: https://docs.rs/embedded-io/latest/embedded_io/
 //! [embedded-hal-async]: https://docs.rs/embedded-hal-async/latest/embedded_hal_async/

xtask/src/semver_check.rs

@@ -89,6 +89,8 @@ pub(crate) fn build_doc_json(
         features
     );
 
+    let envs = vec![("RUSTDOCFLAGS", "--cfg docsrs --cfg not_really_docsrs")];
+
     // always use `esp` toolchain so we don't have to deal with potentially
     // different versions of the doc-json
     let mut cargo_builder = CargoArgsBuilder::default()
@@ -102,7 +104,7 @@ pub(crate) fn build_doc_json(
     cargo_builder = cargo_builder.arg("-Zbuild-std=alloc,core");
     let cargo_args = cargo_builder.build();
     log::debug!("{cargo_args:#?}");
-    crate::cargo::run(&cargo_args, package_path)?;
+    crate::cargo::run_with_env(&cargo_args, package_path, envs, false)?;
     Ok(current_path)
 }