Skip to content

docs(std): add the HTTP, JSON, regex and SQLite guide pages and correct the std module docs - #442

Merged
0xErwin1 merged 2 commits into
mainfrom
docs/std-module-pages
Nov 2, 2026
Merged

0xErwin1 merged 2 commits into
mainfrom
docs/std-module-pages

Conversation

@0xErwin1

@0xErwin1 0xErwin1 commented Nov 2, 2026

Copy link
Copy Markdown
Collaborator

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 cover std::regex, std::json, std::http and std::sqlite3 with 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 doc publishes with every release, so a wrong claim there ships:

  • std/http and std/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 Web::listen. The committed e2e fixture std_http_serve_connection.ign already writes static str.
  • std/http: only a well-formed HTTP/<digit>.<digit> reaches UNSUPPORTED_VERSION; writeResponse refuses a head that already carries Content-Length or Transfer-Encoding, so a chunked body writes its head with writeHead; a worker's accept loop stops only on EBADF or EINVAL; the linger cap is 2 seconds or 1048576 bytes.
  • std/sqlite3: open returns the WAL pragma error instead of falling back to the previous journal mode, bindings survive reset, and the single panicking entry point is SharedConnection::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 in docs/web are fragments of the same shape.

With a compiler built from this tree (ignis build):

  • build/bin/ignis check on each of the ten complete samples in the pages and the module docs: no errors.
  • build/bin/ignis check-std: no errors.
  • ignis fmt --check on the five changed .ign files: clean.
  • python3 scripts/selfhost_doc_parity.py --compiler build/bin/ignis: 8 identical, 0 different. test_cases/doc/__doc_baselines__/output__std_io_mod.json moves with the five edited module docs, one line each.

Follow-up found, not fixed here

Sweeping all 69 ignis blocks in the std module docs turned up around twenty that no longer compile against the current compiler: String::toString and Io::printI32 no longer resolve (math, number, ptr, result), TomlError is not exported by std::toml, the std::json sample calls writeRoot with a &String receiver, and several older pointer-era samples in std::libc, std::fs and std::ffi do not parse. Fixing them means deciding the current equivalent for each sample, so it belongs in its own PR.

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.
@0xErwin1
0xErwin1 merged commit fcb0040 into main Nov 2, 2026
9 checks passed
@0xErwin1
0xErwin1 deleted the docs/std-module-pages branch November 2, 2026 13:36
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