Skip to content

chore: remove every comment from the Rust sources - #345

Merged
LeadcodeDev merged 1 commit into
mainfrom
chore/strip-comments
Sep 26, 2026
Merged

LeadcodeDev merged 1 commit into
mainfrom
chore/strip-comments

Conversation

@LeadcodeDev

Copy link
Copy Markdown
Owner

Stacked on #343 — targets feat/install-cli-and-studio, not main. Retarget to main once #343 merges.

16 355 comments removed across 199 changed files. // and //! are both at
zero. The 1 671 /// that remain are the ones clap and schemars read.

before after
// 6 298 0
//! 1 255 0
/// 8 943 1 671 (clap + schemars only)

Why those 1 671 stay

They are not documentation, they are interface text:

Read by Where What it produces
clap types deriving Parser/Subcommand/Args/ValueEnum the text of rustmotion --help
schemars types deriving JsonSchema, and their fields the description fields of the exported schema, which validate --strict-attrs consumes

Removing them would not delete a comment. It would empty --help and strip
1 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 and
block-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 preserved
  • rustmotion --help and all twelve subcommands → byte-identical

Both 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 Cli was reached. Every global option lost its help:

-  -q, --quiet              Suppress all output except errors
+  -q, --quiet

Braces inside string literals. Comments were blanked before counting brace
depth; literals were not. A { inside an about = "…" or a format! shifted
the depth that decides where a protected struct body ends, so fields near the
end of a struct fell outside it — six badge fields, 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_slug and expr's
module example. Ported to #[test] functions in the mod tests each file
already had, rather than lost.

Build Tests before Tests after
default 1510 1510
--features studio 1701 1701

Two if chains had identical branches — only the comments differed

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, 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 from SystemTime::now().as_nanos() alone, so two
annotations 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 = 3 under its old
package. Running the full suite is simply what tripped it.

Verification

  • cargo fmt --all --check clean
  • cargo clippy --workspace --all-targets -- -D warnings clean, and with --features rustmotion/studio
  • both test configurations at their original counts
  • the two byte-identical invariants above

CLAUDE.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.

@LeadcodeDev LeadcodeDev added the enhancement New feature or request label Sep 26, 2026
@LeadcodeDev LeadcodeDev self-assigned this Sep 26, 2026
@LeadcodeDev
LeadcodeDev added this pull request to stack #346 September 26, 2026 22:03
Base automatically changed from feat/install-cli-and-studio to main September 26, 2026 22:04
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.
@LeadcodeDev

Copy link
Copy Markdown
Owner Author

Rebased onto main now that #342 and #343 are in.

The conflict was structural rather than semantic: this branch carried the install
work as its own commit, while main received the squashed version of it, so the
two histories described the same change differently. Replaying only the strip
commit (git rebase --onto origin/main <install-commit>) let git recognise the
install work as already applied and skip it, which left exactly one real
conflict: gradient_text.rs, the file #342 touched.

Resolved by taking main's version — the #337 fix with its comments — and
running the stripper over it, so the new code stays and only its comments go. 84
comments removed from that file.

Both invariants re-verified against the same pre-strip baseline, which also
confirms neither #342 nor #343 moved them:

  • rustmotion schema — byte-identical, 1 223 descriptions
  • rustmotion --help and all twelve subcommands — byte-identical

Test count rises by exactly the four tests #342 added:

Build before now
default 1510 1514
--features studio 1701 1705

All ten gradient_text tests pass, so the text-align fix survives the strip.
fmt needed one pass after the rebase — the lines it wrapped around the removed
comments re-fold once they are gone — and is folded into the commit. clippy
clean in both configurations.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant