Update some doctests

Author: bugadani

documentation/API-GUIDELINES.md

@@ -77,7 +77,7 @@ Modules should have the following documentation format:
 //! ```
 //!
 //! ## Implementation State
-//! List unsuported features
+//! List unsupported features
 ```
 - If any of the headers is empty, remove it
 - When possible, use ESP-IDF docs and TRM as references and include links if possible.

esp-hal/doc-helper/before

@@ -1,12 +1,10 @@
 # #![no_std]
-# use esp_hal::peripherals::Peripherals;
-# use esp_hal::clock::ClockControl;
-# use esp_hal::system::SystemControl;
+# use esp_hal::prelude::*;
+# use procmacros::handler;
+# use esp_hal::interrupt;
 # #[panic_handler]
 # fn panic(_ : &core::panic::PanicInfo) -> ! {
 #     loop {}
 # }
+# #[allow(unused_variables)]
 # fn main() {
-#   let peripherals = Peripherals::take();
-#   let system = SystemControl::new(peripherals.SYSTEM);
-#   let mut clocks = ClockControl::boot_defaults(system.clock_control).freeze();

esp-hal/src/delay.rs

@@ -1,16 +1,18 @@
 //! # Delay
 //!
 //! ## Overview
+//!
 //! The Delay driver provides blocking delay functionalities using the
-//! `SYSTIMER` peripheral for RISC-V devices and the built-in Xtensa timer for
-//! Xtensa devices.
+//! [current_time] function.
 //!
 //! ## Configuration
+//!
 //! The delays are implemented in a "best-effort" way, meaning that the CPU will
 //! block for at least the amount of time specified, but accuracy can be
 //! affected by many factors, including interrupt usage.
 //!
 //! ## Usage
+//!
 //! This module implements the blocking [DelayMs] and [DelayUs] traits from
 //! [embedded-hal], both 0.2.x and 1.x.x.
 //!
@@ -20,7 +22,9 @@
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::delay::Delay;
 //! # use embedded_hal::delay::DelayNs;
-//! let mut delay = Delay::new(&clocks);
+//! let system = esp_hal::init(CpuClock::boot_default());
+//!
+//! let mut delay = Delay::new(&system.clocks);
 //!
 //! delay.delay_ms(1000 as u32);
 //! # }

esp-hal/src/dma/mod.rs

@@ -1,6 +1,7 @@
 //! # Direct Memory Access (DMA)
 //!
 //! ## Overview
+//!
 //! The DMA driver provides an interface to efficiently transfer data between
 //! different memory regions and peripherals within the ESP microcontroller
 //! without involving the CPU. The DMA controller is responsible for managing
@@ -10,25 +11,32 @@
 //! `ESP32-S2` are using older `PDMA` controller, whenever other chips are using
 //! newer `GDMA` controller.
 //!
-//! ## Examples
-//! ### Initialize and Utilize DMA Controller in `SPI`
+//! ## Example
+//!
+//! ### Initialize and utilize DMA controller in `SPI`
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::dma_buffers;
 //! # use esp_hal::gpio::Io;
 //! # use esp_hal::spi::{master::{Spi, prelude::*}, SpiMode};
 //! # use esp_hal::dma::{Dma, DmaPriority};
-//! # use crate::esp_hal::prelude::_fugit_RateExtU32;
-//! let dma = Dma::new(peripherals.DMA);
+//! let system = esp_hal::init(CpuClock::boot_default());
+//! let dma = Dma::new(system.peripherals.DMA);
 #![cfg_attr(any(esp32, esp32s2), doc = "let dma_channel = dma.spi2channel;")]
 #![cfg_attr(not(any(esp32, esp32s2)), doc = "let dma_channel = dma.channel0;")]
-//! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
+//! let io = Io::new(system.peripherals.GPIO, system.peripherals.IO_MUX);
 //! let sclk = io.pins.gpio0;
 //! let miso = io.pins.gpio2;
 //! let mosi = io.pins.gpio4;
 //! let cs = io.pins.gpio5;
 //!
-//! let mut spi = Spi::new(peripherals.SPI2, 100.kHz(), SpiMode::Mode0, &clocks)
+//! let mut spi = Spi::new(
+//!     system.peripherals.SPI2,
+//!     100.kHz(),
+//!     SpiMode::Mode0,
+//!     &system.clocks
+//! )
 //! .with_pins(Some(sclk), Some(mosi), Some(miso), Some(cs))
 //! .with_dma(dma_channel.configure(
 //!     false,
@@ -40,10 +48,10 @@
 //! ⚠️ 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.
 //!
-//! ⚠️ Note: For chips that support DMA to/from PSRAM (esp32s3) DMA transfers to/from PSRAM
+//! ⚠️ Note: For chips that support DMA to/from PSRAM (ESP32-S3) DMA transfers to/from PSRAM
 //! have extra alignment requirements. The address and size of the buffer pointed to by
 //! each descriptor must be a multiple of the cache line (block) size. This is 32 bytes
-//! on esp32s3.
+//! on ESP32-S3.
 //!
 //! For convenience you can use the [crate::dma_buffers] macro.
 

esp-hal/src/i2s.rs

@@ -1,14 +1,15 @@
 //! # Inter-IC Sound (I2S)
 //!
 //! ## Overview
+//!
 //! I2S (Inter-IC Sound) is a synchronous serial communication protocol usually
 //! used for transmitting audio data between two digital audio devices.
 //! Espressif devices may contain more than one I2S peripheral(s). These
 //! peripherals can be configured to input and output sample data via the I2S
 //! driver.
 //!
-//!
 //! ## Configuration
+//!
 //! I2S supports different data formats, including varying data and channel
 //! widths, different standards, such as the Philips standard and configurable
 //! pin mappings for I2S clock (BCLK), word select (WS), and data input/output
@@ -18,33 +19,33 @@
 //! supports various configurations, such as different data formats, standards
 //! (e.g., Philips) and pin configurations. It relies on other peripheral
 //! modules, such as
-//!     - `GPIO`
-//!     - `DMA`
-//!     - `system` (to configure and enable the I2S peripheral)
+//!   - `GPIO`
+//!   - `DMA`
+//!   - `system` (to configure and enable the I2S peripheral)
+//!
+//! ## Example
 //!
-//! ## Examples
 //! ### Initialization
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::i2s::I2s;
 //! # use esp_hal::i2s::Standard;
 //! # use esp_hal::i2s::DataFormat;
+//! # use esp_hal::i2s::I2sReadDma;
 //! # use esp_hal::gpio::Io;
 //! # use esp_hal::dma_buffers;
 //! # use esp_hal::dma::{Dma, DmaPriority};
-//! # use crate::esp_hal::prelude::_fugit_RateExtU32;
-//! # use crate::esp_hal::peripherals::Peripherals;
-//! # use crate::esp_hal::i2s::I2sReadDma;
-//! # use core::ptr::addr_of_mut;
-//! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
-//! let dma = Dma::new(peripherals.DMA);
+//! let system = esp_hal::init(CpuClock::boot_default());
+//! # let io = Io::new(system.peripherals.GPIO, system.peripherals.IO_MUX);
+//! let dma = Dma::new(system.peripherals.DMA);
 #![cfg_attr(any(esp32, esp32s2), doc = "let dma_channel = dma.i2s0channel;")]
 #![cfg_attr(not(any(esp32, esp32s2)), doc = "let dma_channel = dma.channel0;")]
 //! let (_, tx_descriptors, mut rx_buffer, rx_descriptors) =
 //! dma_buffers!(0, 4 * 4092);
 //!
 //! let i2s = I2s::new(
-//!     peripherals.I2S0,
+//!     system.peripherals.I2S0,
 //!     Standard::Philips,
 //!     DataFormat::Data16Channel16,
 //!     44100.Hz(),
@@ -54,7 +55,7 @@
 //!     ),
 //!     tx_descriptors,
 //!     rx_descriptors,
-//!     &clocks,
+//!     &system.clocks,
 //! );
 #![cfg_attr(not(esp32), doc = "let i2s = i2s.with_mclk(io.pins.gpio0);")]
 //! let mut i2s_rx = i2s.i2s_rx

esp-hal/src/interrupt/mod.rs

@@ -24,23 +24,23 @@
 //! We reserve a number of CPU interrupts, which cannot be used; see
 //! [`RESERVED_INTERRUPTS`].
 //!
-//! ## Examples
-//! ### Using the Peripheral Driver to Register an Interrupt Handler
+//! ## Example
+//!
+//! ### Using the peripheral driver to register an interrupt handler
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use core::cell::RefCell;
-//!
+//! #
 //! # use critical_section::Mutex;
 //! # use esp_hal::{
 //! #    prelude::*,
 //! #    system::{SoftwareInterrupt, SystemControl},
 //! # };
 //! # use esp_hal::interrupt::Priority;
 //! # use esp_hal::interrupt::InterruptHandler;
-//!
-//! static SWINT0: Mutex<RefCell<Option<SoftwareInterrupt<0>>>> =
-//! Mutex::new(RefCell::new(None));
-//!
+//! #
+//! let system = esp_hal::init(CpuClock::boot_default());
 //! let mut sw_int = system.software_interrupt_control;
 //!     critical_section::with(|cs| {
 //!         sw_int
@@ -56,15 +56,15 @@
 //!     });
 //!
 //!     loop {}
-//! }
+//! # }
 //!
-//! # use procmacros::handler;
-//! # use esp_hal::interrupt;
 //! # use critical_section::Mutex;
 //! # use core::cell::RefCell;
 //! # use esp_hal::system::SoftwareInterrupt;
-//! # static SWINT0: Mutex<RefCell<Option<SoftwareInterrupt<0>>>> = Mutex::new(RefCell::new(None));
-//! #[handler(priority = esp_hal::interrupt::Priority::Priority1)]
+//! static SWINT0: Mutex<RefCell<Option<SoftwareInterrupt<0>>>> =
+//!     Mutex::new(RefCell::new(None));
+//!
+//! #[handler(priority = Priority::Priority1)]
 //! fn swint0_handler() {
 //!     // esp_println::println!("SW interrupt0");
 //!     critical_section::with(|cs| {

esp-hal/src/lcd_cam/cam.rs

@@ -21,9 +21,10 @@
 //! # use fugit::RateExtU32;
 //! # use esp_hal::dma_buffers;
 //! # use esp_hal::dma::{Dma, DmaPriority};
-//! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
+//! let system = esp_hal::init(CpuClock::boot_default());
+//! # let io = Io::new(system.peripherals.GPIO, system.peripherals.IO_MUX);
 //!
-//! # let dma = Dma::new(peripherals.DMA);
+//! # let dma = Dma::new(system.peripherals.DMA);
 //! # let channel = dma.channel0;
 //!
 //! # let (tx_buffer, tx_descriptors, _, rx_descriptors) = dma_buffers!(32678, 0);
@@ -48,14 +49,14 @@
 //!     io.pins.gpio16,
 //! );
 //!
-//! let lcd_cam = LcdCam::new(peripherals.LCD_CAM);
+//! let lcd_cam = LcdCam::new(system.peripherals.LCD_CAM);
 //! let mut camera = Camera::new(
 //!     lcd_cam.cam,
 //!     channel.rx,
 //!     rx_descriptors,
 //!     data_pins,
 //!     20u32.MHz(),
-//!     &clocks
+//!     &system.clocks
 //! )
 //! // Remove this for slave mode.
 //! .with_master_clock(mclk_pin)

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

@@ -1,13 +1,16 @@
 //! # LCD - I8080/MOTO6800 Mode.
 //!
 //! ## Overview
+//!
 //! The LCD_CAM peripheral I8080 driver provides support for the I8080
-//! format/timing. The driver mandates DMA for DMA (Direct Memory Access) for
+//! format/timing. The driver mandates DMA (Direct Memory Access) for
 //! efficient data transfer.
 //!
-//! ## Examples
+//! ## Example
+//!
 //! ### MIPI-DSI Display
-//! Following code show how to send a command to a MIPI-DSI display over I8080
+//!
+//! The following example shows how to send a command to a MIPI-DSI display over the I8080
 //! protocol.
 //!
 //! ```rust, no_run
