Skip to content

trim stdlib comments - #128

Merged
alii merged 1 commit into
masterfrom
stdlib-tidy
Sep 24, 2026
Merged

alii merged 1 commit into
masterfrom
stdlib-tidy

Conversation

@alii

@alii alii commented Sep 24, 2026

Copy link
Copy Markdown
Member

The stdlib's comments, cut down, and every file run through scarlet fmt.

Comments: 3,052 lines → 1,046. The rule applied throughout: a comment earns its place by saying something the code cannot — a non-obvious why, an RFC rule that matters, a trap. What a name or a signature already said is gone, along with history notes ("used to", "the old VM", issue numbers) and // ---------- banners ----------. What is left is at most three lines, and a module's own doc at most ten.

The biggest cuts: wire.scrl 304 → 18, process.scrl 366 → 115, http.scrl 268 → 92, json/decode.scrl 216 → 53, http/client.scrl 204 → 72.

docs/wire-format.md is new. wire.scrl was 304 comment lines of 319, and most of it was the byte format: tags, layouts, the capture format, the fingerprint, the order refusals are checked in. Wire is not built on the new VM yet, and whoever rebuilds it will want that — so it moved to a doc, as tables and short prose, and the module doc points at it.

Formatting. All 40 files now pass scarlet fmt --check; 17 did not. A test in module/stdlib.rs keeps it that way: people read the stdlib to learn how Scarlet is written, so it should look like what the formatter produces. The two formatter fixes this turned up went in ahead of it (#126, #127).

Three imports nothing used are gone: int from http/form, result from json, option from oauth2.

Nothing else changed. Stripping comments and blank lines from every file, before and after, gives the same code apart from those three imports — and formatting only rewraps. One test in references.rs pinned a line number in array.scrl; it now reads the line out of the file, so editing a comment can never fail it for the wrong reason.

Not done here: examples/ and tests/programs/ are still unformatted, and their comments are untouched.

All seven CI gates pass locally. hawk ran for the host target, and nothing here is gated on a cfg.

@alii
alii merged commit 42eff5e into master Sep 24, 2026
4 checks passed
@alii
alii deleted the stdlib-tidy branch September 24, 2026 01:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant