Skip to content

docs(i18n): drop the stale per-update count log from the gate comment - #180

Merged
argszero merged 1 commit into
mainfrom
docs/fix-stale-gate-count-comment
Sep 12, 2026
Merged

docs(i18n): drop the stale per-update count log from the gate comment#180
argszero merged 1 commit into
mainfrom
docs/fix-stale-gate-count-comment

Conversation

@argszero

Copy link
Copy Markdown
Owner

Summary

Fix a doc comment that contradicts the constants directly beneath it.

src/i18n_pack.rs keeps six positive-control constants for the language-pack gate. The comment block above them described "本次更新" — the update that wrote it — with that release's numbers:

本次更新(共享页「本月新增」卡):783 → 786 = **+3 键** …
上一轮(运营概览「服务版本 / 运行时长」两张卡):775 → 783 键,520 → 531 / 418 → 426。

but the constants eleven lines below read:

const ZH_KEY_COUNT: usize = 785;   // comment says 786
const T_LITERAL_COUNT: usize = 537; // comment says 535
const T_LITERAL_DISTINCT: usize = 430; // comment says 429

C2015 wrote that narrative while setting 786/538/431; C2019 moved the constants to 785/537/430 and did not touch the prose. So for two commits the file has asserted two different "current" key counts, one line apart.

Why it survived: only the comment was wrong. The constants are internally consistent (the gate's own asserts pass), so cargo test stayed green — nothing asserts on prose. The stale half is the half a reader trusts when deciding what number to write next.

Changes

  • Removed the per-update narrative from the ZH_KEY_COUNT comment block.
  • Kept the orientation-independent rule it also carried (calibrate against the extractor's real output, never hand-compute) — that part cannot rot.
  • Recorded where the history now lives: git log -p src/i18n_pack.rs, instead of a copy maintained in the file.
  • Documented which set T_LITERAL_COUNT counts (the T() call-site total — neither the key count nor the distinct count; three different sets, pitfall 99).
  • Comment-only: src/i18n_pack.rs is a #[cfg(test)]-only module, so no production behaviour changes and no constant moves.

The replacement block deliberately contains no "old → new" notation. In this position that notation reads as an assertion about the current value, and the constants below are the only authority for that — the first attempt at this cleanup re-created exactly the confusion it removes, which the checker below caught.

Related Issue

No issue exists for this — found by sweeping Rust doc comments for checkable claims. Left empty rather than fabricating a reference.

Tests

  • cargo test165 passed / 0 failed
  • cargo fmt --check — clean
  • cargo clippy --all-targets -- -D warnings — clean, 0 warnings
  • Doc-block vs constants checker, before → after

The checker extracts every N -> M progression from the comment block above the constants and asks whether the right-hand side matches any constant. It is discriminating, not merely green:

run result
--source HEAD (before) exit 1 — 4 mismatches (claims 786 / 535 / 429 / 426 vs constants 785/537/430)
working tree (after) exit 0 — 0 claims, 0 mismatches
--self-test PASS — injects a fabricated claim and requires it to be caught

--self-test matters here: after the fix the real corpus is empty, so "0 mismatches" would otherwise be vacuously green (an always-passing check carries no information). The self-test injects a synthetic claim and asserts it is detected, proving the checker can still fail.

No unit test added: this is a comment-only fix with no behaviour to assert, and the repo deliberately carries no doc-linting toolchain (same call as #178 and #179).

Checklist

  • Branch naming follows convention (docs/)
  • Commit message uses Conventional Commits (docs(i18n): — scope is the module changed)
  • Single responsibility, minimal change (14 insertions / 9 deletions in one file)

`src/i18n_pack.rs`'s positive-control comment block described "本次更新" with
the numbers of the release that wrote it (the sharing 本月新增 card: 783 -> 786
keys, 531 -> 535 call sites, 426 -> 429 distinct) while the six constants directly
beneath it read 785 / 785 / 330 / 305 / 537 / 430. C2015 wrote that narrative and
C2019 moved the constants to 785/537/430 without touching it, so the comment has
contradicted its own code for two commits.

Why it survived: only the comment was wrong. The constants are internally
consistent, so `cargo test` stayed green throughout — there is no assertion on
prose.

Fix: delete the per-update narrative and keep only the orientation-independent
rule (calibrate against the extractor's real output, never hand-compute), which
cannot rot. Each cycle's delta belongs to the commit history
(`git log -p src/i18n_pack.rs`), not to a copy maintained in the file.

The replacement block deliberately contains no "old -> new" notation: in this
position that notation reads as an assertion about the current value, and the
constants below are the only authority for that. (Writing the clean-up this way
first re-created the confusion it removes — the checker flagged the fix itself.)

Also records which set T_LITERAL_COUNT counts: it is the T() call-site total,
neither the key count nor the distinct count (three different sets).

Comment-only change: src/i18n_pack.rs is a #[cfg(test)]-only module, so no
production behaviour changes and no constants move. 165 tests pass.

Co-authored-by: argszero <argszero@argszerodeMac-mini.local>
@argszero
argszero merged commit d2c7431 into main Sep 12, 2026
1 check passed
@argszero
argszero deleted the docs/fix-stale-gate-count-comment branch September 12, 2026 06:42
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