chore: remove every comment from the Rust sources - #345
Conversation
16 355 comments removed across 250 files: every `//` and every `//!` is now at zero, and the 1 671 `///` that remain are the ones clap and schemars read. Those are not documentation, they are interface text — removing them would not delete a comment, it would empty `rustmotion --help` and 1 223 descriptions out of the exported schema, which `validate --strict-attrs` consumes. Done by a lexer, not by regex. `"https://example.com/a//b"` contains `//`, and a raw string can hold `/* anything */`, so the stripper tracks string, raw-string, char and block-comment state instead of matching lines. Two invariants pinned it, captured from a binary built before the change and diffed against one built after: - `rustmotion schema` — byte-identical, 1 223 descriptions preserved - `rustmotion --help` plus all twelve subcommands — byte-identical Both caught real losses on the first attempt, which is the reason they were captured. Two structural faults in the detector: - a multi-line attribute. `#[derive(Parser)]` followed by a `#[command(\n name = "rustmotion",\n …\n)]` spanning five lines: the inner lines match neither "attribute" nor "doc comment", so they were read as code and cleared the pending derive list before `struct Cli` was reached. Every global option lost its help text — `-q, --quiet` printed with an empty description. - braces inside string literals. Comments were blanked before counting brace depth, but literals were not, so a `{` in an `about = "…"` or a `format!` shifted the depth that decides where a protected body ends, and fields near the end of a struct fell outside it. Three consequences that are not cosmetic. **Five doctests were tests, and they lived in doc comments.** `VarScope`, `build_css2_url`, `parse_ttf_urls`, `family_slug` and `expr`'s module example have been ported to `#[test]` functions in the `mod tests` each file already had. Test count is unchanged: 1510 by default, 1701 with `--features studio`. **Two `if` chains turned out to have identical branches.** Only the comments distinguished them; the code never did. let depth_sin = if tilt_rad.abs() > 0.01 { // With tilt, depth is based on the untilted Y theta.sin() } else { // Without tilt, use Y component for depth theta.sin() }; `stepper.rs` had the same shape: "Filled circle for active" and "Filled circle for completed" are the same call. Both collapsed to exactly what they already computed — no rendering changes — which makes the defect visible instead of hidden behind a comment that claimed a distinction. Worth a second look by whoever knows what the tilt branch was meant to do. **One flaky test, pre-existing, surfaced by running the suite.** `annotation_id()` derived an id from `SystemTime::now().as_nanos()` alone, so two annotations minted inside one clock tick collided — a real defect in the studio, not just a capricious test. It now carries an atomic tiebreaker. Unrelated to comment removal: the code is byte-identical to before it, and the studio already built at `opt-level = 3`. 40 consecutive runs green. CLAUDE.md now states the rule for the whole codebase, names the clap/schemars exception as interface text rather than an exemption, and records that writing an executable example from here on means writing a test.
|
Rebased onto The conflict was structural rather than semantic: this branch carried the install Resolved by taking Both invariants re-verified against the same pre-strip baseline, which also
Test count rises by exactly the four tests #342 added:
All ten |
91b7039 to
4fab402
Compare
Stacked on #343 — targets
feat/install-cli-and-studio, notmain. Retarget tomainonce #343 merges.16 355 comments removed across 199 changed files.
//and//!are both atzero. The 1 671
///that remain are the ones clap and schemars read.////!///Why those 1 671 stay
They are not documentation, they are interface text:
clapParser/Subcommand/Args/ValueEnumrustmotion --helpschemarsJsonSchema, and their fieldsdescriptionfields of the exported schema, whichvalidate --strict-attrsconsumesRemoving them would not delete a comment. It would empty
--helpand strip1 223 descriptions out of the schema.
Done by a lexer, not a regex
"https://example.com/a//b"contains//. A raw string can hold/* anything */. The stripper tracks string, raw-string, char andblock-comment state, so no literal was touched.
Two invariants, and they both caught real losses
Captured from a binary built before the change and diffed against one built
after:
rustmotion schema→ byte-identical, 1 223 descriptions preservedrustmotion --helpand all twelve subcommands → byte-identicalBoth failed on the first attempt, which is why they were captured. Two
structural faults in the detector:
A multi-line attribute.
#[derive(Parser)]followed by a#[command(…)]spanning five lines: the inner lines (
name = "rustmotion",) match neither"attribute" nor "doc comment", so they read as code and cleared the pending
derive list before
struct Cliwas reached. Every global option lost its help:Braces inside string literals. Comments were blanked before counting brace
depth; literals were not. A
{inside anabout = "…"or aformat!shiftedthe depth that decides where a protected struct body ends, so fields near the
end of a struct fell outside it — six
badgefields,counter's duration,heatmap's animate and others lost their schema descriptions.Three consequences that are not cosmetic
Five doctests were tests, and they lived in doc comments
VarScope,build_css2_url,parse_ttf_urls,family_slugandexpr'smodule example. Ported to
#[test]functions in themod testseach filealready had, rather than lost.
--features studioTwo
ifchains had identical branches — only the comments differedstepper.rshad the same shape: "Filled circle for active" and "Filled circlefor completed" are the same call. Both collapsed to exactly what they already
computed, so nothing renders differently — but the comment was claiming a
distinction the code never made, and collapsing makes that visible instead of
hidden. Worth a second look from whoever knows what the tilt branch was meant
to do; I deliberately did not invent it.
One flaky test, pre-existing
annotation_id()derived an id fromSystemTime::now().as_nanos()alone, so twoannotations minted inside one clock tick collided — a real defect in the studio's
id generator, not just a capricious test. It now carries an atomic tiebreaker;
40 consecutive runs green.
Not caused by this PR and not by #343 either: the function is byte-identical to
before the strip, and the studio already built at
opt-level = 3under its oldpackage. Running the full suite is simply what tripped it.
Verification
cargo fmt --all --checkcleancargo clippy --workspace --all-targets -- -D warningsclean, and with--features rustmotion/studioCLAUDE.md
The rule was crate-scoped to the studio; it now covers the whole codebase, names
the clap/schemars exception as interface text rather than an exemption, and
records the non-obvious corollary: a doctest lives in a doc comment, so writing
an executable example from here on means writing a test.