Skip to content

Commit 08c20da

Browse files
innermatrixinnermatrix
committed
Fixed attiny doctests
1 parent 0dc06c4 commit 08c20da

File tree

7 files changed

+139
-66
lines changed

7 files changed

+139
-66
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,11 @@ jobs:
123123
- name: Test-compile HAL crate for an MCU
124124
if: "${{ matrix.m.type == 'mcu' }}"
125125
run: cd "mcu/${{ matrix.m.crate }}" && cargo build --features "${{ matrix.m.name }}" -Z build-std=core --target "../../avr-specs/avr-${{ matrix.m.spec }}.json"
126+
- name: Compile doctests for an ATtiny MCU
127+
if: "${{ matrix.m.crate == 'attiny-hal' }}"
128+
run: >-
129+
cd "mcu/${{ matrix.m.crate }}" &&
130+
cargo test --doc --features "${{ matrix.m.name }}" -Z build-std=core --target "../../avr-specs/avr-${{ matrix.m.spec }}.json"
126131
127132
ravedude:
128133
name: "ravedude"

‎mcu/attiny-hal/Cargo.toml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,10 @@ _peripheral-simple-pwm = []
3434
no-globals = []
3535

3636

37+
[dev-dependencies]
38+
ufmt = "0.2.0"
39+
embedded-hal = "1.0"
40+
3741
[dependencies]
3842
avr-hal-generic = { path = "../../avr-hal-generic/" }
3943

‎mcu/attiny-hal/src/impl/adc.rs‎

