refactor: enforce max 8 code lines, add docstrings, fix warnings across all Rust and C SDK projects

Rust (all 15 projects):
- Refactored overlength functions: format_counter, format_u8, format_f32_1,
  format_u32_minimal, gpio_drive, read_sensor, poll_sensor, format_round_trip,
  format_u32, prepare_write_buf, write_min_digits, write_temp, UartDriver::init,
  init_spi, angle_to_pulse_us, compute_servo_level
- Added 200+ docstrings to test functions, mock structs, impl blocks
- Fixed pub static comments (//) to doc comments (///) in all main.rs files
- Fixed helper function ordering (helpers above callers)
- Fixed Fn(u32) -> FnMut(u32) bound in button poll_button
- Moved OneShot trait import from main.rs to board.rs in adc project
- Added unsafe {} blocks in flash unsafe fn bodies (Rust 2024 edition)
- Removed unused hal::Clock imports from pwm/servo main.rs
- All 15 projects build with zero errors and zero warnings

C Pico SDK (all 15 projects):
- Added docstrings to all public functions, macros, and static variables
- All 15 projects rebuilt with zero errors

Cleanup:
- Removed build/ and target/ directories from git tracking
- Added target/ to .gitignore
- Deleted temporary fix_rust_docs.py script

drivers/0x0a_ir_rust/src/board.rs

@@ -37,10 +37,10 @@ use hal::gpio::{FunctionNull, FunctionUart, Pin, PullDown, PullNone};
 use hal::uart::{DataBits, Enabled, StopBits, UartConfig, UartPeripheral};
 
 // Alias our HAL crate
-#[cfg(rp2350)]
-use rp235x_hal as hal;
 #[cfg(rp2040)]
 use rp2040_hal as hal;
+#[cfg(rp2350)]
+use rp235x_hal as hal;
 
 /// Timer device type for the HAL timer peripheral.
 #[cfg(rp2350)]
@@ -86,7 +86,13 @@ pub(crate) fn init_clocks(
     watchdog: &mut hal::Watchdog,
 ) -> hal::clocks::ClocksManager {
     hal::clocks::init_clocks_and_plls(
-        XTAL_FREQ_HZ, xosc, clocks, pll_sys, pll_usb, resets, watchdog,
+        XTAL_FREQ_HZ,
+        xosc,
+        clocks,
+        pll_sys,
+        pll_usb,
+        resets,
+        watchdog,
     )
     .unwrap()
 }
@@ -148,34 +154,49 @@ fn wait_for_level(timer: &HalTimer, level: bool, timeout_us: u32) -> Option<i64>
     Some(time_us_32(timer).wrapping_sub(start) as i64)
 }
 
