Fixed attiny doctests

innermatrix · innermatrix · commit 08c20da71093 · 2025-03-09T17:44:03.000-04:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -123,6 +123,11 @@ jobs:
       - name: Test-compile HAL crate for an MCU
         if: "${{ matrix.m.type == 'mcu' }}"
         run: cd "mcu/${{ matrix.m.crate }}" && cargo build --features "${{ matrix.m.name }}" -Z build-std=core --target "../../avr-specs/avr-${{ matrix.m.spec }}.json"
+      - name: Compile doctests for an ATtiny MCU
+        if: "${{ matrix.m.crate == 'attiny-hal' }}"
+        run: >-
+          cd "mcu/${{ matrix.m.crate }}" && 
+          cargo test --doc --features "${{ matrix.m.name }}" -Z build-std=core --target "../../avr-specs/avr-${{ matrix.m.spec }}.json"
 
   ravedude:
     name: "ravedude"
diff --git a/mcu/attiny-hal/Cargo.toml b/mcu/attiny-hal/Cargo.toml
@@ -34,6 +34,10 @@ _peripheral-simple-pwm = []
 no-globals = []
 
 
+[dev-dependencies]
+ufmt = "0.2.0"
+embedded-hal = "1.0"
+
 [dependencies]
 avr-hal-generic = { path = "../../avr-hal-generic/" }
 
diff --git a/mcu/attiny-hal/src/impl/adc.rs b/mcu/attiny-hal/src/impl/adc.rs
@@ -17,28 +17,49 @@ macro_rules! impl_mod_adc {
         pub mod adc {
             //! Analog-to-Digital Converter
             //!
-            //! # Example
-            //!
             //! For full source code, please refer to the ATmega ADC example:
             //! [`atmega2560-adc.rs`](https://github.com/Rahix/avr-hal/blob/main/examples/atmega2560/src/bin/atmega2560-adc.rs)
             //!
+            //! # Example: Read pins using `analog_read()`
+            //!
+            //! ```no_run
+            #![doc = concat!("use attiny_hal::", stringify!($hal), " as hal;")]
+            //!
+            //! let dp = hal::Peripherals::take().unwrap();
+            //! let pins = hal::pins!(dp);
+            //!
+            //! type Clock = avr_hal_generic::clock::MHz16;
+            //! let mut adc = hal::Adc::<Clock>::new(dp.ADC, Default::default());
+            //! 
+            $(
+                #![doc = paste!{ concat!(
+                    "let ", stringify!([< input_ $pin_name:lower >]), " = pins.", stringify!([< $pin_name:lower >]), ".into_analog_input(&mut adc);\n",
+                    "let ", stringify!([< value_ $pin_name:lower >]), " = ", stringify!([< input_ $pin_name:lower >]), ".analog_read(&mut adc);\n\n"
+                )}]
+            )*
             //! ```
-            //! let dp = attiny_hal::Peripherals::take().unwrap();
-            //! let pins = attiny_hal::pins!(dp);
             //!
-            //! let mut adc = Adc::new(dp.ADC, Default::default());
+            //! # Example: Read channels (including pins) using `read_blocking()`
             //!
-            //! let channels: [attiny_hal::adc::Channel; 4] = [
-            //!     pins.pa0.into_analog_input(&mut adc).into_channel(),
-            //!     pins.pa1.into_analog_input(&mut adc).into_channel(),
-            //!     pins.pa2.into_analog_input(&mut adc).into_channel(),
-            //!     pins.pa3.into_analog_input(&mut adc).into_channel(),
-            //! ];
+            //! ```no_run
+            #![doc = concat!("use attiny_hal::", stringify!($hal), " as hal;")]
             //!
