The docs pointed at code that had moved #1482
No reviewers
Labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
jaylouisw/packetforge!1482
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "docs/citation-repair"
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?
What was wrong
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.What was 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.What changed
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.
Reviewer note: the repairs are mechanical but were read line by line; the one judgement call that the tool got wrong (the DNS row in
SIMULATION.md) is called out above and was left at its original, correct citations. No code changed — only numbers inside docs, plus one script, one npm task and one MAINTAINING section.The docs cite the implementation constantly. SIMULATION.md says, of VLAN tagging, that "`_emitFrame` sets `wireTagged`/`wireVid` from `classifyEgress`" and cites engine/simulator.js:1666-1680. Line 1666 is now BGP route application; _emitFrame is defined at 2661 and wireTagged lives in the frame builder at 84. A reader who follows that lands in the wrong subsystem and learns, correctly, that the prose cannot be checked. Measured: 348 citations, 150 naming a symbol, 28 of those more than 40 lines from the code they name - most by hundreds, several by nearly a thousand, because whole mechanisms landed above the cited functions. * 28 citations repaired to the line where the named function is actually defined, each only when the symbol had exactly one definition in that file (two definitions means the name is overloaded, and a guess would replace one wrong number with another). Definitions were matched as definitions, never as call sites. Every changed line was read; one repair was reverted by hand, because the DNS row's only call-shaped symbol is not its subject and its original pair of ranges still points at resolveName(); * scripts/check-doc-citations.js + `npm run check:citations` list suspects with the distance, the symbol and the line 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, allowing 40 lines of drift; * docs/MAINTAINING.md states the rule and the tool's limit in its own output: today's single suspect cites a test body while the sentence mentions 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. It is a diagnostic, not a gate, and the doc says so. Suite 238 suites, 8848 assertions, 0 failed. Syntax 307 files OK.