Lines changed: 36 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -17,28 +17,49 @@ macro_rules! impl_mod_adc {
1717
pub mod adc {
1818
//! Analog-to-Digital Converter
1919
//!
20-
//! # Example
21-
//!
2220
//! For full source code, please refer to the ATmega ADC example:
2321
//! [`atmega2560-adc.rs`](https://github.com/Rahix/avr-hal/blob/main/examples/atmega2560/src/bin/atmega2560-adc.rs)
2422
//!
23+
//! # Example: Read pins using `analog_read()`
24+
//!
25+
//! ```no_run
26+
#![doc = concat!("use attiny_hal::", stringify!($hal), " as hal;")]
27+
//!
28+
//! let dp = hal::Peripherals::take().unwrap();
29+
//! let pins = hal::pins!(dp);
30+
//!
31+
//! type Clock = avr_hal_generic::clock::MHz16;
32+
//! let mut adc = hal::Adc::<Clock>::new(dp.ADC, Default::default());
33+
//!
34+
$(
35+
#![doc = paste!{ concat!(
36+
"let ", stringify!([< input_ $pin_name:lower >]), " = pins.", stringify!([< $pin_name:lower >]), ".into_analog_input(&mut adc);\n",
37+
"let ", stringify!([< value_ $pin_name:lower >]), " = ", stringify!([< input_ $pin_name:lower >]), ".analog_read(&mut adc);\n\n"
38+
)}]
39+
)*
2540
//! ```
26-
//! let dp = attiny_hal::Peripherals::take().unwrap();
27-
//! let pins = attiny_hal::pins!(dp);
2841
//!
29-
//! let mut adc = Adc::new(dp.ADC, Default::default());
42+
//! # Example: Read channels (including pins) using `read_blocking()`
3043
//!
31-
//! let channels: [attiny_hal::adc::Channel; 4] = [
32-
//! pins.pa0.into_analog_input(&mut adc).into_channel(),
33-
//! pins.pa1.into_analog_input(&mut adc).into_channel(),
34-
//! pins.pa2.into_analog_input(&mut adc).into_channel(),
35-
//! pins.pa3.into_analog_input(&mut adc).into_channel(),
36-
//! ];
44+
//! ```no_run
45+
#![doc = concat!("use attiny_hal::", stringify!($hal), " as hal;")]
3746
//!
38-
//! for (index, channel) in channels.iter().enumerate() {
39-
//! let value = adc.read_blocking(channel);
40-
//! ufmt::uwrite!(&mut serial, "CH{}: {} ", index, value).unwrap();
41-
//! }
47+
//! let dp = hal::Peripherals::take().unwrap();
48+
//! let pins = hal::pins!(dp);
49+
//!
50+
//! type Clock = avr_hal_generic::clock::MHz16;
51+
//! let mut adc = hal::Adc::<Clock>::new(dp.ADC, Default::default());
52+
$(
53+
#![doc = paste!{ concat!(
54+
"let ", stringify!([< channel_ $pin_name:lower >]), " = pins.", stringify!([< $pin_name:lower >]), ".into_analog_input(&mut adc).into_channel();\n",
55+
"let ", stringify!([< value_ $pin_name:lower >]), " = adc.read_blocking(&", stringify!([< channel_ $pin_name:lower >]), ");\n\n"
56+
) }]
57+
)*
58+
$(
59+
#![doc = paste!{ concat!(
60+
"let ", stringify!([< value_ $channel_name:lower >]), " = adc.read_blocking(&hal::adc::channel::", stringify!([< $channel_name >]), ");\n\n"
61+
) }]
62+
)*
4263
//! ```
4364
4465
use avr_hal_generic::paste::paste;
@@ -61,14 +82,6 @@ macro_rules! impl_mod_adc {
6182
///
6283
/// Some channels are not directly connected to pins. This module provides types which can be used
6384
/// to access them.
64-
///
65-
/// # Example
66-
/// ```
67-
/// let dp = attiny_hal::Peripherals::take().unwrap();
68-
/// let mut adc = attiny_hal::Adc::new(dp.ADC, Default::default());
69-
///
70-
/// let value = adc.read_blocking(&channel::Vbg);
71-
/// ```
7285
#[allow(non_camel_case_types)]
7386
pub mod channel {
7487
$(

‎mcu/attiny-hal/src/impl/eeprom.rs‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,17 +13,16 @@ macro_rules! impl_mod_eeprom {
1313
//! For full source code, please refer to the ATmega EEPROM example:
1414
//! [`atmega2560-eeprom.rs`](https://github.com/Rahix/avr-hal/blob/main/examples/atmega2560/src/bin/atmega2560-eeprom.rs)
1515
//!
16-
//! ```
16+
//! ```no_run
17+
#![doc = concat!("use attiny_hal::", stringify!($hal), " as hal;")]
1718
//! const BOOT_COUNT_OFFSET: u16 = 0;
1819
//!
19-
//! let dp = attiny_hal::Peripherals::take().unwrap();
20-
//! let mut eeprom = Eeprom::new(dp.EEPROM);
20+
//! let dp = hal::Peripherals::take().unwrap();
21+
//! let mut eeprom = hal::Eeprom::new(dp.EEPROM);
2122
//!
2223
//! let mut boot_count = eeprom.read_byte(BOOT_COUNT_OFFSET);
2324
//! boot_count = boot_count.wrapping_add(1);
2425
//! eeprom.write_byte(BOOT_COUNT_OFFSET, boot_count);
25-
//!
26-
//! ufmt::uwriteln!(&mut serial, "Boot count: {}", boot_count).unwrap();
2726
//! ```
2827
2928
pub use avr_hal_generic::eeprom::{EepromOps, OutOfBoundsError};

‎mcu/attiny-hal/src/impl/port.rs‎

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,15 +16,33 @@ macro_rules! impl_mod_port {
1616
//! For full source code, please refer to the ATmega port example:
1717
//! [`atmega2560-blink.rs`](https://github.com/Rahix/avr-hal/blob/main/examples/atmega2560/src/bin/atmega2560-blink.rs)
1818
//!
19-
//! ```
20-
//! let dp = attiny_hal::Peripherals::take().unwrap();
21-
//! let pins = attiny_hal::pins!(dp);
19+
//! ```no_run
20+
//! use attiny_hal::prelude::*;
21+
#![doc = concat!("use attiny_hal::", stringify!($hal), " as hal;")]
22+
//!
23+
//! type Clock = attiny_hal::clock::MHz8;
24+
//! let mut delay = attiny_hal::delay::Delay::<Clock>::new();
25+
//!
26+
//! let dp = hal::Peripherals::take().unwrap();
27+
//! let pins = hal::pins!(dp);
2228
//!
23-
//! let mut led = pins.pb2.into_output();
29+
$(
30+
$(
31+
#![doc = paste!{ concat!(
32+
"let mut ", stringify!([< led_p $name:lower $pin >]), " = pins.", stringify!([< p $name:lower $pin >]), ".into_output();",
33+
) }]
34+
)+
35+
)+
2436
//!
2537
//! loop {
26-
//! led.toggle();
27-
//! delay_ms(1000);
38+
$(
39+
$(
40+
#![doc = paste!{ concat!(
41+
" ", stringify!([< led_p $name:lower $pin >]), ".toggle();",
42+
) }]
43+
)+
44+
)+
45+
//! delay.delay_ms(1000u16);
2846
//! }
2947
//! ```
3048