@@ -16,11 +19,11 @@
 //! # use esp_hal::lcd_cam::{LcdCam, lcd::i8080::{Config, I8080, TxEightBits}};
 //! # use esp_hal::dma_buffers;
 //! # use esp_hal::dma::{Dma, DmaPriority};
-//! # use fugit::RateExtU32;
 //!
-//! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
+//! let system = esp_hal::init(CpuClock::boot_default());
+//! # let io = Io::new(system.peripherals.GPIO, system.peripherals.IO_MUX);
 //!
-//! # let dma = Dma::new(peripherals.DMA);
+//! # let dma = Dma::new(system.peripherals.DMA);
 //! # let channel = dma.channel0;
 //!
 //! # let (tx_buffer, tx_descriptors, _, rx_descriptors) = dma_buffers!(32678, 0);
@@ -40,7 +43,7 @@
 //!     io.pins.gpio16,
 //!     io.pins.gpio15,
 //! );
-//! let lcd_cam = LcdCam::new(peripherals.LCD_CAM);
+//! let lcd_cam = LcdCam::new(system.peripherals.LCD_CAM);
 //!
 //! let mut i8080 = I8080::new(
 //!     lcd_cam.lcd,
@@ -49,7 +52,7 @@
 //!     tx_pins,
 //!     20.MHz(),
 //!     Config::default(),
