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/0x0f_flash_rust/src/board.rs

@@ -39,10 +39,10 @@ use hal::rom_data;
 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;
 
 /// External crystal frequency in Hz (12 MHz).
 pub(crate) const XTAL_FREQ_HZ: u32 = 12_000_000u32;
@@ -92,7 +92,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()
 }
@@ -153,6 +159,37 @@ pub(crate) fn init_uart(
         .unwrap()
 }
 
+/// Transition flash out of XIP mode and erase the target sector.
+///
+/// # Safety
+///
+/// Must be called with interrupts disabled and no other flash access active.
+unsafe fn flash_prepare_sector(flash_offset: u32) {
+    unsafe {
+        rom_data::connect_internal_flash();
+        rom_data::flash_exit_xip();
+        rom_data::flash_range_erase(
+            flash_offset,
+            flash::FLASH_SECTOR_SIZE as usize,
+            flash::FLASH_SECTOR_SIZE,
+            0x20,
+        );
+    }
+}
+
+/// Program data into the erased sector and restore XIP mode.
+///
+/// # Safety
+///
+/// Must be called with interrupts disabled and no other flash access active.
+unsafe fn flash_program_and_restore(flash_offset: u32, data: &[u8]) {
+    unsafe {
+        rom_data::flash_range_program(flash_offset, data.as_ptr(), data.len());
+        rom_data::flash_flush_cache();
+        rom_data::flash_enter_cmd_xip();
+    }
+}
+
 /// Erase one 4096-byte sector and write data to on-chip flash.
 ///
 /// Disables interrupts, transitions the flash device out of XIP mode,
