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

@@ -43,10 +43,10 @@ use hal::spi::Spi;
 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;
@@ -85,12 +85,7 @@ pub(crate) type MosiPin = Pin<hal::gpio::bank0::Gpio19, FunctionSpi, PullNone>;
 pub(crate) type EnabledUart = UartPeripheral<Enabled, hal::pac::UART0, (TxPin, RxPin)>;
 
 /// Type alias for the SPI0 peripheral configured in 8-bit master mode.
-pub(crate) type EnabledSpi = Spi<
-    hal::spi::Enabled,
-    hal::pac::SPI0,
-    (MosiPin, MisoPin, SckPin),
-    8,
->;
+pub(crate) type EnabledSpi = Spi<hal::spi::Enabled, hal::pac::SPI0, (MosiPin, MisoPin, SckPin), 8>;
 
 /// Initialise system clocks and PLLs from the external 12 MHz crystal.
 pub(crate) fn init_clocks(
@@ -102,7 +97,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()
 }
@@ -142,6 +143,28 @@ pub(crate) fn init_delay(clocks: &hal::clocks::ClocksManager) -> cortex_m::delay
     cortex_m::delay::Delay::new(core.SYST, clocks.system_clock.freq().to_Hz())
 }
 
+/// Reconfigure MISO, SCK, and MOSI pins from default to SPI function.
+fn reconfigure_data_pins(
+    miso: hal::gpio::Pin<hal::gpio::bank0::Gpio16, FunctionNull, PullDown>,
+    sck: hal::gpio::Pin<hal::gpio::bank0::Gpio18, FunctionNull, PullDown>,
+    mosi: hal::gpio::Pin<hal::gpio::bank0::Gpio19, FunctionNull, PullDown>,
+) -> (MosiPin, MisoPin, SckPin) {
+    (
+        mosi.reconfigure::<FunctionSpi, PullNone>(),
+        miso.reconfigure::<FunctionSpi, PullNone>(),
+        sck.reconfigure::<FunctionSpi, PullNone>(),
+    )
+}
+
+/// Reconfigure a pin as digital output and de-assert chip select (drive high).
+fn init_cs_pin(
+    cs: hal::gpio::Pin<hal::gpio::bank0::Gpio17, FunctionNull, PullDown>,
+) -> CsPin {
+    let mut cs = cs.reconfigure::<FunctionSio<hal::gpio::SioOutput>, PullNone>();
+    let _ = cs.set_high();
+    cs
+}
+
 /// Configure SPI0 and the software-controlled chip-select pin.
 pub(crate) fn init_spi(
     spi0: hal::pac::SPI0,
@@ -152,11 +175,8 @@ pub(crate) fn init_spi(
     resets: &mut hal::pac::RESETS,
     clocks: &hal::clocks::ClocksManager,
 ) -> (EnabledSpi, CsPin) {
-    let miso = miso.reconfigure::<FunctionSpi, PullNone>();
-    let sck = sck.reconfigure::<FunctionSpi, PullNone>();
-    let mosi = mosi.reconfigure::<FunctionSpi, PullNone>();
-    let mut cs = cs.reconfigure::<FunctionSio<hal::gpio::SioOutput>, PullNone>();
-    let _ = cs.set_high();
+    let (mosi, miso, sck) = reconfigure_data_pins(miso, sck, mosi);
+    let cs = init_cs_pin(cs);
     let spi = Spi::<_, _, _, 8>::new(spi0, (mosi, miso, sck)).init(
         resets,
         clocks.peripheral_clock.freq(),
@@ -176,6 +196,22 @@ fn cs_deselect(cs: &mut CsPin) {
     let _ = cs.set_high();
 }
 
+/// Execute a full-duplex SPI transfer with chip-select framing.
+fn execute_transfer(spi_dev: &mut EnabledSpi, cs: &mut CsPin, rx: &mut [u8]) {
+    cs_select(cs);
+    let _ = spi_dev.transfer(rx, spi::TX_MESSAGE);
+    cs_deselect(cs);
+}
+
+/// Format and print the TX and RX lines over UART.
+fn print_transfer_result(uart: &EnabledUart, rx: &[u8]) {
+    let mut line_buf = [0u8; 24];
+    let tx_len = spi::format_tx_line(&mut line_buf, spi::TX_MESSAGE);
+    uart.write_full_blocking(&line_buf[..tx_len]);
+    let rx_len = spi::format_rx_line(&mut line_buf, rx);
+    uart.write_full_blocking(&line_buf[..rx_len]);
+}
+
 /// Perform one SPI loopback transfer and print TX/RX text over UART.
 pub(crate) fn loopback_transfer(
     spi_dev: &mut EnabledSpi,
@@ -183,17 +219,9 @@ pub(crate) fn loopback_transfer(
     uart: &EnabledUart,
     delay: &mut cortex_m::delay::Delay,
 ) {
-    let tx = spi::TX_MESSAGE;
     let mut rx = [0u8; spi::TX_MESSAGE.len()];
-    cs_select(cs);
-    let _ = spi_dev.transfer(&mut rx, tx);
-    cs_deselect(cs);
-
-    let mut line_buf = [0u8; 24];
-    let tx_len = spi::format_tx_line(&mut line_buf, tx);
-    uart.write_full_blocking(&line_buf[..tx_len]);
-    let rx_len = spi::format_rx_line(&mut line_buf, &rx);
-    uart.write_full_blocking(&line_buf[..rx_len]);
+    execute_transfer(spi_dev, cs, &mut rx);
+    print_transfer_result(uart, &rx);
     spi::clear_rx_buffer(&mut rx);
     delay.delay_ms(POLL_MS);
 }
@@ -205,15 +233,30 @@ pub(crate) fn loopback_transfer(
 /// * `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);
     let (mut spi, mut cs) = init_spi(
-        pac.SPI0, pins.gpio16, pins.gpio17, pins.gpio18, pins.gpio19, &mut pac.RESETS, &clocks,
+        pac.SPI0,
+        pins.gpio16,
+        pins.gpio17,
+        pins.gpio18,
+        pins.gpio19,
+        &mut pac.RESETS,
+        &clocks,
     );
     uart.write_full_blocking(b"SPI driver initialized on SPI0 at 1000000 Hz\r\n");
-    loop { loopback_transfer(&mut spi, &mut cs, &uart, &mut delay); }
+    loop {
+        loopback_transfer(&mut spi, &mut cs, &uart, &mut delay);
+    }
 }
 
-// End of file
+// End of file

drivers/0x0b_spi_rust/src/main.rs

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

drivers/0x0b_spi_rust/src/spi.rs

@@ -110,6 +110,7 @@ mod tests {
     // Import all parent module items
     use super::*;
 
+    /// Valid ports are zero and one.
     #[test]
     fn valid_ports_are_zero_and_one() {
         assert!(is_valid_port(0));
@@ -117,6 +118,7 @@ mod tests {
         assert!(!is_valid_port(2));
     }
 
+    /// Clear rx buffer zeroes all bytes.
     #[test]
     fn clear_rx_buffer_zeroes_all_bytes() {
         let mut rx = [1u8, 2, 3, 4];
@@ -124,6 +126,7 @@ mod tests {
         assert_eq!(rx, [0u8; 4]);
     }
 
+    /// Copy transfer result copies common prefix.
     #[test]
     fn copy_transfer_result_copies_common_prefix() {
         let src = b"abcd";
@@ -132,6 +135,7 @@ mod tests {
         assert_eq!(&dst, b"abc");
     }
 
+    /// Format tx line omits trailing nul.
     #[test]
     fn format_tx_line_omits_trailing_nul() {
         let mut buf = [0u8; 32];
@@ -139,6 +143,7 @@ mod tests {
         assert_eq!(&buf[..n], b"TX: SPI loopback OK\r\n");
     }
 
+    /// Format rx line adds blank line.
     #[test]
     fn format_rx_line_adds_blank_line() {
         let mut buf = [0u8; 32];
@@ -146,6 +151,7 @@ mod tests {
         assert_eq!(&buf[..n], b"RX: SPI loopback OK\r\n\r\n");
     }
 
+    /// C string len stops at nul.
     #[test]
     fn c_string_len_stops_at_nul() {
         assert_eq!(c_string_len(b"abc\0xyz"), 3);