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:
2026-07-23 16:55:39 -04:00
parent ff0fb56c67
commit a02b555e66
1458 changed files with 10729 additions and 21750 deletions
@@ -68,7 +68,6 @@ const COMPLETION_TIMEOUT: Duration = Duration::from_secs(30);
/// streaming preamble plus its post-gesture tail drain — finishes in ~20s.
const CELL_HARD_CAP: Duration = Duration::from_secs(60);
/// `tier` label for [`CellReport`].
fn tier_label(tier: Tier) -> &'static str {
match tier {
Tier::Curated => "curated",
@@ -145,7 +144,6 @@ fn panic_message(err: tokio::task::JoinError) -> String {
}
}
/// Everything [`run_cell`] needs from a completed (non-aborted) cell body.
struct CellRun {
outcomes: Vec<(InvariantId, InvariantResult)>,
streams: usize,
@@ -311,11 +309,9 @@ fn check_screen(
InvariantResult::Pass
}
/// XPASS row detail: the actionable half of the xfail contract.
const XPASS_DETAIL: &str = "expected to violate (xfail) but PASSED — the pinned bug got fixed \
or the cell rotted; promote the invariant out of the xfail set";
/// Classify evaluated invariants into per-row statuses and the cell verdict.
/// Precedence: any `Fail` (non-xfail violation) fails the cell; else any
/// `XPass` fails it (fixed/rotted xfail must be promoted, not absorbed);
/// else any `XFail` marks the expected failure; else `Pass`.
@@ -370,8 +366,8 @@ mod tests {
}
}
/// The wire bytes of the shared wheel position, pinned to the
/// `40;12` encoding documented on `WHEEL_ROW`/`WHEEL_COL`.
/// Pins the wire bytes to the `40;12` encoding documented on
/// `WHEEL_ROW`/`WHEEL_COL`.
#[test]
fn sgr_report_encodes_one_based_wire_coords() {
assert_eq!(sgr_wheel_report(64), "\x1b[<64;40;12M");
@@ -382,9 +378,7 @@ mod tests {
fn clamped_travel_models_bottom_pin_and_top_clamp() {
// G7's shape: down-deliveries at the pin don't move, the up tail does.
assert_eq!(simulate_clamped_travel(300, [10, -7]), -7);
// Up then partially back down: net movement, no clamp involved.
assert_eq!(simulate_clamped_travel(300, [-5, 3]), -2);
// Pure down at the pin stays put.
assert_eq!(simulate_clamped_travel(300, [10]), 0);
// Down past the pin then up: the overshoot must not bank as credit.
assert_eq!(simulate_clamped_travel(300, [25, -4]), -4);
@@ -422,13 +416,11 @@ mod tests {
fn classify_precedence_fail_over_xpass_over_xfail_over_pass() {
use InvariantId::{Cap, NoDrop, Ord, SmoothCoast};
// All pass, nothing xfailed → Pass.
let (status, rows) = classify(&[(Ord, InvariantResult::Pass)], &[]);
assert_eq!(status, CellStatus::Pass);
assert_eq!(rows[0].status, InvariantStatus::Pass);
assert_eq!(rows[0].id, "I-ORD");
// The declared bug violates, everything else passes → XFail.
let jerk = [
(Ord, InvariantResult::Pass),
(SmoothCoast, violated("coast")),
@@ -439,7 +431,7 @@ mod tests {
assert_eq!(rows[1].status, InvariantStatus::XFail);
assert_eq!(rows[1].detail.as_deref(), Some("coast"));
// One xfail row passing flips the cell to XPass (fixed-bug tripwire)…
// One xfail row passing flips the cell to XPass: the fixed-bug tripwire.
let half_fixed = [
(SmoothCoast, InvariantResult::Pass),
(NoDrop, violated("dropped 74")),
@@ -448,7 +440,7 @@ mod tests {
assert_eq!(status, CellStatus::XPass);
assert!(rows[0].detail.as_deref().unwrap().contains("promote"));
// …but any non-xfail violation dominates everything.
// A non-xfail violation dominates everything.
let broken = [
(Cap, violated("flushed 40 exceeds cap 25")),
(SmoothCoast, InvariantResult::Pass),