@@ -170,19 +207,9 @@ pub(crate) fn init_uart(
 /// Caller must ensure no other core or DMA is accessing flash/XIP during
 /// this operation.
 pub(crate) fn flash_write(flash_offset: u32, data: &[u8]) {
-    let len = data.len();
     cortex_m::interrupt::free(|_| unsafe {
-        rom_data::connect_internal_flash();
-        rom_data::flash_exit_xip();
-        rom_data::flash_range_erase(
-            flash_offset,
-            flash::FLASH_SECTOR_SIZE as usize,
-            flash::FLASH_SECTOR_SIZE,
-            0x20,
-        );
-        rom_data::flash_range_program(flash_offset, data.as_ptr(), len);
-        rom_data::flash_flush_cache();
-        rom_data::flash_enter_cmd_xip();
+        flash_prepare_sector(flash_offset);
+        flash_program_and_restore(flash_offset, data);
     });
 }
 
@@ -211,11 +238,20 @@ pub(crate) fn flash_read(flash_offset: u32, out: &mut [u8]) {
 /// * `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);
     flash_demo(&uart);
-    loop { cortex_m::asm::wfe(); }
+    loop {
+        cortex_m::asm::wfe();
+    }
 }
 
 /// Execute the flash write / read-back / report sequence.

drivers/0x0f_flash_rust/src/flash.rs

@@ -46,6 +46,25 @@ pub const XIP_BASE: u32 = 0x1000_0000;
 /// Demo string written to flash, matching the C demo exactly.
 pub const DEMO_MSG: &[u8] = b"Embedded Hacking flash driver demo";
 
+/// Fill the entire buffer with 0xFF (erased flash state).
+fn fill_erased(buf: &mut [u8]) {
+    for b in buf.iter_mut() {
+        *b = 0xFF;
+    }
+}
+
+/// Copy the demo string and NUL terminator into `buf`, returning meaningful length.
+fn copy_demo_msg(buf: &mut [u8]) -> usize {
+    let msg_with_nul = DEMO_MSG.len() + 1;
+    let n = msg_with_nul.min(buf.len());
+    let copy_len = DEMO_MSG.len().min(n);
+    buf[..copy_len].copy_from_slice(&DEMO_MSG[..copy_len]);
+    if copy_len < n {
+        buf[copy_len] = 0x00;
+    }
+    n
+}
+
 /// Prepare a write buffer with 0xFF fill and the demo string at the start.
 ///
 /// Mirrors the C demo's `_prepare_write_buf()` function. The buffer is
@@ -60,17 +79,8 @@ pub const DEMO_MSG: &[u8] = b"Embedded Hacking flash driver demo";
 ///
 /// Number of meaningful bytes (string length + NUL terminator).
 pub fn prepare_write_buf(buf: &mut [u8]) -> usize {
-    for b in buf.iter_mut() {
-        *b = 0xFF;
-    }
-    let msg_with_nul = DEMO_MSG.len() + 1;
-    let n = msg_with_nul.min(buf.len());
-    let copy_len = DEMO_MSG.len().min(n);
-    buf[..copy_len].copy_from_slice(&DEMO_MSG[..copy_len]);
-    if copy_len < n {
-        buf[copy_len] = 0x00;
-    }
-    n
+    fill_erased(buf);
+    copy_demo_msg(buf)
 }
 
 /// Format the "Flash readback: <string>\r\n" message into `buf`.
@@ -115,36 +125,43 @@ mod tests {
     // Import all parent module items
     use super::*;
 
+    /// Flash size is 4mb.
     #[test]
     fn flash_size_is_4mb() {
         assert_eq!(FLASH_SIZE_BYTES, 4 * 1024 * 1024);
     }
 
+    /// Sector size is 4096.
     #[test]
     fn sector_size_is_4096() {
         assert_eq!(FLASH_SECTOR_SIZE, 4096);
     }
 
+    /// Page size is 256.
     #[test]
     fn page_size_is_256() {
         assert_eq!(FLASH_PAGE_SIZE, 256);
     }
 
+    /// Target offset is last sector.
     #[test]
     fn target_offset_is_last_sector() {
         assert_eq!(FLASH_TARGET_OFFSET, FLASH_SIZE_BYTES - FLASH_SECTOR_SIZE);
     }
 
+    /// Write len matches page size.
     #[test]
     fn write_len_matches_page_size() {
         assert_eq!(FLASH_WRITE_LEN, 256);
     }
 
+    /// Xip base address.
     #[test]
     fn xip_base_address() {
         assert_eq!(XIP_BASE, 0x1000_0000);
     }
 
+    /// Prepare write buf fills 0xff.
     #[test]
     fn prepare_write_buf_fills_0xff() {
         let mut buf = [0u8; FLASH_WRITE_LEN];
@@ -156,6 +173,7 @@ mod tests {
         }
     }
 
+    /// Prepare write buf has demo string.
     #[test]
     fn prepare_write_buf_has_demo_string() {
         let mut buf = [0u8; FLASH_WRITE_LEN];
@@ -163,6 +181,7 @@ mod tests {
         assert_eq!(&buf[..DEMO_MSG.len()], DEMO_MSG);
     }
 
+    /// Prepare write buf has nul terminator.
     #[test]
     fn prepare_write_buf_has_nul_terminator() {
         let mut buf = [0u8; FLASH_WRITE_LEN];
@@ -170,6 +189,7 @@ mod tests {
         assert_eq!(buf[DEMO_MSG.len()], 0x00);
     }
 
+    /// Format readback matches c output.
     #[test]
     fn format_readback_matches_c_output() {
         let mut read_data = [0xFFu8; FLASH_WRITE_LEN];
@@ -184,6 +204,7 @@ mod tests {
         );
     }
 
+    /// Format readback empty string.
     #[test]
     fn format_readback_empty_string() {
         let read_data = [0u8; 8];
@@ -192,6 +213,7 @@ mod tests {
         assert_eq!(&buf[..n], b"Flash readback: \r\n");
     }
 
+    /// Format readback no nul.
     #[test]
     fn format_readback_no_nul() {
         let read_data = [b'A'; 8];
@@ -200,6 +222,7 @@ mod tests {
         assert_eq!(&buf[..n], b"Flash readback: AAAAAAAA\r\n");
     }
 
+    /// Demo msg matches c string.
     #[test]
     fn demo_msg_matches_c_string() {
         assert_eq!(DEMO_MSG, b"Embedded Hacking flash driver demo");

drivers/0x0f_flash_rust/src/main.rs

@@ -61,13 +61,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)]
@@ -79,7 +79,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] = [