-            //! for (index, channel) in channels.iter().enumerate() {
-            //!     let value = adc.read_blocking(channel);
-            //!     ufmt::uwrite!(&mut serial, "CH{}: {} ", index, value).unwrap();
-            //! }
+            //! let dp = hal::Peripherals::take().unwrap();
+            //! let pins = hal::pins!(dp);
+            //!
+            //! type Clock = avr_hal_generic::clock::MHz16;
+            //! let mut adc = hal::Adc::<Clock>::new(dp.ADC, Default::default());
+            $(
+                #![doc = paste!{ concat!(
+                    "let ", stringify!([< channel_ $pin_name:lower >]), " = pins.", stringify!([< $pin_name:lower >]), ".into_analog_input(&mut adc).into_channel();\n",
+                    "let ", stringify!([< value_ $pin_name:lower >]), " = adc.read_blocking(&", stringify!([< channel_ $pin_name:lower >]), ");\n\n"
+                ) }]
+            )*
+            $(
+                #![doc = paste!{ concat!(
+                    "let ", stringify!([< value_ $channel_name:lower >]), " = adc.read_blocking(&hal::adc::channel::", stringify!([< $channel_name >]), ");\n\n"
+                ) }]
+            )*
             //! ```
 
             use avr_hal_generic::paste::paste;
@@ -61,14 +82,6 @@ macro_rules! impl_mod_adc {
             ///
             /// Some channels are not directly connected to pins.  This module provides types which can be used
             /// to access them.
-            /// 
-            /// # Example
-            /// ```
-            /// let dp = attiny_hal::Peripherals::take().unwrap();
-            /// let mut adc = attiny_hal::Adc::new(dp.ADC, Default::default());
-            ///
-            /// let value = adc.read_blocking(&channel::Vbg);
-            /// ```
             #[allow(non_camel_case_types)]
             pub mod channel {
                 $(
diff --git a/mcu/attiny-hal/src/impl/eeprom.rs b/mcu/attiny-hal/src/impl/eeprom.rs
@@ -13,17 +13,16 @@ macro_rules! impl_mod_eeprom {
             //! For full source code, please refer to the ATmega EEPROM example:
             //! [`atmega2560-eeprom.rs`](https://github.com/Rahix/avr-hal/blob/main/examples/atmega2560/src/bin/atmega2560-eeprom.rs)
             //!
-            //! ```
+            //! ```no_run
+            #![doc = concat!("use attiny_hal::", stringify!($hal), " as hal;")]
             //! const BOOT_COUNT_OFFSET: u16 = 0;
             //!
-            //! let dp = attiny_hal::Peripherals::take().unwrap();
-            //! let mut eeprom = Eeprom::new(dp.EEPROM);
+            //! let dp = hal::Peripherals::take().unwrap();
+            //! let mut eeprom = hal::Eeprom::new(dp.EEPROM);
             //!
             //! let mut boot_count = eeprom.read_byte(BOOT_COUNT_OFFSET);
             //! boot_count = boot_count.wrapping_add(1);
             //! eeprom.write_byte(BOOT_COUNT_OFFSET, boot_count);
-            //!
-            //! ufmt::uwriteln!(&mut serial, "Boot count: {}", boot_count).unwrap();
             //! ```
 
             pub use avr_hal_generic::eeprom::{EepromOps, OutOfBoundsError};
diff --git a/mcu/attiny-hal/src/impl/port.rs b/mcu/attiny-hal/src/impl/port.rs
@@ -16,15 +16,33 @@ macro_rules! impl_mod_port {
             //! For full source code, please refer to the ATmega port example:
             //! [`atmega2560-blink.rs`](https://github.com/Rahix/avr-hal/blob/main/examples/atmega2560/src/bin/atmega2560-blink.rs)
             //!
-            //! ```
-            //! let dp = attiny_hal::Peripherals::take().unwrap();
-            //! let pins = attiny_hal::pins!(dp);
+            //! ```no_run
+            //! use attiny_hal::prelude::*;
+            #![doc = concat!("use attiny_hal::", stringify!($hal), " as hal;")]
+            //!
+            //! type Clock = attiny_hal::clock::MHz8;
+            //! let mut delay = attiny_hal::delay::Delay::<Clock>::new();
+            //! 
+            //! let dp = hal::Peripherals::take().unwrap();
+            //! let pins = hal::pins!(dp);
             //!
-            //! let mut led = pins.pb2.into_output();
+            $(
+                $(
+                    #![doc = paste!{ concat!(
+                        "let mut ", stringify!([< led_p $name:lower $pin >]), " = pins.", stringify!([< p $name:lower $pin >]), ".into_output();",
+                    ) }]
+                )+
+            )+
             //!
             //! loop {
-            //!     led.toggle();
-            //!     delay_ms(1000);
+            $(
+                $(
+                    #![doc = paste!{ concat!(
+                        "    ", stringify!([< led_p $name:lower $pin >]), ".toggle();",
+                    ) }]
+                )+
+            )+
+            //!     delay.delay_ms(1000u16);
             //! }
             //! ```
 