+/// Wait for the IR receiver to go idle (LOW).
+fn wait_for_idle(timer: &HalTimer) -> bool {
+    wait_for_level(timer, false, ir::LEADER_START_TIMEOUT_US).is_some()
+}
+
+/// Validate the NEC leader mark pulse width.
+fn validate_leader_mark(timer: &HalTimer) -> bool {
+    let Some(w) = wait_for_level(timer, true, ir::LEADER_MARK_TIMEOUT_US) else {
+        return false;
+    };
+    ir::is_valid_leader_mark(w)
+}
+
+/// Validate the NEC leader space width.
+fn validate_leader_space(timer: &HalTimer) -> bool {
+    let Some(w) = wait_for_level(timer, false, ir::LEADER_SPACE_TIMEOUT_US) else {
+        return false;
+    };
+    ir::is_valid_leader_space(w)
+}
+
 /// Wait for the NEC leader burst and space.
 fn wait_leader(timer: &HalTimer) -> bool {
-    if wait_for_level(timer, false, ir::LEADER_START_TIMEOUT_US).is_none() {
-        return false;
+    wait_for_idle(timer) && validate_leader_mark(timer) && validate_leader_space(timer)
+}
+
+/// Wait for the bit mark and measure the bit space width.
+fn measure_bit_space(timer: &HalTimer) -> Option<i64> {
+    if wait_for_level(timer, true, ir::BIT_MARK_TIMEOUT_US).is_none() {
+        return None;
     }
-    let Some(mark_width) = wait_for_level(timer, true, ir::LEADER_MARK_TIMEOUT_US) else {
-        return false;
-    };
-    if !ir::is_valid_leader_mark(mark_width) {
-        return false;
+    let w = wait_for_level(timer, false, ir::BIT_SPACE_TIMEOUT_US)?;
+    if !ir::is_valid_bit_space(w) {
+        return None;
     }
-    let Some(space_width) = wait_for_level(timer, false, ir::LEADER_SPACE_TIMEOUT_US) else {
-        return false;
-    };
-    ir::is_valid_leader_space(space_width)
+    Some(w)
 }
 
 /// Read one NEC bit and store it in the frame buffer.
 fn read_nec_bit(timer: &HalTimer, data: &mut [u8; 4], bit_index: usize) -> bool {
-    if wait_for_level(timer, true, ir::BIT_MARK_TIMEOUT_US).is_none() {
-        return false;
-    }
-    let Some(space_width) = wait_for_level(timer, false, ir::BIT_SPACE_TIMEOUT_US) else {
+    let Some(space_width) = measure_bit_space(timer) else {
         return false;
     };
-    if !ir::is_valid_bit_space(space_width) {
-        return false;
-    }
     ir::accumulate_nec_bit(data, bit_index, space_width);
     true
 }
@@ -225,7 +246,14 @@ pub(crate) fn poll_receiver(
 /// * `pac` - PAC Peripherals singleton (consumed).
 pub(crate) fn run(mut pac: hal::pac::Peripherals) -> ! {
     let mut wd = hal::Watchdog::new(pac.WATCHDOG);
-    let clocks = init_clocks(pac.XOSC, pac.CLOCKS, pac.PLL_SYS, pac.PLL_USB, &mut pac.RESETS, &mut wd);
+    let clocks = init_clocks(
+        pac.XOSC,
+        pac.CLOCKS,
+        pac.PLL_SYS,
+        pac.PLL_USB,
+        &mut pac.RESETS,
+        &mut wd,
+    );
     let pins = init_pins(pac.IO_BANK0, pac.PADS_BANK0, pac.SIO, &mut pac.RESETS);
     let uart = init_uart(pac.UART0, pins.gpio0, pins.gpio1, &mut pac.RESETS, &clocks);
     let mut delay = init_delay(&clocks);
@@ -235,7 +263,9 @@ pub(crate) fn run(mut pac: hal::pac::Peripherals) -> ! {
     let timer = hal::Timer::new(pac.TIMER, &mut pac.RESETS);
     let _ = pins.gpio5.into_pull_up_input();
     announce_ir(&uart);
-    loop { poll_receiver(&uart, &timer, &mut delay); }
+    loop {
+        poll_receiver(&uart, &timer, &mut delay);
+    }
 }
 
 /// Print the IR driver initialisation banner over UART.
@@ -248,4 +278,4 @@ fn announce_ir(uart: &EnabledUart) {
     uart.write_full_blocking(b"Press a button on your NEC remote...\r\n");
 }
 
-// End of file
+// End of file

drivers/0x0a_ir_rust/src/ir.rs

@@ -153,36 +153,43 @@ mod tests {
     // Import all parent module items
     use super::*;
 
+    /// Leader mark accepts lower bound.
     #[test]
     fn leader_mark_accepts_lower_bound() {
         assert!(is_valid_leader_mark(8_000));
     }
 
+    /// Leader mark rejects below lower bound.
     #[test]
     fn leader_mark_rejects_below_lower_bound() {
         assert!(!is_valid_leader_mark(7_999));
     }
 
+    /// Leader space accepts upper bound.
     #[test]
     fn leader_space_accepts_upper_bound() {
         assert!(is_valid_leader_space(5_000));
     }
 
+    /// Leader space rejects above upper bound.
     #[test]
     fn leader_space_rejects_above_upper_bound() {
         assert!(!is_valid_leader_space(5_001));
     }
 
+    /// Bit space rejects short pulse.
     #[test]
     fn bit_space_rejects_short_pulse() {
         assert!(!is_valid_bit_space(199));
     }
 
+    /// Bit space accepts threshold.
     #[test]
     fn bit_space_accepts_threshold() {
         assert!(is_valid_bit_space(200));
     }
 
+    /// Accumulate zero bit leaves byte clear.
     #[test]
     fn accumulate_zero_bit_leaves_byte_clear() {
         let mut data = [0u8; 4];
@@ -190,6 +197,7 @@ mod tests {
         assert_eq!(data[0], 0);
     }
 
+    /// Accumulate one bit sets lsb.
     #[test]
     fn accumulate_one_bit_sets_lsb() {
         let mut data = [0u8; 4];
@@ -197,6 +205,7 @@ mod tests {
         assert_eq!(data[0], 1);
     }
 
+    /// Accumulate crosses into next byte.
     #[test]
     fn accumulate_crosses_into_next_byte() {
         let mut data = [0u8; 4];
@@ -205,18 +214,21 @@ mod tests {
         assert_eq!(data[1], 1);
     }
 
+    /// Validate frame returns command.
     #[test]
     fn validate_frame_returns_command() {
         let data = [0x00, 0xFF, 0x45, 0xBA];
         assert_eq!(validate_nec_frame(&data), Some(0x45));
     }
 
+    /// Validate frame rejects bad inverse.
     #[test]
     fn validate_frame_rejects_bad_inverse() {
         let data = [0x00, 0xFE, 0x45, 0xBA];
         assert_eq!(validate_nec_frame(&data), None);
     }
 
+    /// Format command single digit.
     #[test]
     fn format_command_single_digit() {
         let mut buf = [0u8; 24];
@@ -224,6 +236,7 @@ mod tests {
         assert_eq!(&buf[..n], b"NEC command: 0x07  (7)\r\n");
     }
 
+    /// Format command three digits.
     #[test]
     fn format_command_three_digits() {
         let mut buf = [0u8; 26];
@@ -231,6 +244,7 @@ mod tests {
         assert_eq!(&buf[..n], b"NEC command: 0xFF  (255)\r\n");
     }
 
+    /// Format hex digit alpha.
     #[test]
     fn format_hex_digit_alpha() {
         assert_eq!(hex_digit(0x0A), b'A');

drivers/0x0a_ir_rust/src/main.rs

@@ -64,13 +64,13 @@ use rp235x_hal as hal;
 #[cfg(rp2040)]
 use rp2040_hal as hal;
 
-// Second-stage boot loader for RP2040
+/// Second-stage boot loader for RP2040
 #[unsafe(link_section = ".boot2")]
 #[used]
 #[cfg(rp2040)]
 pub static BOOT2: [u8; 256] = rp2040_boot2::BOOT_LOADER_W25Q080;
 
-// Boot metadata for the RP2350 Boot ROM
+/// Boot metadata for the RP2350 Boot ROM
 #[unsafe(link_section = ".start_block")]
 #[used]
 #[cfg(rp2350)]
@@ -82,7 +82,7 @@ fn main() -> ! {
     board::run(hal::pac::Peripherals::take().unwrap())
 }
 
-// Picotool binary info metadata
+/// Picotool binary info metadata
 #[unsafe(link_section = ".bi_entries")]
 #[used]
 pub static PICOTOOL_ENTRIES: [hal::binary_info::EntryAddr; 5] = [