docs: make the line-number convention match what is actually in the tree
The convention added in 166b77e said deployment.md was the only exception, but
opengaps.md, retired.md and design.md still carry 44 anchors and reference.md is
the file that actually lost its 56. State the policy as it is applied: symbol
names for anything new, deployment.md's 60 anchors kept because it is an
operator runbook, reference.md stays line-number-free, and the 44 legacy anchors
are neither added to nor cleaned up because those files rarely change.
This commit is contained in:
parent
166b77eb34
commit
390a850cba
|
|
@ -72,10 +72,11 @@
|
|||
- **行号锚点必须指向对应内容**,不能只指向「文件里那一行」。文档写「某文件第 120 行是
|
||||
重试上限」,第 120 行就必须是重试上限;行号漂移而描述跟着跑,比行号写错更危险。
|
||||
- **校验器只能证明「该行号存在且非空」,不能证明该行内容符合描述。** 内容级核对必须人工读。
|
||||
- **文档引用代码一律用符号名,不写行号。** 唯一例外是 `docs/deployment.md`(运维 runbook,
|
||||
事故中按行跳转)。行号随任何无关改动重排,而符号名稳定;`docs/reference.md` 曾有 56 个
|
||||
`notify.rs` 锚点,其中约 40 个落在闭合括号、注释行或错误的符号上,而门禁报 0 错,
|
||||
2026-09-29 决定彻底不维护行号。
|
||||
- **文档引用代码一律用符号名,不写行号。** 行号随任何无关改动重排,符号名稳定。
|
||||
`docs/deployment.md` 是既有例外(运维 runbook,事故中按行跳转,60 个锚点仍保留)。
|
||||
`docs/reference.md` 的 56 个 `notify.rs` 锚点里约 40 个落在闭合括号、注释行或错误符号上,
|
||||
而门禁报 0 错,2026-09-29 起全部删除、不再回补。opengaps / retired / design 里还剩 44 个
|
||||
存量锚点,**不再新增、也不刻意清理**——它们改动频率低,不值得为此动文档。
|
||||
- 需要定位到行时用 `grep` 符号名,不要用文档里的行号做判断依据。
|
||||
- `scripts/docs_check/audit_anchor_semantics.py` 是**独立脚本**,没接进 `run_all.sh`,
|
||||
恒 `exit 0`,只打印候选。它抓「锚点指向的行跟所声称的符号毫无关系」这类漂移,但抓不到
|
||||
|
|
|
|||
Loading…
Reference in New Issue