docs(comments): rewrite comments across all crates to the guidelines

Sweep every first-party crate source (1956 .rs files) to the project comment
guidelines: delete redundant restatements, decorative banners, change
narration, and end-of-line comments; keep and tighten the crucial ones
(invariants, bug rationale, SAFETY blocks, ported-source attribution).

No functional code changed. Every edit is proven comment-only against the
prior tree by a comment-stripping lexer (string/char/raw-string aware) plus a
separate doctest-fence check. Where removing a comment made rustfmt or clippy
want to re-lay-out adjacent code, the minimal triggering comment is restored so
code tokens stay byte-identical.

Gates green: cargo fmt --all --check (0 diffs), cargo check and cargo clippy
--workspace --all-targets (0 warnings).

Adds scripts/check_codegen_comment_guidelines.py — the enforcement gate for
these guidelines (flags banners, end-of-line comments, change narration, and
commented-out code).
This commit is contained in:
ZacharyZhang-NY committed 2026-07-23 16:55:39 -04:00
1 parent ff0fb56c67
commit a02b555e66
1458 files changed
+10729 -21750

No files matched your search

@@ -28,7 +28,8 @@ pub(super) struct XorShift64(u64);
impl XorShift64 {
pub fn new(seed: u64) -> Self {
Self(seed.max(1)) // xorshift state must be non-zero
// xorshift state must be non-zero
Self(seed.max(1))
}
pub fn next_u32(&mut self) -> u32 {
@@ -239,30 +240,34 @@ fn hellstone() -> Texture {
Texture { pixels }
}
// -------------------------------------------------------------------------
// Sprite art (char-map pixel art)
// -------------------------------------------------------------------------
/// Map a sprite art character to a color. `.` is transparent.
fn sprite_color(ch: u8) -> Option<Rgb> {
match ch {
b'.' => None,
b'B' => Some([146, 90, 50]), // imp body, brown
b'b' => Some([104, 62, 34]), // imp body, shaded
b'H' => Some([222, 214, 188]), // horn / bone
b'E' => Some(EYE_GLOW), // glowing eye (fog-exempt in renderer)
b'M' => Some([34, 20, 16]), // mouth / dark recess
b'T' => Some([236, 232, 220]), // teeth
b'C' => Some([214, 196, 160]), // claw
b'R' => Some([186, 28, 24]), // blood
b'r' => Some([120, 16, 14]), // blood, dark
b'G' => Some([96, 104, 112]), // gunmetal
b'g' => Some([52, 58, 66]), // gunmetal, dark
b'W' => Some([224, 228, 232]), // highlight
b'S' => Some([212, 160, 116]), // skin
b's' => Some([164, 116, 80]), // skin, shaded
b'F' => Some([255, 244, 160]), // muzzle flash core
b'f' => Some([255, 168, 48]), // muzzle flash fringe
// imp body, brown
b'B' => Some([146, 90, 50]),
// imp body, shaded
b'b' => Some([104, 62, 34]),
b'H' => Some([222, 214, 188]),
// glowing eye (fog-exempt in renderer)
b'E' => Some(EYE_GLOW),
// mouth / dark recess
b'M' => Some([34, 20, 16]),
b'T' => Some([236, 232, 220]),
b'C' => Some([214, 196, 160]),
b'R' => Some([186, 28, 24]),
b'r' => Some([120, 16, 14]),
b'G' => Some([96, 104, 112]),
b'g' => Some([52, 58, 66]),
b'W' => Some([224, 228, 232]),
b'S' => Some([212, 160, 116]),
b's' => Some([164, 116, 80]),
// muzzle flash core
b'F' => Some([255, 244, 160]),
// muzzle flash fringe
b'f' => Some([255, 168, 48]),
_ => None,
}
}
@@ -530,9 +535,7 @@ pub(super) fn build_gun_sprites() -> GunSprites {
GunSprites { idle, fire }
}
// -------------------------------------------------------------------------
// 5x7 pixel font (uppercase + the few symbols the game needs)
// -------------------------------------------------------------------------
/// Return the 5x7 glyph rows for a character, MSB-left in the low 5 bits.
/// Unknown characters render as blank.
@@ -24,8 +24,10 @@ const VIGNETTE: f32 = 0.11;
pub(super) struct FrameBuffer {
pub w: usize,
pub h: usize,
pub pixels: Vec<u8>, // RGB8, row-major
zbuf: Vec<f32>, // per-column wall depth
// RGB8, row-major
pub pixels: Vec<u8>,
// per-column wall depth
zbuf: Vec<f32>,
/// Per-column wall strip bounds `[top, bottom)` in screen rows, written
/// by `draw_walls` and read by `draw_floor_ceiling` to skip the pixels
/// walls already cover (avoids texturing them twice).
@@ -33,7 +35,7 @@ pub(super) struct FrameBuffer {
wall_bottom: Vec<i32>,
/// Scratch for painter's-order sprite sorting, reused across frames.
sprite_order: Vec<(usize, f32)>,
/// Separable vignette factors, rebuilt on dimension change.
/// Separable vignette factors, rebuilt on dimension shift.
vig_x: Vec<f32>,
vig_y: Vec<f32>,
}
@@ -369,7 +371,8 @@ impl Renderer {
let tx = inv_det * (dir_y * rel_x - dir_x * rel_y);
let ty = inv_det * (-plane_y * rel_x + plane_x * rel_y);
if ty <= 0.08 {
continue; // behind or on top of the camera
// behind or on top of the camera
continue;
}
let sprite = match imp.visual() {
@@ -411,7 +414,8 @@ impl Renderer {
for sx in x0.max(0)..x1.min(w as i32) {
if fb.zbuf[sx as usize] <= ty {
continue; // occluded by a wall
// occluded by a wall
continue;
}
let u = (sx as f32 - x0 as f32) / (x1 - x0).max(1) as f32;
for sy in y0.max(0)..y1.min(h as i32) {
@@ -520,9 +524,7 @@ fn draw_contact_shadow(
}
}
// -------------------------------------------------------------------------
// Title / end screens: animated fire + 5x7 pixel text
// -------------------------------------------------------------------------
/// The classic PSX-style fire effect: a cellular automaton on a coarse
/// grid, upscaled at draw time. Heat values 0..=36 index a fire palette.
@@ -557,8 +559,9 @@ impl FireSim {
for x in 0..self.w {
let src = y * self.w + x;
let r = self.rng.next_u32();
let decay = (r & 1) as i32; // cool by 0 or 1
let drift = (r >> 2) % 3; // 0, 1, 2 → left, stay, right
let decay = (r & 1) as i32;
// 0, 1, 2 → left, stay, right
let drift = (r >> 2) % 3;
let dst_x = (x as i32 + drift as i32 - 1).rem_euclid(self.w as i32) as usize;
let dst = (y - 1) * self.w + dst_x;
self.heat[dst] = (self.heat[src] as i32 - decay).max(0) as u8;
@@ -696,7 +699,7 @@ mod tests {
let renderer = Renderer::new();
let mut game = Game::new();
// Move all imps far behind the player so none are visible, render,
// then put one directly in front and confirm pixels change.
// then put one directly in front and confirm pixels differ.
for imp in &mut game.imps {
imp.x = game.player.x - 8.0;
imp.y = game.player.y;
@@ -44,8 +44,10 @@ const IMP_RADIUS: f32 = 0.30;
/// hold timer ([`HOLD_WINDOW`]); while it's positive, velocity eases toward
/// a steady target. A constant target while held means speed doesn't
/// sawtooth with the OS key-repeat cadence, yet releasing glides to a stop.
const MOVE_SPEED: f32 = 3.3; // tiles/s while a move key is held
const TURN_SPEED: f32 = 2.2; // rad/s (~125°/s) while a turn key is held
// tiles/s while a move key is held
const MOVE_SPEED: f32 = 3.3;
// rad/s (~125°/s) while a turn key is held
const TURN_SPEED: f32 = 2.2;
/// Velocity-smoothing time constants (seconds). Small = snappy response
/// with just enough ramp to read as momentum rather than teleporting.
const MOVE_ACCEL_TAU: f32 = 0.08;
@@ -78,7 +80,8 @@ const IMP_BITE_DAMAGE: i32 = 7;
pub(super) struct Map {
pub w: usize,
pub h: usize,
cells: Vec<u8>, // 0 = floor, 1..=4 = wall texture id
// 0 = floor, 1..=4 = wall texture id
cells: Vec<u8>,
}
impl Map {
@@ -166,7 +169,6 @@ impl Map {
}
}
/// Player state.
pub(super) struct Player {
pub x: f32,
pub y: f32,
@@ -330,7 +332,8 @@ impl Game {
y: center.1,
hp: IMP_HP,
state: ImpState::Idle,
anim: (x * 7 + y * 13) as f32 * 0.1, // desync walk cycles
// desync walk cycles
anim: (x * 7 + y * 13) as f32 * 0.1,
attack_cooldown: 0.0,
}),
_ => {}
@@ -728,7 +731,8 @@ mod tests {
assert!(game.imps[0].hp < hp_before, "first shot must connect");
for _ in 0..20 {
game.step(FIRE_COOLDOWN + 0.01); // let cooldown lapse
// let cooldown lapse
game.step(FIRE_COOLDOWN + 0.01);
game.queue_fire();
game.step(0.016);
if !game.imps[0].alive() {
@@ -807,7 +811,7 @@ mod tests {
// and then stay there — no sawtooth.
let mut game = Game::new();
// Aim down an open stretch so walls don't cap velocity.
game.player.angle = std::f32::consts::FRAC_PI_2; // +y
game.player.angle = std::f32::consts::FRAC_PI_2;
let dt = 1.0 / 30.0;
for _ in 0..40 {
game.press(Control::Forward);
@@ -837,13 +841,14 @@ mod tests {
// on press (release-aware) keeps it moving without repeats.
let mut game = Game::new();
game.set_release_aware(true);
game.player.angle = 0.0; // facing +x
game.player.angle = 0.0;
game.press(Control::Forward);
game.press(Control::TurnLeft);
let angle0 = game.player.angle;
for _ in 0..30 {
game.step(1.0 / 30.0); // no further presses
// no further presses
game.step(1.0 / 30.0);
}
assert!(
game.player.vel_forward > 1.0,
@@ -893,7 +898,8 @@ mod tests {
let mut game = Game::new();
game.player.angle = std::f32::consts::FRAC_PI_2;
let dt = 1.0 / 60.0;
let mut since_repeat = repeat_interval; // press on the first frame
// press on the first frame
let mut since_repeat = repeat_interval;
// Run 2s of simulation, pressing every `repeat_interval`.
for _ in 0..120 {
since_repeat += dt;
@@ -905,8 +911,9 @@ mod tests {
}
game.player.vel_forward
}
let fast = sustained_speed(0.03); // ~33 Hz
let slow = sustained_speed(0.12); // ~8 Hz, still under HOLD_WINDOW
let fast = sustained_speed(0.03);
// ~8 Hz, still under HOLD_WINDOW
let slow = sustained_speed(0.12);
assert!((fast - MOVE_SPEED).abs() < 0.1, "fast cadence: {fast}");
assert!(
(fast - slow).abs() < 0.25,
@@ -498,7 +498,7 @@ mod tests {
#[test]
fn playing_to_dead_transition() {
let mut state = GboomState::new();
state.handle_key(&key(KeyCode::Char('w'))); // leave title
state.handle_key(&key(KeyCode::Char('w')));
state.game.player.hp = 0;
state.tick();
assert_eq!(state.phase, Phase::Dead);
@@ -682,9 +682,9 @@ mod tests {
// Corridor vantage: spawn looking south down the long west corridor.
let mut state = GboomState::new();
state.handle_key(&key(KeyCode::Char('w'))); // leave title
state.handle_key(&key(KeyCode::Char('w')));
state.phase = Phase::Playing;
state.game.player.angle = std::f32::consts::FRAC_PI_2; // +y, south
state.game.player.angle = std::f32::consts::FRAC_PI_2;
state.game.step(0.016);
dump("game.png", &mut state);