Check the docs' claims against the code mechanically

Translating everything into Chinese found four claims that had already drifted, and
none of them were caught by reading -- they were caught by comparing against source.
Proofreading does not find rot, so do the comparison mechanically and keep doing it.

tools/check_docs.py verifies that every tool a README names exists, that every test in
run_tests.sh is documented in both languages, that internal .md links resolve, that the
translation pairs have matching heading structure, that memory-map addresses match the
model's #defines, and that documented firmware file:line references still point at what
the prose claims. It runs in the quick tier of run_tests.sh, needing no emulator.

Confirmed it can actually fail, because a checker that cannot is worthless: renaming a
documented tool and deleting a heading from the Chinese side each produce one named
failure and exit 1, and reverting returns it to clean.

One thing it deliberately does not check. An early version compared firmware constants
with a regex that took the first number on a line, so `key_debounce_10ms = 20 / 10` read
as 20 and it declared the docs wrong for saying 2. The docs were right and the checker
was broken. A checker that cries wolf gets ignored, so claims it cannot verify
unambiguously are left out rather than guessed at.

Current state: 16 file:line references all accurate, 7 memory-map addresses all match,
zero broken links, all three translation pairs structurally aligned.
This commit is contained in:
mckero committed 2026-08-29 16:54:25 +01:00
1 parent 3df3c1b16d
commit b32335d8c0
6 files changed
+225

No files matched your search

+1
View File
@@ -84,6 +84,7 @@ VFO 重算了状态。在真机上你只看到"什么都没发生",在这里
test_battery.py 电量与低电告警跟随 ADC
test_millis.py millis() 会递增,超时才可能到期
test_spectrum.py RSSI 取决于调谐位置,不是常数
check_docs.py 文档的断言是否仍与代码一致
run_tests.sh 跑上面全部,先检查构建
test_run_tests.sh 验证 runner 真的能发现失败
lib_kill_emulator.sh 只杀模拟器的清理逻辑