From 3c91843bfe4b533ef3b7e0da2a6a7f859061113a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 26 Apr 2026 07:34:32 +0000
Subject: [PATCH] fix(ci): missing-docs in framebuffer.rs + clippy/rustfmt for
 1.94.0 toolchain
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI fixes for PR #113:

1. native-backend (missing_docs) — added doc comments for 11 public items
   in src/hpc/framebuffer.rs: Framebuffer.{width,height,tier},
   WobbleState::new, FireState::new, FlybyFrame.{cam_x,cam_y,cam_zoom},
   FlybyCache.{frames,height,len,is_empty}, PyramidShader::new.

2. clippy + format — rust-toolchain.toml pins 1.94.0, but the CI jobs
   install clippy/rustfmt only for the matrix `stable` toolchain. Added
   explicit `rustup component add ... --toolchain 1.94.0` step (with
   `|| true` so it doesn't fail if already installed) so cargo can find
   the components when it resolves the pinned toolchain.

Pre-existing failures NOT addressed in this PR (would balloon scope):
- nostd/thumbv6m: pre-existing unused-import warnings under -D warnings
- cross_test/s390x: pre-existing endianness/cross-compile issues

These fail on origin/master too and are not caused by this PR's changes.

https://claude.ai/code/session_01SbYsmmbPf9YQuYbHZN52Zh
---
 .github/workflows/ci.yaml |  5 +++++
 src/hpc/framebuffer.rs    | 16 ++++++++++++++--
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 52cbaf35..ec0f8033 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -44,6 +44,9 @@ jobs:
         with:
           toolchain: ${{ matrix.rust }}
           components: clippy
+      # rust-toolchain.toml pins 1.94.0 — install clippy for that toolchain too,
+      # since dtolnay/rust-toolchain only installs for the requested matrix value.
+      - run: rustup component add clippy --toolchain 1.94.0 || true
       - uses: Swatinem/rust-cache@v2
       - run: cargo clippy --features approx,serde,rayon -- -D warnings
       - run: cargo clippy --features native -- -D warnings
@@ -56,6 +59,8 @@ jobs:
       - uses: dtolnay/rust-toolchain@stable
         with:
           components: rustfmt
+      # rust-toolchain.toml pins 1.94.0 — install rustfmt for that toolchain too.
+      - run: rustup component add rustfmt --toolchain 1.94.0 || true
       - run: cargo fmt --all --check
 
   nostd:
diff --git a/src/hpc/framebuffer.rs b/src/hpc/framebuffer.rs
index a0d214d6..69c60194 100644
--- a/src/hpc/framebuffer.rs
+++ b/src/hpc/framebuffer.rs
@@ -108,8 +108,11 @@ pub enum ViewMode {
 /// Palette-indexed framebuffer. Each pixel is a u8 index into a palette
 /// whose size is determined by the SIMD tier.
 pub struct Framebuffer {
+    /// Framebuffer width in pixels.
     pub width: usize,
+    /// Framebuffer height in pixels.
     pub height: usize,
+    /// Active palette tier (determines color count and sprite size).
     pub tier: PaletteTier,
     /// Row-major palette indices, length = width × height.
     pub pixels: Vec<u8>,
@@ -551,6 +554,7 @@ pub struct WobbleState {
 }
 
 impl WobbleState {
+    /// Allocate wobble state for `capacity` nodes (decay 0.92, amplitude 3.0).
     pub fn new(capacity: usize) -> Self {
         Self {
             displace: vec![0.0; capacity * 2],
@@ -613,6 +617,7 @@ pub struct FireState {
 }
 
 impl FireState {
+    /// Allocate fire state for `capacity` nodes (decay rate 16/tick).
     pub fn new(capacity: usize) -> Self {
         Self {
             intensity: vec![0u8; capacity],
@@ -755,19 +760,23 @@ pub struct FlybyFrame {
     pub packed: Vec<u64>,
     /// Bits per pixel used for packing.
     pub bpp: usize,
-    /// Camera position at this keyframe.
+    /// Camera X position at this keyframe.
     pub cam_x: f32,
+    /// Camera Y position at this keyframe.
     pub cam_y: f32,
+    /// Camera zoom factor at this keyframe.
     pub cam_zoom: f32,
 }
 
 /// Ring buffer of pre-rendered flyby keyframes.
 pub struct FlybyCache {
+    /// Pre-rendered keyframes in the orbit sequence.
     pub frames: Vec<FlybyFrame>,
     /// Current playback position in [0, frames.len()).
     pub cursor: usize,
-    /// Width/height of pre-rendered frames.
+    /// Width of pre-rendered frames.
     pub width: usize,
+    /// Height of pre-rendered frames.
     pub height: usize,
 }
 
@@ -843,9 +852,11 @@ impl FlybyCache {
         self.frames.iter().map(|f| f.packed.len() * 8).sum()
     }
 
+    /// Frame count.
     /// Frame count.
     pub fn len(&self) -> usize { self.frames.len() }
 
+    /// True when no keyframes have been pre-rendered.
     pub fn is_empty(&self) -> bool { self.frames.is_empty() }
 }
 
@@ -1114,6 +1125,7 @@ pub struct PyramidShader {
 }
 
 impl PyramidShader {
+    /// Allocate the four-level pyramid (~9 MB total: L1=4K + L2=64K + L3=1M + L4=4M + scratch).
     pub fn new(palette_max: u8) -> Self {
         Self {
             l1: vec![0u8; 64 * 64],