The docs' line citations point at code that has moved #1481

Closed
opened 2026-11-12 04:43:05 +00:00 by jaylouisw · 1 comment
Owner

The symptom

The docs cite the implementation constantly. docs/SIMULATION.md says, of VLAN tagging:

Frames are really tagged on the wire: _emitFrame sets wireTagged/wireVid from classifyEgress … | engine/simulator.js:1666-1680

Line 1666 of engine/simulator.js is now BGP route application. _emitFrame's definition is hundreds of lines further down, and wireTagged lives at line 84 in the frame builder. The reader who follows that citation lands in the wrong subsystem and learns, correctly, that the prose cannot be checked.

Measured

citations in docs:              348
  of which name a symbol:       150
  pointing >40 lines away:       28

Most are hundreds of lines off; the worst are near a thousand, because whole mechanisms landed above the cited functions and pushed them down. Two examples from the same page: portPvid() was cited at simulator.js:72-78 and is defined at 103; _emitFrame at 1666-1680 and defined at 2661.

Repaired

28 citations now point at the line where the named function is actually defined:

doc was is symbol
SIMULATION.md engine/device.js:366-443 engine/device.js:816 routeTo()
SIMULATION.md engine/simulator.js:1666-1680 engine/simulator.js:2661 _emitFrame
SIMULATION.md engine/simulator.js:1392-1471 engine/simulator.js:2407 pingScion()
UPSTREAM-DESIGN.md media.js:562 media.js:894 derivePortHardware()
UPSTREAM-DESIGN.md validation.js:59 validation.js:152 SEVERITY_BY_CODE
… 23 more

Each was repaired only when the symbol had exactly one definition in the cited file — a name with two definitions is overloaded, and guessing would replace one wrong number with another. Definitions were matched as definitions (function x(, x(…) {, const x =), never as call sites, because a call site is not the thing the sentence is about. Every changed line was read before it was kept, and one repair was reverted by hand: the DNS row cites two ranges for name resolution, and the only call-shaped symbol in the sentence (openFlow()) is not its subject — the original engine/simulator.js:137, engine/simulator.js:228-260 still points at resolveName() and stays.

Tool, and its limit

npm run check:citations lists suspects with the distance, the symbol and the line it found; -- --strict exits 1. It judges a citation only when the sentence names exactly one function as a call, gives exactly one citation, and that function has exactly one definition in the cited file — a citation may sit up to 40 lines away.

It is a diagnostic, not a CI gate, and its own output shows why. Today's single suspect is docs/BGP-POLICY.md:1090 citing test/bgp.test.js:452, which is a test body, while the sentence mentions mkPath() — a helper defined 400 lines above. A rule that flagged that would be wrong; a rule narrow enough to be right judges 15 of 348. Judging the rest needs a reader. So the tool narrows the search and a human decides, and docs/MAINTAINING.md says so in those words, including the false positive.

Full suite: 238 suites, 8848 assertions, 0 failed. Syntax 307 files OK.

## The symptom The docs cite the implementation constantly. `docs/SIMULATION.md` says, of VLAN tagging: > Frames are really tagged on the wire: `_emitFrame` sets `wireTagged`/`wireVid` from `classifyEgress` … | `engine/simulator.js:1666-1680` Line 1666 of `engine/simulator.js` is now BGP route application. `_emitFrame`'s definition is hundreds of lines further down, and `wireTagged` lives at line 84 in the frame builder. The reader who follows that citation lands in the wrong subsystem and learns, correctly, that the prose cannot be checked. ## Measured ``` citations in docs: 348 of which name a symbol: 150 pointing >40 lines away: 28 ``` Most are hundreds of lines off; the worst are near a thousand, because whole mechanisms landed *above* the cited functions and pushed them down. Two examples from the same page: `portPvid()` was cited at `simulator.js:72-78` and is defined at 103; `_emitFrame` at 1666-1680 and defined at 2661. ## Repaired 28 citations now point at the line where the named function is actually defined: | doc | was | is | symbol | |---|---|---|---| | `SIMULATION.md` | `engine/device.js:366-443` | `engine/device.js:816` | `routeTo()` | | `SIMULATION.md` | `engine/simulator.js:1666-1680` | `engine/simulator.js:2661` | `_emitFrame` | | `SIMULATION.md` | `engine/simulator.js:1392-1471` | `engine/simulator.js:2407` | `pingScion()` | | `UPSTREAM-DESIGN.md` | `media.js:562` | `media.js:894` | `derivePortHardware()` | | `UPSTREAM-DESIGN.md` | `validation.js:59` | `validation.js:152` | `SEVERITY_BY_CODE` | | … | 23 more | | | Each was repaired only when the symbol had **exactly one definition** in the cited file — a name with two definitions is overloaded, and guessing would replace one wrong number with another. Definitions were matched as definitions (`function x(`, `x(…) {`, `const x =`), never as call sites, because a call site is not the thing the sentence is about. Every changed line was read before it was kept, and one repair was reverted by hand: the DNS row cites two ranges for name resolution, and the only call-shaped symbol in the sentence (`openFlow()`) is not its subject — the original `engine/simulator.js:137`, `engine/simulator.js:228-260` still points at `resolveName()` and stays. ## Tool, and its limit `npm run check:citations` lists suspects with the distance, the symbol and the line it found; `-- --strict` exits 1. It judges a citation only when the sentence names exactly one function as a call, gives exactly one citation, and that function has exactly one definition in the cited file — a citation may sit up to 40 lines away. **It is a diagnostic, not a CI gate, and its own output shows why.** Today's single suspect is `docs/BGP-POLICY.md:1090` citing `test/bgp.test.js:452`, which is a *test body*, while the sentence mentions `mkPath()` — a helper defined 400 lines above. A rule that flagged that would be wrong; a rule narrow enough to be right judges 15 of 348. Judging the rest needs a reader. So the tool narrows the search and a human decides, and `docs/MAINTAINING.md` says so in those words, including the false positive. Full suite: 238 suites, 8848 assertions, 0 failed. Syntax 307 files OK.
Author
Owner

Landed as #1482 (57a2f32d). Post-merge on main: check:citations reports 351 citations, 15 judged, 1 suspect (the known false positive documented in MAINTAINING.md), tree clean.

The honest limit is recorded where the next person will meet it: a mechanical rule that is sound judges 15 of 351, and the one rule loose enough to judge more flags a test body as drift. So the repair is the deliverable and the tool narrows the search — the judgement stays with a reader.

Landed as #1482 (`57a2f32d`). Post-merge on `main`: `check:citations` reports 351 citations, 15 judged, 1 suspect (the known false positive documented in MAINTAINING.md), tree clean. The honest limit is recorded where the next person will meet it: a mechanical rule that is sound judges 15 of 351, and the one rule loose enough to judge more flags a test body as drift. So the repair is the deliverable and the tool narrows the search — the judgement stays with a reader.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge#1481
No description provided.