Repository navigation
docs(std): add the HTTP, JSON, regex and SQLite guide pages and correct the std module docs - #442
Merged
Merged
Conversation
Four pages that belong beside the existing data-structures page, ordered 2 to 5 in the std section: - regex: matching, captures, replacement, syntax, limits and what is not supported. - json: the JsonValue tree, the scalar writeRoot overloads and stringify. - http: the sans-IO parser, the serialization helpers and the blocking server. - sqlite3: connections, statements, transactions, errors and threading. Every claim was checked against std/ and every complete sample compiles as written; the two statement fragments follow the existing convention for excerpts in these pages.
- http and web: the handler sample held a `str` field, which makes the record a view, so it failed the `Send + Sync` bound of `Server::run` and of `Web::listen`. The committed e2e fixture already writes `static str`. - http: only a well-formed `HTTP/<digit>.<digit>` reaches `UNSUPPORTED_VERSION`; `writeResponse` refuses a head that already carries a framing header, so a chunked body writes its head with `writeHead`; an accept loop stops only on `EBADF` or `EINVAL`; the linger cap is 2 seconds or 1048576 bytes. - sqlite3: `open` returns the WAL pragma error instead of falling back, bindings survive `reset`, and the single panicking entry point is `SharedConnection::new`. The doc baseline moves with the text: five module docs changed, one line each.
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.
What
Two commits, both documentation only.
1. Four new pages in
docs/web/std/, ordered 2 to 5 beside the existing data-structures page. They coverstd::regex,std::json,std::httpandstd::sqlite3with the API surface, the formats and the limits each module actually implements.2. Five std module doc comments that were wrong. These feed the API package
ignis docpublishes with every release, so a wrong claim there ships:std/httpandstd/web: the handler sample held astrfield, which makes the record a view, so it failed theSend + Syncbound ofServer::runandWeb::listen. The committed e2e fixturestd_http_serve_connection.ignalready writesstatic str.std/http: only a well-formedHTTP/<digit>.<digit>reachesUNSUPPORTED_VERSION;writeResponserefuses a head that already carriesContent-LengthorTransfer-Encoding, so a chunked body writes its head withwriteHead; a worker's accept loop stops only onEBADForEINVAL; the linger cap is 2 seconds or 1048576 bytes.std/sqlite3:openreturns the WAL pragma error instead of falling back to the previous journal mode, bindings survivereset, and the single panicking entry point isSharedConnection::new.Verification
Every claim in the four pages was checked against
std/and every complete sample compiles as written. The two statement fragments follow the existing convention for excerpts in these pages; 16 of the 102 blocks already indocs/webare fragments of the same shape.With a compiler built from this tree (
ignis build):build/bin/ignis checkon each of the ten complete samples in the pages and the module docs: no errors.build/bin/ignis check-std: no errors.ignis fmt --checkon the five changed.ignfiles: clean.python3 scripts/selfhost_doc_parity.py --compiler build/bin/ignis: 8 identical, 0 different.test_cases/doc/__doc_baselines__/output__std_io_mod.jsonmoves with the five edited module docs, one line each.Follow-up found, not fixed here
Sweeping all 69
ignisblocks in the std module docs turned up around twenty that no longer compile against the current compiler:String::toStringandIo::printI32no longer resolve (math, number, ptr, result),TomlErroris not exported bystd::toml, thestd::jsonsample callswriteRootwith a&Stringreceiver, and several older pointer-era samples instd::libc,std::fsandstd::ffido not parse. Fixing them means deciding the current equivalent for each sample, so it belongs in its own PR.