docs: fix the four front-door examples that misrepresented the language#476
Merged
Merged
Conversation
The README and doc examples a newcomer reads first were wrong on the exact surfaces we lead with. Verified every corrected example against the real runtime (byte-true output shown): - README observer example (#313): `5,2,5,2` classified as `diverging`, not the claimed `oscillating` — four samples is too short. Extended to three periods (`5,2,5,2,5,2`) so it truly prints `oscillating`. This is the showcase of the observer, our whole differentiator; it printed the wrong trajectory. - README stdlib snippet (#319): `map of [[1,2,3], double]` referenced an undefined `double` and crashed with `undefined variable 'double'` on a reader's first copy-paste. Now defines `double` inline; prints [2,4,6]. - lib/format.eigs fmt_bar docstring (#320): showed `████░░░░░░`; actual output is `[######....] 60.0%`. Docstring now matches the runtime. - String-escape docs (#318): SYNTAX/GRAMMAR/LANGUAGE_CONTRACT implied a closed escape set `\n \t \r \\ \" \{ \}`. The lexer recognizes `\n \t \r \\ \"` and drops the backslash on any other `\x` (so `\{`/`\}` give literal braces via the catch-all, and `\r` was real but only documented in the contract). Docs now state the true contract. Docs-only; doc_drift_check.sh passes. Closes #313 Closes #319 Closes #320 Closes #318 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The first artifacts a stranger reads — the README and the intro docs — were wrong on the exact surfaces we lead with. Every corrected example was verified against the real runtime.
What was broken
oscillatingexample printsdiverging— the sequence is too short to ever classify as oscillating #313) —5,2,5,2 → report → "oscillating"actually printeddiverging(four samples is too short to classify). This is the showcase of the observer, our whole differentiator, printing the wrong trajectory. Extended to three periods so it truly printsoscillating.doubleand errors out (undefined variable 'double') #319) —map of [[1,2,3], double]referenced an undefineddoubleand crashed withundefined variable 'double'on a reader's first copy-paste. Now definesdoubleinline →[2, 4, 6].lib/format.eigsfmt_bar docstring (lib/format.eigsdocstring shows wrongfmt_baroutput (████░░░░░░vs actual[######....] 60.0%) #320) — showed████░░░░░░; actual output is[######....] 60.0%. Docstring now matches.\ris supported but undocumented;\{/\}are documented but only work via the catch-all branch #318) — SYNTAX/GRAMMAR/LANGUAGE_CONTRACT implied a closed set\n \t \r \\ \" \{ \}. The lexer recognizes\n \t \r \\ \"and drops the backslash on any other\x(so\{/\}yield literal braces via the catch-all;\rwas real but under-documented). Docs now state the true contract.Verification
All corrected examples run byte-true against the current runtime:
oscillatingexample printsdiverging— the sequence is too short to ever classify as oscillating #313 →oscillatingdoubleand errors out (undefined variable 'double') #319 →[2, 4, 6]lib/format.eigsdocstring shows wrongfmt_baroutput (████░░░░░░vs actual[######....] 60.0%) #320 →[######....] 60.0%\ris supported but undocumented;\{/\}are documented but only work via the catch-all branch #318 →\r→CR,\{/\}→{/},\q→q(catch-all confirmed)Docs-only;
tools/doc_drift_check.shpasses.Closes #313
Closes #319
Closes #320
Closes #318
🤖 Generated with Claude Code