‎mcu/attiny-hal/src/impl/simple_pwm.rs‎

Lines changed: 45 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -63,17 +63,25 @@ macro_rules! timer0_8bit_impl {
6363
) => {
6464
paste! {
6565
avr_hal_generic::impl_simple_pwm! {
66-
/// Use `$peripheral` for PWM (pins `$pin`,)
66+
#[doc = concat!("Use `", stringify!($peripheral), "` for PWM.")]
6767
///
6868
/// # Example
69-
/// ```
70-
/// let mut timer0 = Timer0Pwm::new(dp.$peripheral, Prescaler::Prescale64);
69+
/// ```no_run
70+
#[doc = concat!("use attiny_hal::", stringify!($hal), " as hal;")]
71+
/// use hal::simple_pwm::{IntoPwmPin,Timer0Pwm,Prescaler};
7172
///
72-
/// let mut d0 = pins.d0.into_output().into_pwm(&mut timer0);
73-
/// let mut d1 = pins.d1.into_output().into_pwm(&mut timer0);
73+
/// let dp = hal::Peripherals::take().unwrap();
74+
/// let pins = hal::pins!(dp);
75+
#[doc = concat!("let mut timer0 = ", stringify!($timer), "::new(dp.", stringify!($peripheral), ", Prescaler::Prescale64);")]
7476
///
75-
/// d0.set_duty(128);
76-
/// d0.enable();
77+
$(
78+
#[doc = paste!{ concat!(
79+
"let mut ", stringify!([< $pin:lower >]), " = pins.", stringify!([< $pin:lower >]), ".into_output().into_pwm(&mut timer0);\n",
80+
stringify!([< $pin:lower >]), ".set_duty(128);\n",
81+
stringify!([< $pin:lower >]), ".enable();\n",
82+
"\n",
83+
) }]
84+
)+
7785
/// ```
7886
pub struct $timer {
7987
timer: crate::$hal::pac::$peripheral,
@@ -125,16 +133,25 @@ macro_rules! timer1_8bit_separate_prescale {
125133
) => {
126134
paste! {
127135
avr_hal_generic::impl_simple_pwm! {
128-
/// Use `$peripheral` for PWM (pins `$pin`,)
136+
#[doc = concat!("Use `", stringify!($peripheral), "` for PWM.")]
129137
///
130138
/// # Example
131-
/// ```
132-
/// let mut timer1 = Timer1Pwm::new(dp.TC1, Prescaler::Prescale64);
139+
/// ```no_run
140+
#[doc = concat!("use attiny_hal::", stringify!($hal), " as hal;")]
141+
/// use hal::simple_pwm::{IntoPwmPin,Timer1Pwm,Prescaler};
133142
///
134-
/// let mut d4 = pins.d4.into_output().into_pwm(&mut timer1);
143+
/// let dp = hal::Peripherals::take().unwrap();
144+
/// let pins = hal::pins!(dp);
145+
#[doc = concat!("let mut timer1 = ", stringify!($timer), "::new(dp.", stringify!($peripheral), ", Prescaler::Prescale64);")]
135146
///
136-
/// d4.set_duty(128);
137-
/// d4.enable();
147+
$(
148+
#[doc = paste!{ concat!(
149+
"let mut ", stringify!([< $pin:lower >]), " = pins.", stringify!([< $pin:lower >]), ".into_output().into_pwm(&mut timer1);\n",
150+
stringify!([< $pin:lower >]), ".set_duty(128);\n",
151+
stringify!([< $pin:lower >]), ".enable();\n",
152+
"\n",
153+
) }]
154+
)+
138155
/// ```
139156
pub struct $timer {
140157
timer: crate::$hal::pac::$peripheral,
@@ -187,16 +204,25 @@ macro_rules! timer1_16bit_impl {
187204
) => {
188205
paste! {
189206
avr_hal_generic::impl_simple_pwm! {
190-
/// Use `$peripheral` for PWM (pins `$pin`,)
207+
#[doc = concat!("Use `", stringify!($peripheral), "` for PWM.")]
191208
///
192209
/// # Example
193-
/// ```
194-
/// let mut timer1 = Timer1Pwm::new(dp.TC1, Prescaler::Prescale64);
210+
/// ```no_run
211+
#[doc = concat!("use attiny_hal::", stringify!($hal), " as hal;")]
212+
/// use hal::simple_pwm::{IntoPwmPin,Timer1Pwm,Prescaler};
195213
///
196-
/// let mut d4 = pins.d4.into_output().into_pwm(&mut timer1);
214+
/// let dp = hal::Peripherals::take().unwrap();
215+
/// let pins = hal::pins!(dp);
216+
#[doc = concat!("let mut timer1 = ", stringify!($timer), "::new(dp.", stringify!($peripheral), ", Prescaler::Prescale64);")]
197217
///
198-
/// d4.set_duty(128);
199-
/// d4.enable();
218+
$(
219+
#[doc = paste!{ concat!(
220+
"let mut ", stringify!([< $pin:lower >]), " = pins.", stringify!([< $pin:lower >]), ".into_output().into_pwm(&mut timer1);\n",
221+
stringify!([< $pin:lower >]), ".set_duty(128);\n",
222+
stringify!([< $pin:lower >]), ".enable();\n",
223+
"\n",
224+
) }]
225+
)+
200226
/// ```
201227
pub struct $timer {
202228
timer: crate::$hal::pac::$peripheral,

‎mcu/attiny-hal/src/impl/spi.rs‎

Lines changed: 21 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -22,30 +22,38 @@ macro_rules! impl_mod_spi {
2222
//! For full source code, please refer to the ATmega SPI example:
2323
//! [`atmega2560-spi-feedback.rs`](https://github.com/Rahix/avr-hal/blob/main/examples/atmega2560/src/bin/atmega2560-spi-feedback.rs)
2424
//!
25-
//! ```
26-
//! let dp = attiny_hal::Peripherals::take().unwrap();
27-
//! let pins = attiny_hal::pins!(dp);
25+
//! ```no_run
26+
#![doc = concat!("use attiny_hal::", stringify!($hal), " as hal;")]
2827
//!
29-
//! let (mut spi, mut cs) = spi::Spi::new(
30-
//! dp.SPI,
31-
//! pins.pa4.into_output(),
32-
//! pins.pa6.into_output(),
33-
//! pins.pa5.into_pull_up_input(),
34-
//! pins.pa3.into_output(),
35-
//! spi::Settings::default(),
36-
//! );
28+
//! use embedded_hal::digital::OutputPin;
29+
//! use embedded_hal::spi::SpiBus;
30+
//!
31+
//! let dp = hal::Peripherals::take().unwrap();
32+
//! let pins = hal::pins!(dp);
33+
//!
34+
$(
35+
#![doc = paste!{ concat!(
36+
"let (mut spi, mut cs) = hal::spi::Spi::new(\n",
37+
" dp.", stringify!($peripheral), ",\n",
38+
" pins.", stringify!([< $sclk:lower >]), ".into_output(),\n",
39+
" pins.", stringify!([< $mosi:lower >]), ".into_output(),\n",
40+
" pins.", stringify!([< $miso:lower >]), ".into_pull_up_input(),\n",
41+
" pins.", stringify!([< $cs:lower >]), ".into_output(),\n",
42+
" hal::spi::Settings::default(),\n",
43+
");\n",
44+
) }]
45+
)+
3746
//!
3847
//! let data_out = b"Hello World!";
3948
//! let mut data_in = [0u8; 12];
4049
//!
4150
//! cs.set_low().unwrap();
4251
//! spi.transfer(&mut data_in, data_out).unwrap();
4352
//! cs.set_high().unwrap();
44-
//!
45-
//! ufmt::uwriteln!(&mut serial, "data: {:?}", data_in).unwrap();
4653
//! ```
4754
4855
pub use avr_hal_generic::spi::*;
56+
use avr_hal_generic::paste::paste;
4957
use crate::$hal as hal;
5058

5159
$(

0 commit comments

Comments
 (0)