From 5d1472d73eac17e82bdfbb9ccc6e72e62609a53a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Quentin?= Date: Fri, 11 Jul 2025 11:32:12 +0200 Subject: [PATCH] Use `doc_replace` more (#3786) * Use `doc_replace` more * Fix * Fix --- esp-hal/src/aes/mod.rs | 8 ++--- esp-hal/src/analog/adc/mod.rs | 23 ++++++------- esp-hal/src/analog/dac.rs | 11 ++++-- esp-hal/src/dma/mod.rs | 46 ++++++++++++++++---------- esp-hal/src/etm.rs | 11 +++--- esp-hal/src/gpio/etm.rs | 6 ++-- esp-hal/src/gpio/interconnect.rs | 6 ++-- esp-hal/src/gpio/lp_io.rs | 9 +++-- esp-hal/src/gpio/rtc_io.rs | 6 ++-- esp-hal/src/i2s/master.rs | 26 ++++++++++----- esp-hal/src/i2s/parallel.rs | 13 +++----- esp-hal/src/interrupt/mod.rs | 11 +++--- esp-hal/src/interrupt/software.rs | 12 +++---- esp-hal/src/lcd_cam/cam.rs | 36 +++++++++----------- esp-hal/src/lcd_cam/lcd/dpi.rs | 6 ++-- esp-hal/src/lcd_cam/lcd/i8080.rs | 15 +++------ esp-hal/src/ledc/mod.rs | 27 ++++++++------- esp-hal/src/mcpwm/mod.rs | 20 +++++------ esp-hal/src/mcpwm/operator.rs | 23 ++++++------- esp-hal/src/parl_io.rs | 20 ++++------- esp-hal/src/pcnt/mod.rs | 15 ++++----- esp-hal/src/rmt.rs | 44 ++++++++++++------------ esp-hal/src/rng.rs | 23 +++++++------ esp-hal/src/rtc_cntl/mod.rs | 45 ++++++++++++------------- esp-hal/src/rtc_cntl/sleep/mod.rs | 17 ++++++---- esp-hal/src/sha.rs | 6 ++-- esp-hal/src/soc/esp32/cpu_control.rs | 15 +++------ esp-hal/src/soc/esp32/efuse/mod.rs | 6 ++-- esp-hal/src/soc/esp32/psram.rs | 6 ++-- esp-hal/src/soc/esp32c2/efuse/mod.rs | 6 ++-- esp-hal/src/soc/esp32c3/efuse/mod.rs | 6 ++-- esp-hal/src/soc/esp32c6/efuse/mod.rs | 6 ++-- esp-hal/src/soc/esp32h2/efuse/mod.rs | 6 ++-- esp-hal/src/soc/esp32s2/efuse/mod.rs | 6 ++-- esp-hal/src/soc/esp32s2/psram.rs | 6 ++-- esp-hal/src/soc/esp32s2/ulp_core.rs | 16 ++++----- esp-hal/src/soc/esp32s3/cpu_control.rs | 15 +++------ esp-hal/src/soc/esp32s3/efuse/mod.rs | 6 ++-- esp-hal/src/soc/esp32s3/psram.rs | 6 ++-- esp-hal/src/soc/esp32s3/ulp_core.rs | 16 ++++----- esp-hal/src/spi/slave.rs | 43 ++++++++++++------------ esp-hal/src/timer/mod.rs | 12 +++---- esp-hal/src/timer/systimer.rs | 13 ++++---- esp-hal/src/timer/timg.rs | 20 +++++------ esp-hal/src/touch.rs | 26 +++++++-------- esp-hal/src/trace.rs | 6 ++-- esp-hal/src/tsens.rs | 15 ++++----- esp-hal/src/twai/filter.rs | 12 +++---- esp-hal/src/twai/mod.rs | 14 ++++---- esp-hal/src/usb_serial_jtag.rs | 27 +++++++-------- xtask/src/semver_check.rs | 4 ++- 51 files changed, 386 insertions(+), 413 deletions(-) diff --git a/esp-hal/src/aes/mod.rs b/esp-hal/src/aes/mod.rs index f7a0ff651..9b2f9a0dd 100644 --- a/esp-hal/src/aes/mod.rs +++ b/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 diff --git a/esp-hal/src/analog/adc/mod.rs b/esp-hal/src/analog/adc/mod.rs index f55f17fe3..c64a7cf3c 100644 --- a/esp-hal/src/analog/adc/mod.rs +++ b/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;")] -#![cfg_attr(any(esp32s2, esp32s3), doc = "let analog_pin = peripherals.GPIO3;")] -#![cfg_attr( - not(any(esp32, esp32s2, esp32s3)), - doc = "let analog_pin = peripherals.GPIO2;" -)] +//! # {analog_pin} //! let mut adc1_config = AdcConfig::new(); -//! let mut pin = adc1_config.enable_pin( -//! analog_pin, -//! Attenuation::_11dB, -//! ); +//! let mut pin = adc1_config.enable_pin(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]. diff --git a/esp-hal/src/analog/dac.rs b/esp-hal/src/analog/dac.rs index 6f9fa9bae..b741b2c24 100644 --- a/esp-hal/src/analog/dac.rs +++ b/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;")] -#![cfg_attr(esp32s2, doc = "let dac1_pin = peripherals.GPIO17;")] +//! # {dac1_pin} //! let mut dac1 = Dac::new(peripherals.DAC1, dac1_pin); //! //! let mut delay = Delay::new(); diff --git a/esp-hal/src/dma/mod.rs b/esp-hal/src/dma/mod.rs index b8aa40c00..0d6918d27 100644 --- a/esp-hal/src/dma/mod.rs +++ b/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;")] -#![cfg_attr(gdma, doc = "let dma_channel = peripherals.DMA_CH0;")] +//! # {dma_channel} //! 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)). -//! with_mode(Mode::_0) )? +//! Config::default() +//! .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 DmaChannelConvert 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 DmaChannelConvert for DEG { /// types compatible with a specific peripheral. /// /// ```rust,no_run -#[doc = crate::before_snippet!()] -/// use esp_hal::spi::master::{ -/// AnySpi, Spi, SpiDma, Config, Instance as SpiInstance +/// # {before_snippet} +/// use esp_hal::{ +/// 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 DmaChannelConvert 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;")] -#[doc = ""] -/// let spi = Spi::new( -/// peripherals.SPI2, -/// Config::default(), -/// )?; +/// +/// # {dma_channel} +/// +/// let spi = Spi::new(peripherals.SPI2, Config::default())?; /// /// let spi_dma = configures_spi_dma(spi, dma_channel); /// # Ok(()) diff --git a/esp-hal/src/etm.rs b/esp-hal/src/etm.rs index 04b38a038..9a9026f7c 100644 --- a/esp-hal/src/etm.rs +++ b/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 -//! .falling_edge(button, InputConfig { pull: Pull::Down }); +//! .channel0_event +//! .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; diff --git a/esp-hal/src/gpio/etm.rs b/esp-hal/src/gpio/etm.rs index 8222dfc9e..262346e42 100644 --- a/esp-hal/src/gpio/etm.rs +++ b/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; diff --git a/esp-hal/src/gpio/interconnect.rs b/esp-hal/src/gpio/interconnect.rs index 5a5681df7..4a2160bc4 100644 --- a/esp-hal/src/gpio/interconnect.rs +++ b/esp-hal/src/gpio/interconnect.rs @@ -912,6 +912,7 @@ impl NoOp { } } +#[procmacros::doc_replace] /// ```rust,compile_fail /// // Regression test for /// // 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 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() {} diff --git a/esp-hal/src/gpio/lp_io.rs b/esp-hal/src/gpio/lp_io.rs index 5e3f9a6ed..a48deb6dc 100644 --- a/esp-hal/src/gpio/lp_io.rs +++ b/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> = -//! LowPowerOutput::new(peripherals.GPIO1); -//! # Ok(()) -//! # } +//! let lp_pin: LowPowerOutput<'_, 1> = LowPowerOutput::new(peripherals.GPIO1); +//! # {after_snippet} //! ``` use core::marker::PhantomData; diff --git a/esp-hal/src/gpio/rtc_io.rs b/esp-hal/src/gpio/rtc_io.rs index af404298f..084f5236a 100644 --- a/esp-hal/src/gpio/rtc_io.rs +++ b/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; diff --git a/esp-hal/src/i2s/master.rs b/esp-hal/src/i2s/master.rs index dd63c2e9f..f729f2012 100644 --- a/esp-hal/src/i2s/master.rs +++ b/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;")] -#![cfg_attr( - not(any(esp32, esp32s2)), - doc = "let dma_channel = peripherals.DMA_CH0;" -)] +//! # {dma_channel} //! 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);")] -//! let mut i2s_rx = i2s.i2s_rx +//! # {mclk} +//! 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. diff --git a/esp-hal/src/i2s/parallel.rs b/esp-hal/src/i2s/parallel.rs index 8c1b649ab..d9781f7af 100644 --- a/esp-hal/src/i2s/parallel.rs +++ b/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( -//! i2s, -//! dma_channel, -//! Rate::from_mhz(1), -//! pins, -//! clock, -//! ).into_async(); +//! let mut parallel = +//! I2sParallel::new(i2s, 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}, diff --git a/esp-hal/src/interrupt/mod.rs b/esp-hal/src/interrupt/mod.rs index e4ee5167a..58db1aaae 100644 --- a/esp-hal/src/interrupt/mod.rs +++ b/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!()] -//! let mut sw_int = -//! SoftwareInterruptControl::new(peripherals.SW_INTERRUPT); +//! # {before_snippet} +//! let mut sw_int = 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>>> = -//! Mutex::new(RefCell::new(None)); +//! static SWINT0: Mutex>>> = Mutex::new(RefCell::new(None)); //! //! #[handler(priority = Priority::Priority1)] //! fn swint0_handler() { diff --git a/esp-hal/src/interrupt/software.rs b/esp-hal/src/interrupt/software.rs index f81e1168c..97bf2f208 100644 --- a/esp-hal/src/interrupt/software.rs +++ b/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!()] -//! let sw_ints = -//! SoftwareInterruptControl::new(peripherals.SW_INTERRUPT); +//! # {before_snippet} +//! let sw_ints = 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>>> = -//! Mutex::new(RefCell::new(None)); +//! static SWINT0: Mutex>>> = Mutex::new(RefCell::new(None)); //! //! #[handler] //! fn swint0_handler() { diff --git a/esp-hal/src/lcd_cam/cam.rs b/esp-hal/src/lcd_cam/cam.rs index 43fa003dd..bbfcc9cae 100644 --- a/esp-hal/src/lcd_cam/cam.rs +++ b/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( -//! lcd_cam.cam, -//! peripherals.DMA_CH0, -//! config, -//! )? -//! .with_master_clock(mclk_pin) // Remove this for slave mode -//! .with_pixel_clock(pclk_pin) -//! .with_vsync(vsync_pin) -//! .with_h_enable(href_pin) -//! .with_data0(peripherals.GPIO11) -//! .with_data1(peripherals.GPIO9) -//! .with_data2(peripherals.GPIO8) -//! .with_data3(peripherals.GPIO10) -//! .with_data4(peripherals.GPIO12) -//! .with_data5(peripherals.GPIO18) -//! .with_data6(peripherals.GPIO17) -//! .with_data7(peripherals.GPIO16); +//! let mut camera = Camera::new(lcd_cam.cam, peripherals.DMA_CH0, config)? +//! .with_master_clock(mclk_pin) // Remove this for slave mode +//! .with_pixel_clock(pclk_pin) +//! .with_vsync(vsync_pin) +//! .with_h_enable(href_pin) +//! .with_data0(peripherals.GPIO11) +//! .with_data1(peripherals.GPIO9) +//! .with_data2(peripherals.GPIO8) +//! .with_data3(peripherals.GPIO10) +//! .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::{ diff --git a/esp-hal/src/lcd_cam/lcd/dpi.rs b/esp-hal/src/lcd_cam/lcd/dpi.rs index bf44b71f1..98f91c2a6 100644 --- a/esp-hal/src/lcd_cam/lcd/dpi.rs +++ b/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::{ diff --git a/esp-hal/src/lcd_cam/lcd/i8080.rs b/esp-hal/src/lcd_cam/lcd/i8080.rs index db52e3074..2940898d9 100644 --- a/esp-hal/src/lcd_cam/lcd/i8080.rs +++ b/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( -//! lcd_cam.lcd, -//! peripherals.DMA_CH0, -//! tx_pins, -//! config, -//! )? -//! .with_ctrl_pins(peripherals.GPIO0, peripherals.GPIO47); +//! let mut i8080 = I8080::new(lcd_cam.lcd, 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::{ diff --git a/esp-hal/src/ledc/mod.rs b/esp-hal/src/ledc/mod.rs index a40c54d6b..d877ec9f0 100644 --- a/esp-hal/src/ledc/mod.rs +++ b/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::(timer::Number::Timer0); -//! lstimer0 -//! .configure(timer::config::Config { -//! duty: timer::config::Duty::Duty5Bit, -//! clock_source: timer::LSClockSource::APBClk, -//! frequency: Rate::from_khz(24), -//! })?; +//! lstimer0.configure(timer::config::Config { +//! duty: timer::config::Duty::Duty5Bit, +//! clock_source: timer::LSClockSource::APBClk, +//! frequency: Rate::from_khz(24), +//! })?; //! //! let mut channel0 = ledc.channel(channel::Number::Channel0, led); -//! channel0 -//! .configure(channel::config::Config { -//! timer: &lstimer0, -//! duty_pct: 10, -//! pin_config: channel::config::PinConfig::PushPull, -//! })?; +//! channel0.configure(channel::config::Config { +//! timer: &lstimer0, +//! duty_pct: 10, +//! 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 diff --git a/esp-hal/src/mcpwm/mod.rs b/esp-hal/src/mcpwm/mod.rs index 373731536..d24a9eae9 100644 --- a/esp-hal/src/mcpwm/mod.rs +++ b/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( - 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))?;" -)] +//! # {clock_cfg} //! 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; diff --git a/esp-hal/src/mcpwm/operator.rs b/esp-hal/src/mcpwm/operator.rs index bc9b2b90e..7775c4d54 100644 --- a/esp-hal/src/mcpwm/operator.rs +++ b/esp-hal/src/mcpwm/operator.rs @@ -440,6 +440,12 @@ impl 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 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, -/// true); -#[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 bridge_off = DeadTimeCfg::new_bypass().set_output_swap(PWMStream::PWMA, true); +/// # {clock_cfg} /// let mut mcpwm = McPwm::new(peripherals.MCPWM0, clock_cfg); /// /// let mut pins = mcpwm.operator0.with_linked_pins( @@ -482,8 +480,7 @@ impl 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>, diff --git a/esp-hal/src/parl_io.rs b/esp-hal/src/parl_io.rs index d006a7aa4..81a0bfe78 100644 --- a/esp-hal/src/parl_io.rs +++ b/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( -//! peripherals.PARL_IO, -//! dma_channel, -//! )?; +//! let parl_io = ParlIo::new(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 -//! .rx -//! .with_config( -//! rx_pins, -//! rx_clk_pin, -//! config, -//! )?; +//! let mut parl_io_rx = parl_io.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}; diff --git a/esp-hal/src/pcnt/mod.rs b/esp-hal/src/pcnt/mod.rs index c85a813d5..3ab4d5fb3 100644 --- a/esp-hal/src/pcnt/mod.rs +++ b/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>>> = -//! Mutex::new(RefCell::new(None)); static VALUE: AtomicI32 = AtomicI32::new(0); +//! static UNIT0: Mutex>>> = Mutex::new(RefCell::new(None)); +//! 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, -//! channel::EdgeMode::Decrement); +//! ch0.set_input_mode(channel::EdgeMode::Increment, 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, -//! channel::EdgeMode::Increment); +//! ch1.set_input_mode(channel::EdgeMode::Decrement, channel::EdgeMode::Increment); //! //! // Enable interrupts and resume pulse counter unit //! u0.listen(); @@ -91,7 +90,7 @@ //! } //! # } //! ``` -//! +//! //! [channel]: channel/index.html //! [unit]: unit/index.html diff --git a/esp-hal/src/rmt.rs b/esp-hal/src/rmt.rs index 67c3ce5d0..68a3276b9 100644 --- a/esp-hal/src/rmt.rs +++ b/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);")] -#![cfg_attr(not(esp32h2), doc = "let freq = Rate::from_mhz(80);")] +//! # {freq} //! let rmt = Rmt::new(peripherals.RMT, freq)?; -//! let mut channel = rmt -//! .channel0 -//! .configure_tx( -//! peripherals.GPIO1, -//! TxChannelConfig::default() -//! .with_clk_divider(1) -//! .with_idle_output_level(Level::Low) -//! .with_idle_output(false) -//! .with_carrier_modulation(false) -//! .with_carrier_high(1) -//! .with_carrier_low(1) -//! .with_carrier_level(Level::Low), -//! )?; -//! # Ok(()) -//! # } +//! let mut channel = rmt.channel0.configure_tx( +//! peripherals.GPIO1, +//! TxChannelConfig::default() +//! .with_clk_divider(1) +//! .with_idle_output_level(Level::Low) +//! .with_idle_output(false) +//! .with_carrier_modulation(false) +//! .with_carrier_high(1) +//! .with_carrier_low(1) +//! .with_carrier_level(Level::Low), +//! )?; +//! # {after_snippet} //! ``` -//! +//! //! ### 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}; diff --git a/esp-hal/src/rng.rs b/esp-hal/src/rng.rs index c79ee7489..8e2ac2802 100644 --- a/esp-hal/src/rng.rs +++ b/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;")] -#![cfg_attr(not(esp32), doc = "let analog_pin = peripherals.GPIO3;")] +//! # {analog_pin} //! let mut adc1_config = AdcConfig::new(); -//! let mut adc1_pin = adc1_config.enable_pin( -//! analog_pin, -//! Attenuation::_11dB -//! ); +//! let mut adc1_pin = adc1_config.enable_pin(analog_pin, Attenuation::_11dB); //! let mut adc1 = Adc::::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::{ diff --git a/esp-hal/src/rtc_cntl/mod.rs b/esp-hal/src/rtc_cntl/mod.rs index ed8de3652..6ee080d4b 100644 --- a/esp-hal/src/rtc_cntl/mod.rs +++ b/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 -//! * Calibration -//! * Low-Power Management -//! * Handling Watchdog Timers +//! * Clock Configuration +//! * Calibration +//! * Low-Power Management +//! * 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( -//! RwdtStage::Stage0, -//! Duration::from_millis(5000), -//! ); +//! rwdt.set_timeout(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( - /// rtc.current_time_us() as i64, - /// )?; + /// let now = Timestamp::from_microsecond(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 diff --git a/esp-hal/src/rtc_cntl/sleep/mod.rs b/esp-hal/src/rtc_cntl/sleep/mod.rs index 5ec7db6b9..1c46174a1 100644 --- a/esp-hal/src/rtc_cntl/sleep/mod.rs +++ b/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 Ext0WakeupSource

{ } } +#[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}; diff --git a/esp-hal/src/sha.rs b/esp-hal/src/sha.rs index 404926903..72198689d 100644 --- a/esp-hal/src/sha.rs +++ b/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. diff --git a/esp-hal/src/soc/esp32/cpu_control.rs b/esp-hal/src/soc/esp32/cpu_control.rs index 3d5d54253..f0af9f9ea 100644 --- a/esp-hal/src/soc/esp32/cpu_control.rs +++ b/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 -/// .start_app_core( -/// unsafe { &mut *addr_of_mut!(APP_CORE_STACK) }, -/// cpu1_fnctn -/// )?; +/// let _guard = +/// cpu_control.start_app_core(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( -/// delay: &Delay, -/// counter: &critical_section::Mutex>, -/// ) -> ! { +/// fn cpu1_task(delay: &Delay, counter: &critical_section::Mutex>) -> ! { /// loop { /// delay.delay(Duration::from_millis(500)); /// diff --git a/esp-hal/src/soc/esp32/efuse/mod.rs b/esp-hal/src/soc/esp32/efuse/mod.rs index a246419c4..92d48780f 100644 --- a/esp-hal/src/soc/esp32/efuse/mod.rs +++ b/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::*; diff --git a/esp-hal/src/soc/esp32/psram.rs b/esp-hal/src/soc/esp32/psram.rs index bbc6a633e..17b984f81 100644 --- a/esp-hal/src/soc/esp32/psram.rs +++ b/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, -//! psram::PsramConfig::default()); +//! let (start, size) = psram::init_psram(peripherals.PSRAM, psram::PsramConfig::default()); //! //! init_psram_heap(start, size); //! diff --git a/esp-hal/src/soc/esp32c2/efuse/mod.rs b/esp-hal/src/soc/esp32c2/efuse/mod.rs index ac1013ac3..377ab6d94 100644 --- a/esp-hal/src/soc/esp32c2/efuse/mod.rs +++ b/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::*; diff --git a/esp-hal/src/soc/esp32c3/efuse/mod.rs b/esp-hal/src/soc/esp32c3/efuse/mod.rs index 0baa0aaed..65996b5b3 100644 --- a/esp-hal/src/soc/esp32c3/efuse/mod.rs +++ b/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::*; diff --git a/esp-hal/src/soc/esp32c6/efuse/mod.rs b/esp-hal/src/soc/esp32c6/efuse/mod.rs index 3f7e6a3d7..4441a6a95 100644 --- a/esp-hal/src/soc/esp32c6/efuse/mod.rs +++ b/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::*; diff --git a/esp-hal/src/soc/esp32h2/efuse/mod.rs b/esp-hal/src/soc/esp32h2/efuse/mod.rs index 48494f10e..fab336849 100644 --- a/esp-hal/src/soc/esp32h2/efuse/mod.rs +++ b/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::*; diff --git a/esp-hal/src/soc/esp32s2/efuse/mod.rs b/esp-hal/src/soc/esp32s2/efuse/mod.rs index 8566c250f..12e5a0934 100644 --- a/esp-hal/src/soc/esp32s2/efuse/mod.rs +++ b/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::*; diff --git a/esp-hal/src/soc/esp32s2/psram.rs b/esp-hal/src/soc/esp32s2/psram.rs index 31c528a79..48b3a8654 100644 --- a/esp-hal/src/soc/esp32s2/psram.rs +++ b/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, -//! psram::PsramConfig::default()); +//! let (start, size) = psram::init_psram(peripherals.PSRAM, psram::PsramConfig::default()); //! //! init_psram_heap(start, size); //! diff --git a/esp-hal/src/soc/esp32s2/ulp_core.rs b/esp-hal/src/soc/esp32s2/ulp_core.rs index d1015e6e3..4a04dc795 100644 --- a/esp-hal/src/soc/esp32s2/ulp_core.rs +++ b/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, -//! 0x0c, 0xc1, 0xf5, 0xbf, 0x00, 0x00, 0x00, 0x00, +//! 0x17, 0x05, 0x00, 0x00, 0x13, 0x05, 0x05, 0x01, 0x81, 0x45, 0x85, 0x05, 0x0c, 0xc1, 0xf5, +//! 0xbf, 0x00, 0x00, 0x00, 0x00, //! ]; -//! let mut ulp_core = -//! esp_hal::ulp_core::UlpCore::new(peripherals.ULP_RISCV_CORE); +//! let mut ulp_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( -//! CODE as *const _ as *const u8, -//! lp_ram, -//! CODE.len(), -//! ); +//! core::ptr::copy_nonoverlapping(CODE as *const _ as *const u8, lp_ram, CODE.len()); //! } //! //! // start ULP core diff --git a/esp-hal/src/soc/esp32s3/cpu_control.rs b/esp-hal/src/soc/esp32s3/cpu_control.rs index 2be814ff3..3c59e7ef4 100644 --- a/esp-hal/src/soc/esp32s3/cpu_control.rs +++ b/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 -/// .start_app_core( -/// unsafe { &mut *addr_of_mut!(APP_CORE_STACK) }, -/// cpu1_fnctn -/// )?; +/// let _guard = +/// cpu_control.start_app_core(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( -/// delay: &Delay, -/// counter: &critical_section::Mutex>, -/// ) -> ! { +/// fn cpu1_task(delay: &Delay, counter: &critical_section::Mutex>) -> ! { /// loop { /// delay.delay(Duration::from_millis(500)); /// diff --git a/esp-hal/src/soc/esp32s3/efuse/mod.rs b/esp-hal/src/soc/esp32s3/efuse/mod.rs index 7d750edf6..24cbbbd47 100644 --- a/esp-hal/src/soc/esp32s3/efuse/mod.rs +++ b/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::*; diff --git a/esp-hal/src/soc/esp32s3/psram.rs b/esp-hal/src/soc/esp32s3/psram.rs index 080264b12..aec12a13a 100644 --- a/esp-hal/src/soc/esp32s3/psram.rs +++ b/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, -//! psram::PsramConfig::default()); +//! let (start, size) = psram::init_psram(peripherals.PSRAM, psram::PsramConfig::default()); //! //! init_psram_heap(start, size); //! diff --git a/esp-hal/src/soc/esp32s3/ulp_core.rs b/esp-hal/src/soc/esp32s3/ulp_core.rs index 7ef8ea30f..51c9c5f3d 100644 --- a/esp-hal/src/soc/esp32s3/ulp_core.rs +++ b/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, -//! 0x0c, 0xc1, 0xf5, 0xbf, 0x00, 0x00, 0x00, 0x00, +//! 0x17, 0x05, 0x00, 0x00, 0x13, 0x05, 0x05, 0x01, 0x81, 0x45, 0x85, 0x05, 0x0c, 0xc1, 0xf5, +//! 0xbf, 0x00, 0x00, 0x00, 0x00, //! ]; //! -//! let mut ulp_core = -//! esp_hal::ulp_core::UlpCore::new(peripherals.ULP_RISCV_CORE); +//! let mut ulp_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( -//! CODE as *const _ as *const u8, -//! lp_ram, -//! CODE.len(), -//! ); +//! core::ptr::copy_nonoverlapping(CODE as *const _ as *const u8, lp_ram, CODE.len()); //! } //! //! // start ULP core diff --git a/esp-hal/src/spi/slave.rs b/esp-hal/src/spi/slave.rs index 303e64f8e..4da732dec 100644 --- a/esp-hal/src/spi/slave.rs +++ b/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;")] -#![cfg_attr(gdma, doc = "let dma_channel = peripherals.DMA_CH0;")] +//! # {dma_channel} //! 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) = -//! dma_buffers!(32000); +//! let (rx_buffer, rx_descriptors, tx_buffer, tx_descriptors) = 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( -//! peripherals.SPI2, -//! Mode::_0, -//! ) -//! .with_sck(sclk) -//! .with_mosi(mosi) -//! .with_miso(miso) -//! .with_cs(cs) -//! .with_dma(dma_channel); +//! let mut spi = Spi::new(peripherals.SPI2, Mode::_0) +//! .with_sck(sclk) +//! .with_mosi(mosi) +//! .with_miso(miso) +//! .with_cs(cs) +//! .with_dma(dma_channel); //! -//! let transfer = spi -//! .transfer(50, dma_rx_buf, 50, dma_tx_buf)?; +//! let transfer = spi.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) -//! - Full duplex, single bit (not dual or quad SPI) -//! - DMA mode (not CPU mode). +//! - Single transfers (not segmented transfers) +//! - Full duplex, single bit (not dual or quad SPI) +//! - 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, diff --git a/esp-hal/src/timer/mod.rs b/esp-hal/src/timer/mod.rs index 9708dd4e3..a094e1a0b 100644 --- a/esp-hal/src/timer/mod.rs +++ b/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(); //! } //! # } //! ``` diff --git a/esp-hal/src/timer/systimer.rs b/esp-hal/src/timer/systimer.rs index 17e87343b..ffda80d9b 100644 --- a/esp-hal/src/timer/systimer.rs +++ b/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: - //! - SYSTIMER_EVT_CNT_CMPx: Indicates the alarm pulses generated by COMPx + //! The system timer can generate the following ETM events: + //! - 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, - //! &led_task); + //! let _configured_etm_channel = etm.channel0.setup(&timer_event, &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::*; diff --git a/esp-hal/src/timer/timg.rs b/esp-hal/src/timer/timg.rs index 825a26021..ff2502ea5 100644 --- a/esp-hal/src/timer/timg.rs +++ b/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!()] -//! use esp_hal::timer::timg::TimerGroup; -//! use esp_hal::timer::Timer; +//! # {before_snippet} +//! use esp_hal::timer::{Timer, timg::TimerGroup}; //! //! 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!()] -//! use esp_hal::timer::timg::TimerGroup; -//! use esp_hal::timer::timg::MwdtStage; -//! use esp_hal::timer::Timer; +//! # {before_snippet} +//! use esp_hal::timer::{ +//! Timer, +//! timg::{MwdtStage, TimerGroup}, +//! }; //! //! let timg0 = TimerGroup::new(peripherals.TIMG0); //! let mut wdt = timg0.wdt; diff --git a/esp-hal/src/touch.rs b/esp-hal/src/touch.rs index f8d7f511a..b723cb771 100644 --- a/esp-hal/src/touch.rs +++ b/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 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) -> 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) -> 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>, diff --git a/esp-hal/src/trace.rs b/esp-hal/src/trace.rs index 85ab5526f..811f3dcb4 100644 --- a/esp-hal/src/trace.rs +++ b/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}; diff --git a/esp-hal/src/tsens.rs b/esp-hal/src/tsens.rs index c7b7e1fcf..0a2eefe68 100644 --- a/esp-hal/src/tsens.rs +++ b/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( -//! peripherals.TSENS, -//! Config::default())?; +//! let temperature_sensor = TemperatureSensor::new(peripherals.TSENS, Config::default())?; //! let delay = Delay::new(); //! delay.delay_micros(200); //! loop { -//! let temp = temperature_sensor.get_temperature(); -//! println!("Temperature: {:.2}°C", temp.to_celcius()); -//! delay.delay_millis(1_000); +//! let temp = temperature_sensor.get_temperature(); +//! println!("Temperature: {:.2}°C", temp.to_celcius()); +//! delay.delay_millis(1_000); //! } //! # } //! ``` -//! +//! //! ## Implementation State //! //! - Temperature calibration range is not supported diff --git a/esp-hal/src/twai/filter.rs b/esp-hal/src/twai/filter.rs index d89559202..12bb8b0a3 100644 --- a/esp-hal/src/twai/filter.rs +++ b/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( - /// b"xxxxxxxxxx0", - /// b"x", - /// [b"xxxxxxxx", b"xxxxxxxx"] - /// ); - /// # Ok(()) - /// # } + /// SingleStandardFilter::new(b"xxxxxxxxxx0", b"x", [b"xxxxxxxx", b"xxxxxxxx"]); + /// # {after_snippet} /// ``` 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 diff --git a/esp-hal/src/twai/mod.rs b/esp-hal/src/twai/mod.rs index ac7b8bfb5..48c0135ab 100644 --- a/esp-hal/src/twai/mod.rs +++ b/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", -//! b"x", [b"xxxxxxxx", b"xxxxxxxx"]) }); +//! twai_config.set_filter( +//! 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; diff --git a/esp-hal/src/usb_serial_jtag.rs b/esp-hal/src/usb_serial_jtag.rs index 5351869de..14a501717 100644 --- a/esp-hal/src/usb_serial_jtag.rs +++ b/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| -//! USB_SERIAL.borrow_ref_mut(cs).replace(usb_serial)); +//! critical_section::with(|cs| 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: -//! Mutex>>> = -//! Mutex::new(RefCell::new(None)); +//! static USB_SERIAL: Mutex>>> = +//! 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/ diff --git a/xtask/src/semver_check.rs b/xtask/src/semver_check.rs index 77f53e771..439e5ba28 100644 --- a/xtask/src/semver_check.rs +++ b/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) }