-//!     &clocks,
+//!     &system.clocks,
 //! )
 //! .with_ctrl_pins(io.pins.gpio0, io.pins.gpio47);
 //!

esp-hal/src/ledc/mod.rs

@@ -1,6 +1,7 @@
 //! # LED Controller (LEDC)
 //!
 //! ## Overview
+//!
 //! The LEDC peripheral is primarily designed to control the intensity of LEDs,
 //! although it can also be used to generate PWM signals for other purposes. It
 //! has multiple channels which can generate independent waveforms that can be
@@ -15,9 +16,12 @@
 //! supported chips.
 //!
 //! ## Examples
+//!
 //! ### Low Speed Channel
-//! The following will configure the Low Speed Channel0 to 24kHz output with
-//! 10% duty using the ABPClock
+//!
+//! The following example will configure the Low Speed Channel0 to 24kHz output
+//! with 10% duty using the ABPClock.
+//!
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::ledc::Ledc;
@@ -26,14 +30,12 @@
 //! # use esp_hal::ledc::LowSpeed;
 //! # use esp_hal::ledc::channel;
 //! # use esp_hal::gpio::Io;
-//! # use crate::esp_hal::prelude::_esp_hal_ledc_timer_TimerIFace;
-//! # use crate::esp_hal::prelude::_fugit_RateExtU32;
-//! # use crate::esp_hal::prelude::_esp_hal_ledc_channel_ChannelIFace;
 //!
-//! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
+//! let system = esp_hal::init(CpuClock::boot_default());
+//! # let io = Io::new(system.peripherals.GPIO, system.peripherals.IO_MUX);
 //! # let led = io.pins.gpio0;
 //!
-//! let mut ledc = Ledc::new(peripherals.LEDC, &clocks);
+//! let mut ledc = Ledc::new(system.peripherals.LEDC, &system.clocks);
 //! ledc.set_global_slow_clock(LSGlobalClkSource::APBClk);
 //!
 //! let mut lstimer0 = ledc.get_timer::<LowSpeed>(timer::Number::Timer0);