docs: teach what 0.4.0 and 0.5.0 added, and correct what drifted - #66
Merged
Conversation
The course was written against a smaller language and a smaller library, so parts of it now describe a compiler that no longer behaves that way, and parts of it leave a learner unprepared for an error the compiler will actually raise. Wrong, and verified against the 0.5.0 binary: - Lesson 8's "a `let` cannot destructure a constructor" demo quoted an error that does not fire. `let Some x = Some 1` parses as a *function* named `Some` with parameter `x`, so it type-checks; the demo needs `let (Some x) = …`, and the parenthesized form is now shown with the reason the brackets matter. - Lesson 17 said a recursive function always shares Python's stack. A saturated self tail call has lowered to `while True` since #39, so the lesson now shows a hundred thousand levels of `countDown` running, and keeps the stack warning for the shape that still has one (`fact`, whose call sits under a `*`). - Four quoted typed-hole notes listed suggestions the stdlib sweep changed. Lesson 9's was worse than stale: it taught "the compiler names your answer" above a note where `String.upper` no longer appears, having been pushed past the six-fit cap by the new `string -> string` members. That exercise now normalizes case with `String.lower`, which the note does name, and the lesson says plainly that the list is a shortlist. - Lesson 18 called `async` the third built-in builder; it is the fourth. - Lesson 6 quoted emitted Python without the `_pf_t0` temporary a record update actually emits. - Lesson 5 defined `sign`, which shadows the prelude's `sign` and gives a student the wrong hover. Missing, in the order a learner hits them: - `extern import` was taught nowhere, yet since #50 a target like `sys.stdout.flush` is a hard compile error asking for exactly that line. Lesson 12 now walks the error and the fix. - Instance-access externs (`= .with_name`) were referenced by lesson 23 as something lesson 12 covers. Lesson 12 did not. Now it does, and the cross-reference is true. - Lesson 15 showed only values crossing a module boundary. Types cross too, and since the dogfooding fix a record may name another module's type, which is what lets a program split along its data. - `Seq` was used in lesson 13 before ever being introduced, and laziness was the one collection idea the course did not teach. Lesson 7 introduces it, along with the two conventions the sweep settled: total functions, and `Option` from any accessor that can come up empty. - `Format` was invisible outside quoted hole notes, and `input` was untaught, so "how do I read from the user" had no answer on the site. One compiler fix came out of writing that up: `Format.thousands` and `Format.grouped` had each other's hover documentation (`thousands` formats a float with grouping, `grouped` an integer), and the padding pair's docs omitted their fill argument.
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 course was written against a smaller language and a smaller library. Parts of it now describe a compiler that no longer behaves that way, and parts leave a learner unprepared for an error the compiler will actually raise. Everything below was checked by running it against the 0.5.0 binary.
Wrong
let Some x = Some 1reports "aletbinding must always match"parse_binding_targetonly enters the pattern grammar after(orIdent {, so this parses as a function namedSomewith parameterx. The demo needslet (Some x) = …, which does produce the quoted errorwhile Truesince #39.countDown 100000 0runs fineasync { }"_pf_t0temporary that is actually emittedlet sign nsign, so hovering it in an editor shows the built-in's docsLesson 9's stale note was the worst of them, because it broke the lesson's own point. It teaches "the compiler names your answer" directly above a note where
String.upperno longer appears: the sweep added enoughstring -> stringmembers that the intended answer is pushed pastHOLE_FIT_CAP = 6by the alphabetical tiebreak. The exercise now normalizes case withString.lower, which the note does name, and the lesson says plainly thattry:is a shortlist rather than the full set.Missing
Ordered by how soon a learner trips over it:
extern importwas taught nowhere. Since externs: refuse to guess an undecidable module prefix #50, a target likesys.stdout.flushis a hard compile error whose message asks for exactly that line. A learner following lesson 12's rule (extern name: Type = dotted.target) hits an error the course never mentions. Lesson 12 now walks the error and the fix.= .with_name) were referenced by lesson 23 as something "from lesson 12". Lesson 12 did not cover them. Now it does, and the cross-reference is true.Seqwas used in lesson 13 before being introduced anywhere, and laziness was the one collection idea the course did not teach. Lesson 7 now introduces it, with the two conventions the sweep settled: total functions that clamp, andOptionfrom any accessor that can come up empty.Formatwas invisible outside quoted hole notes, where a learner metFormat.padLeftas a suggestion for a module the course never named.inputwas untaught, so "how do I read from the user" had no answer on the site.One compiler fix
Writing the
Formatsection turned up thatFormat.thousandsandFormat.groupedcarry each other's hover documentation.thousands : int -> float<'u> -> stringformats a float with grouping andgrouped : int<'u> -> stringformats an integer, andMEMBER_DOCShad those two descriptions swapped. The padding pair's docs also omitted theirfillargument, which their signatures take. This is what LSP hover and the hole notes serve, so it is documentation that happens to live insrc/.Verification
python docs/verify_lessons.pypasses 23/23 against a fresh 0.5.0 build, andcargo test,cargo clippy --all-targets -- -D warningsandcargo fmt --checkare clean. Every new code block in this PR was run, not just checked.Best reviewed with whitespace off; the em dashes inside quoted compiler output are the compiler's own.