diff --git a/mcu/attiny-hal/src/impl/simple_pwm.rs b/mcu/attiny-hal/src/impl/simple_pwm.rs
@@ -63,17 +63,25 @@ macro_rules! timer0_8bit_impl {
     ) => {
         paste! {
             avr_hal_generic::impl_simple_pwm! {
-                /// Use `$peripheral` for PWM (pins `$pin`,)
+                #[doc = concat!("Use `", stringify!($peripheral), "` for PWM.")]
                 ///
                 /// # Example
-                /// ```
-                /// let mut timer0 = Timer0Pwm::new(dp.$peripheral, Prescaler::Prescale64);
+                /// ```no_run
+                #[doc = concat!("use attiny_hal::", stringify!($hal), " as hal;")]
+                /// use hal::simple_pwm::{IntoPwmPin,Timer0Pwm,Prescaler};
                 ///
-                /// let mut d0 = pins.d0.into_output().into_pwm(&mut timer0);
-                /// let mut d1 = pins.d1.into_output().into_pwm(&mut timer0);
+                /// let dp = hal::Peripherals::take().unwrap();
+                /// let pins = hal::pins!(dp);
+                #[doc = concat!("let mut timer0 = ", stringify!($timer), "::new(dp.", stringify!($peripheral), ", Prescaler::Prescale64);")]
                 ///
-                /// d0.set_duty(128);
-                /// d0.enable();
+                $(
+                    #[doc = paste!{ concat!(
+                        "let mut ", stringify!([< $pin:lower >]), " = pins.", stringify!([< $pin:lower >]), ".into_output().into_pwm(&mut timer0);\n",
+                        stringify!([< $pin:lower >]), ".set_duty(128);\n",
+                        stringify!([< $pin:lower >]), ".enable();\n",
+                        "\n",
+                    ) }]
+                )+
                 /// ```
                 pub struct $timer {
                     timer: crate::$hal::pac::$peripheral,
@@ -125,16 +133,25 @@ macro_rules! timer1_8bit_separate_prescale {
     ) => {
         paste! {
             avr_hal_generic::impl_simple_pwm! {
-                /// Use `$peripheral` for PWM (pins `$pin`,)
+                #[doc = concat!("Use `", stringify!($peripheral), "` for PWM.")]
                 ///
                 /// # Example
-                /// ```
-                /// let mut timer1 = Timer1Pwm::new(dp.TC1, Prescaler::Prescale64);
+                /// ```no_run
+                #[doc = concat!("use attiny_hal::", stringify!($hal), " as hal;")]
+                /// use hal::simple_pwm::{IntoPwmPin,Timer1Pwm,Prescaler};
                 ///
-                /// let mut d4 = pins.d4.into_output().into_pwm(&mut timer1);
+                /// let dp = hal::Peripherals::take().unwrap();
+                /// let pins = hal::pins!(dp);
+                #[doc = concat!("let mut timer1 = ", stringify!($timer), "::new(dp.", stringify!($peripheral), ", Prescaler::Prescale64);")]
                 ///
-                /// d4.set_duty(128);
-                /// d4.enable();
+                $(
+                    #[doc = paste!{ concat!(
+                        "let mut ", stringify!([< $pin:lower >]), " = pins.", stringify!([< $pin:lower >]), ".into_output().into_pwm(&mut timer1);\n",
+                        stringify!([< $pin:lower >]), ".set_duty(128);\n",
+                        stringify!([< $pin:lower >]), ".enable();\n",
+                        "\n",
+                    ) }]
+                )+
                 /// ```
                 pub struct $timer {
                     timer: crate::$hal::pac::$peripheral,
@@ -187,16 +204,25 @@ macro_rules! timer1_16bit_impl {
     ) => {
         paste! {
             avr_hal_generic::impl_simple_pwm! {
-                /// Use `$peripheral` for PWM (pins `$pin`,)
+                #[doc = concat!("Use `", stringify!($peripheral), "` for PWM.")]
                 ///
                 /// # Example
-                /// ```
-                /// let mut timer1 = Timer1Pwm::new(dp.TC1, Prescaler::Prescale64);
+                /// ```no_run
+                #[doc = concat!("use attiny_hal::", stringify!($hal), " as hal;")]
+                /// use hal::simple_pwm::{IntoPwmPin,Timer1Pwm,Prescaler};
                 ///
-                /// let mut d4 = pins.d4.into_output().into_pwm(&mut timer1);
+                /// let dp = hal::Peripherals::take().unwrap();
+                /// let pins = hal::pins!(dp);
+                #[doc = concat!("let mut timer1 = ", stringify!($timer), "::new(dp.", stringify!($peripheral), ", Prescaler::Prescale64);")]
                 ///
-                /// d4.set_duty(128);
-                /// d4.enable();
+                $(
+                    #[doc = paste!{ concat!(
+                        "let mut ", stringify!([< $pin:lower >]), " = pins.", stringify!([< $pin:lower >]), ".into_output().into_pwm(&mut timer1);\n",
+                        stringify!([< $pin:lower >]), ".set_duty(128);\n",
+                        stringify!([< $pin:lower >]), ".enable();\n",
+                        "\n",
+                    ) }]
+                )+
                 /// ```
                 pub struct $timer {
                     timer: crate::$hal::pac::$peripheral,
diff --git a/mcu/attiny-hal/src/impl/spi.rs b/mcu/attiny-hal/src/impl/spi.rs
@@ -22,30 +22,38 @@ macro_rules! impl_mod_spi {
             //! For full source code, please refer to the ATmega SPI example:
             //! [`atmega2560-spi-feedback.rs`](https://github.com/Rahix/avr-hal/blob/main/examples/atmega2560/src/bin/atmega2560-spi-feedback.rs)
             //!
-            //! ```
-            //! let dp = attiny_hal::Peripherals::take().unwrap();
-            //! let pins = attiny_hal::pins!(dp);
+            //! ```no_run
+            #![doc = concat!("use attiny_hal::", stringify!($hal), " as hal;")]
             //!
-            //! let (mut spi, mut cs) = spi::Spi::new(
-            //!     dp.SPI,
-            //!     pins.pa4.into_output(),
-            //!     pins.pa6.into_output(),
-            //!     pins.pa5.into_pull_up_input(),
-            //!     pins.pa3.into_output(),
-            //!     spi::Settings::default(),
-            //! );
+            //! use embedded_hal::digital::OutputPin;
+            //! use embedded_hal::spi::SpiBus;
+            //! 
+            //! let dp = hal::Peripherals::take().unwrap();
+            //! let pins = hal::pins!(dp);
+            //!
+            $(
+                #![doc = paste!{ concat!(
+                    "let (mut spi, mut cs) = hal::spi::Spi::new(\n",
+                    "    dp.", stringify!($peripheral), ",\n",
+                    "    pins.", stringify!([< $sclk:lower >]), ".into_output(),\n",
+                    "    pins.", stringify!([< $mosi:lower >]), ".into_output(),\n",
+                    "    pins.", stringify!([< $miso:lower >]), ".into_pull_up_input(),\n",
+                    "    pins.", stringify!([< $cs:lower >]), ".into_output(),\n",
+                    "    hal::spi::Settings::default(),\n",
+                    ");\n",
+                ) }]
+            )+
             //!
             //! let data_out = b"Hello World!";
             //! let mut data_in = [0u8; 12];
             //!
             //! cs.set_low().unwrap();
             //! spi.transfer(&mut data_in, data_out).unwrap();
             //! cs.set_high().unwrap();
-            //!
-            //! ufmt::uwriteln!(&mut serial, "data: {:?}", data_in).unwrap();
             //! ```
 
             pub use avr_hal_generic::spi::*;
+            use avr_hal_generic::paste::paste;
             use crate::$hal as hal;
 
             $(
