The docs' line citations point at code that has moved #1481
Labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
jaylouisw/packetforge#1481
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
The symptom
The docs cite the implementation constantly.
docs/SIMULATION.mdsays, of VLAN tagging:Line 1666 of
engine/simulator.jsis now BGP route application._emitFrame's definition is hundreds of lines further down, andwireTaggedlives 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
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 atsimulator.js:72-78and is defined at 103;_emitFrameat 1666-1680 and defined at 2661.Repaired
28 citations now point at the line where the named function is actually defined:
SIMULATION.mdengine/device.js:366-443engine/device.js:816routeTo()SIMULATION.mdengine/simulator.js:1666-1680engine/simulator.js:2661_emitFrameSIMULATION.mdengine/simulator.js:1392-1471engine/simulator.js:2407pingScion()UPSTREAM-DESIGN.mdmedia.js:562media.js:894derivePortHardware()UPSTREAM-DESIGN.mdvalidation.js:59validation.js:152SEVERITY_BY_CODEEach 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 originalengine/simulator.js:137,engine/simulator.js:228-260still points atresolveName()and stays.Tool, and its limit
npm run check:citationslists suspects with the distance, the symbol and the line it found;-- --strictexits 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:1090citingtest/bgp.test.js:452, which is a test body, while the sentence mentionsmkPath()— 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, anddocs/MAINTAINING.mdsays so in those words, including the false positive.Full suite: 238 suites, 8848 assertions, 0 failed. Syntax 307 files OK.
Landed as #1482 (
57a2f32d). Post-merge onmain:check:citationsreports 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.