Skip to content

Clean up code comments and add algorithm citations - #17

Merged
tamirelazar merged 10 commits into
devfrom
chore/comment-sweep
Jun 12, 2026
Merged

Clean up code comments and add algorithm citations#17
tamirelazar merged 10 commits into
devfrom
chore/comment-sweep

Conversation

@tamirelazar

Copy link
Copy Markdown
Owner

Summary

Full sweep of every comment in src/ (54 files, +432/−856):

  • Wrong/stale docs fixed — highlights: FrameTimer doc described the pre-flicker-fix architecture; frame_buffer claimed double-buffering that doesn't exist; max_brightness docs conflated the internal white-point divisor with the user-facing gain; dither::max_value doc was off by the actual semantics; local_variance returns a standard deviation; path_continuity is a flood-fill region-size proxy, not path tracing; nonexistent open_exclusive reference removed
  • Noise deleted — narration comments restating the next line
  • Verbose-but-true tightened# Arguments blocks restating signatures → one prose sentence with the units/semantics that matter
  • Citations injected (verified against sources): Jones 2010 (doi:10.1162/artl.2010.16.2.16202) in simulation; Miranda, Adamatzky & Jones 2011 (doi:10.1016/S1672-6529(11)60016-4) in audio; Ottosson 2020 OKLab post in palette.rs/gradients.rs (incl. an honest note that the red-row M/S constants predate the 2021 matrix update); Floyd & Steinberg 1976 in error_diffusion.rs; Bayer 1973 in dither.rs

Two sanctioned user-facing string fixes (not comments): placeholder yourusername URL → real repo; --quadrant help claimed "4× vertical resolution" (it's 2×2 subpixels per cell).

Verification

  • Whole-branch diff check: only comment lines changed (plus the two string fixes above)
  • cargo fmt --check, cargo clippy -- -D warnings (default + all-features)
  • cargo test --lib 752 passed, --all-features 764, doctests 19, visual regression 46 — goldens untouched

Known issues found but out of scope (comment-only PR)

  • --help renders constant paths instead of values for ~25 flags (stringify! misuse), e.g. [default: population::DEFAULT_POPULATION]
  • --pause-style help lists 8 of 12 accepted styles; clap default ("minimal") disagrees with Args::default() (Vignette)
  • --decay help says 0.0-1.0; validated range is 0.5-0.9999
  • png.rs timestamp "uniqueness" reads subsec_nanos() of a fresh Instant (~0)

@tamirelazar
tamirelazar merged commit 470f423 into dev Jun 12, 2026
3 checks passed
@tamirelazar
tamirelazar deleted the chore/comment-sweep branch June 12, 2026 21:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant