From 45fba49a0d08e7892cc13ef7a506f7df484cabad Mon Sep 17 00:00:00 2001 From: Kinflou Date: Tue, 3 Nov 2026 15:56:08 +0800 Subject: [PATCH] docs: check five reference pages against the code C ABI: vector counts after runtime#76 (76 cases), the revision checked, and a note that runtime#76 raised the jsonrpc@1 decode's core cost. Generator protocol: the html renderer, notes, and the generator's own version check. Conformance: the JSON comparison rules (exact decimals, runtime#72) and --timeout covering every case. inspect: the IR format stamp refusal. doc: open's html choice, --version's folder, an external renderer replacing the built-ins, nav.yml, the header and theme persistence, page titles, built versions' notes, and the format-stamp exit code. Refs ComlineProject/core#197 --- docs/docs/reference/c-abi.md | 11 ++++-- docs/docs/reference/conformance.md | 21 +++++++++-- docs/docs/reference/generator-protocol.md | 12 +++--- docs/docs/reference/tools/doc.md | 45 +++++++++++++++-------- docs/docs/reference/tools/inspect.md | 6 +++ 5 files changed, 68 insertions(+), 27 deletions(-) diff --git a/docs/docs/reference/c-abi.md b/docs/docs/reference/c-abi.md index 7ca76f8..ea2073e 100644 --- a/docs/docs/reference/c-abi.md +++ b/docs/docs/reference/c-abi.md @@ -14,7 +14,7 @@ transports, async and dispatch stay in each host. comments are the doc comments of the Rust source. - **Why it exists and what was decided:** [one protocol core](../proposals/shared-runtime-core/core-interface.md). -This page was written against runtime `main` at `cb41d31`. Where it and the +This page was checked against runtime `main` at `b101fe9`. Where it and the header disagree, the header is right. ## Version @@ -382,9 +382,9 @@ cbindgen --config cbindgen.toml --output include/comline.h (`tests/c/vectors.c`, C11 against `comline.h`) and Node (`js/test/vectors.test.mjs`, against the wasm32 build). C runs against the static library, the dynamic library, and the static library under ASan and UBSan. - - The cases are every one in `name-hash` (8), `handshake` (9), `envelope` + - The cases are every one in `name-hash` (8), `handshake` (13), `envelope` (8), `framing-datagram` (9), `framing-datagram2` (12) and `framing-jsonrpc` - (19): 65 in all. Each harness fails on any mismatch, and on a case count + (26): 76 in all. Each harness fails on any mismatch, and on a case count that differs from the vectors'. - The nine `datagram@1` cases have no connection form. For them the harness checks that the ABI refuses `datagram@1`. @@ -443,7 +443,10 @@ rustc 1.98.0. Message mode, a 16-byte payload: 16 B. - **`jsonrpc@1` decoding is its own cost.** It scans the frame with serde_json at about 2.8 instructions a byte (185,825 for 64 KiB, on the core). The - crossing adds the same 153 on top. + crossing adds the same 153 on top. Since these figures, + [runtime#76](https://github.com/ComlineProject/runtime/pull/76) made the + decoder check the `jsonrpc` version and the shape of `params`, which raised + the core side of the `jsonrpc@1` `feed`; the crossing is unchanged. - **runtime#60 cut it.** The overlap check was most of `encode_request`'s crossing. From the PR's body, measured locally at the same paths: `encode_request` `datagram@2` 965 to 742, `feed` `datagram@2` 319–327 to diff --git a/docs/docs/reference/conformance.md b/docs/docs/reference/conformance.md index b80c67d..000f62f 100644 --- a/docs/docs/reference/conformance.md +++ b/docs/docs/reference/conformance.md @@ -68,7 +68,7 @@ A case is one operation and the bytes it must produce: | `input` | the operation's input | | `bytes` | the encoded form, lowercase hex | | `expect` | optional: `"reject"` means decoding `bytes` must fail; the input then names only what selects the decoder (the framing) | -| `compare` | optional: `"json"` compares JSON text as JSON (RFC 8259) instead of byte for byte | +| `compare` | optional: `"json"` compares JSON text as JSON (RFC 8259) instead of byte for byte; see [Comparing as JSON](#comparing-as-json) | - **Bytes** are lowercase hex. - **64-bit and wider integers** (`ir_hash`, `request_id`, `u64`, `i64`, `u128`, @@ -95,6 +95,20 @@ A case is one operation and the bytes it must produce: A framing is proven with `request` and `response` cases; a format with `encode` and `decode` cases. +### Comparing as JSON + +A case with `"compare": "json"` holds bytes that are JSON text (a JSON value, +or a JSON-RPC frame). An encode passes when its output equals `bytes` as JSON: + +- Whitespace and member order don't matter. +- **Numbers compare as exact decimals:** `1` equals `1.0`, but + `9007199254740992` doesn't equal `9007199254740993`, though both read as the + same double ([runtime#72](https://github.com/ComlineProject/runtime/pull/72)). +- Strings compare by the text they hold, however they're escaped: + `"app.Chat\/count"` equals `"app.Chat/count"`. +- The same holds for JSON inside a frame: JSON-RPC params, results and error + data. + Values and types are written in a typed encoding (`{"u8": 255}`, `{"struct": {"name": "Point", "fields": [...]}}`, and so on). The full list is in the @@ -206,8 +220,9 @@ comline conformance --impl "" [--encoding ]... [--corpus //`, so the site's shared files are at `../`. Absent for a site of its own. | | `versions` | set for a site's index render: every version, oldest first, each `{ id, release, kind, model }`. `release` is the release a dev build leads to (`0.3.0` for `0.3.0-dev.2`), itself for a release, `unreleased` for the working tree; `kind` is `release`, `dev` or `unreleased`; `model` is that version's model as JSON, with its `changelog` from the version before it in the list. The files land at the site's root, and the request's own `model` is the newest version's. | -| `notes` | plain-text notes for every page of this version: what an old version's documentation lacks | +| `notes` | plain-text notes for every page of this version: what a built version's documentation lacks (headers, for one built before they were stored; wire summaries, which no built version records yet) | A renderer accepts every option and ignores the ones it has no use for. The answer is `Render(Generated)`: files, checked like a generator's. @@ -155,7 +155,8 @@ target's version. - **Describe:** the CLI's protocol version must be inside `protocols`, and its IR format must be in `ir_formats`. Otherwise it refuses the generator and names - both sides. + both sides. The other way round, `serve_stdio` answers a request whose + `protocol` or `ir_format` isn't its own with an `Error` naming both. - **Language:** the generator must offer the target's language at the target's version, or the CLI refuses it. - **Renderer:** for `comline doc`, the program must list the format in @@ -201,5 +202,6 @@ The `comline_codegen::protocol` module exports: `handle`, which does the same on bytes; - `serve_stdio(registry)`: a generator process's whole `main`. A registry holds renderers too (`Registry::register_renderer`), so one binary can - generate, render, or both. The official Markdown renderer is - `comline-doc-markdown` in the generation repository. + generate, render, or both. The official renderers are + `comline-doc-markdown` and `comline-doc-html` in the generation repository; + both are linked into `comline` and both set `sites`. diff --git a/docs/docs/reference/tools/doc.md b/docs/docs/reference/tools/doc.md index 4cd18b3..f91462c 100644 --- a/docs/docs/reference/tools/doc.md +++ b/docs/docs/reference/tools/doc.md @@ -15,9 +15,9 @@ walkthrough, see [Documenting your schemas](../../guide/documenting.md). | Flag | Default | Meaning | |---|---|---| | `--out ` | `[doc] out`, else `docs/api` | Where to write, relative to the project. | -| `--version ` | every version | Document only this built version, into `///`: a version string, a commit hash (4+ characters), or `HEAD`. | +| `--version ` | every version | Document only this built version, into its version's folder, `///`: `` is a version string, a commit hash (4+ characters), or `HEAD`. | | `--changelog-from ` | `[doc] changelog_from` | With `--version`: add what changed from built version `` to the documented one. | -| `--format ` | `[doc] formats`, else `markdown` | `markdown`, `html`, `json`, or another renderer id `[doc] renderer` offers. Repeat it, or separate formats with commas. | +| `--format ` | `[doc] formats`, else `markdown` | `markdown`, `html`, `json`, or another renderer id `[doc] renderer` offers. Repeat it, or separate formats with commas. With `[doc] renderer` set, every format but `json` comes from that renderer ([External renderers](#external-renderers)). | | `--open` | off | After rendering, open the first format's index, as `comline doc open` does. With `--version`, it opens that version's own `index.html` or `index.md` (`model.json` for `json`). | ## Opening the result @@ -27,8 +27,8 @@ system's default handler: `//index.html`, `index.md` or `index.json`, for `html`, `markdown` or `json`. `--out` is read as `comline doc` reads it. -- With no ``, it opens `html` if that is among `[doc] formats`, else - the first configured format. +- With no ``, it opens `html` if that is among `[doc] formats` or + `/html/index.html` is already there, else the first configured format. - If the file isn't there, it renders that format first, exactly as `comline doc --format ` would. If it is, it opens it as it is, without re-rendering, and says so in one line with how to refresh it @@ -71,7 +71,8 @@ docs/api/ ``` - A dev build's folder is its full version (`0.2.0-dev.1`), and it belongs to - the release it leads to (`0.2.0`). + the release it leads to (`0.2.0`). A version built more than once keeps its + newest build. - The working tree appears as `unreleased` only when its schemas or headers differ from the last build. With nothing built, it is the only version. - Each version carries the changelog from the version before it in the list @@ -112,7 +113,7 @@ version's folder: | `.md` | Per schema (`types::user` → `types/user.md`): its `//!` header, a table of its declarations (Item, Summary, then Type and Value, each only when some declaration in the module has one: a constant's type and value, a type alias's target), then each one with its `///` docs, annotations, fields and arguments (a field's own docs, else its parent's `/// @name:` line), enum variants, an error's ordinal and message, a validator's targets, parameters and asserts, and each protocol's functions and wire summary. | | `changelog.md` | With a changelog: breaking changes, additions and other changes. Each entry is a heading line (its severity, `MAJOR`, `MINOR` or `PATCH`, and a title such as `` `Orders.place`: signature changed `` linking to the declaration), then the change as a fenced `diff` block: the old IDL line with `-`, the new with `+`. An addition has only the `+` line, a removal only the `-` line, and a change with no IDL to show (a docstring, an error's ordinal, guarantees) a sentence instead. A release shows its changes since the previous release; a dev build its step, then a link to its changes since the last release, listed below it. | | `deps//.md` | Per module of a dependency without a published base URL: what the package reaches of it, as `.md`. | -| `nav.yml` | A `nav` list for mkdocs or zensical: the package's modules, then a `Dependencies` section (a dependency's pages, or its published base URL). | +| `nav.yml` | A `nav` list for mkdocs or zensical: the overview (`index.md`), the package's modules, then a `Dependencies` section (a dependency's pages, or its published base URL), then `Changelog` when there is one. | `/markdown/index.md` lists the versions, newest first, grouped by release. There is no version picker: switching versions on a published site is left to @@ -151,7 +152,8 @@ writes a self-contained static site per version with the same content: | `search.js` | The search index (each declaration's name, kind, module and first line of docs), inlined as data, and the search box's script. | Every page has a header with the package's name (the version is in the -picker beside it), a search box, a theme toggle and a version picker, and a +picker beside it), a version picker with a link to `compare.html`, a search +box and a theme toggle, and a sidebar: the package's modules and their declarations, then a Dependencies section, collapsed unless the page is a dependency's, with one group per dependency. A group links to the dependency's published docs when it has a @@ -173,9 +175,14 @@ Changelog The header and sidebar work like this: - The theme toggle cycles auto (the OS setting), light and dark. The choice is - kept in the browser's `localStorage` where it's allowed, so it carries across - pages and versions, and is applied before the page paints. Where storage is - blocked it lasts for the page. + applied before the page paints, and carries across pages and versions: it is + kept in `localStorage` where that's allowed, and also in the tab + (`window.name`) and on internal links (`?theme=`), so it follows the reader + under `file://`, where some browsers give each file its own storage, and into + a page opened in a new tab. +- A page's title is ` - package - Comline` (`Schema types::user`, + `Changelog`, `Compare`), or `package - Comline` for the overview. It + carries no version. - The picker is a native drop-down, newest first, with dev builds grouped under the release they lead to, and a Go button. Choosing a version with the mouse @@ -232,10 +239,13 @@ fields. `dependencies` lists what the package reaches of each dependency A built version's model comes from its frozen IR and the `//!` headers stored with it. A built version keeps no source, so: -- its protocols have no wire summary. +- its protocols have no wire summary + ([core#153](https://github.com/ComlineProject/core/issues/153)); +- a version built before headers were stored + ([core#152](https://github.com/ComlineProject/core/pull/152)) has no headers. -A version built before headers were stored has no headers. Each page of such a -version opens with a note saying what it lacks, in both formats. +Each page of such a version opens with a note saying what it lacks, in +`markdown` and `html`. ## External renderers @@ -243,7 +253,9 @@ version opens with a note saying what it lacks, in both formats. [generator protocol](../generator-protocol.md#render), and runs like an external generator: a `.wasm` under wasmtime with no filesystem, environment or network, a native executable with an empty environment, the same time limit -(`[doc] timeout`, 60 seconds), output caps and path checks. `comline` asks it +per call (`[doc] timeout`, 60 seconds), output caps and path checks. It takes +the built-ins' place: every format but `json`, `markdown` and `html` included, +is asked of it. `comline` asks it to describe itself first and refuses it unless it lists the format, at the model version this `comline` writes, in its `renderers`. It renders each version's folder with one `Render` each. The site's index is asked for only @@ -254,4 +266,7 @@ folders alone. `0` on success. `1` when the package doesn't compile, a version doesn't exist, or the renderer refuses or fails. `2` when `--version` or `--changelog-from` is -given and the project was never built. +given and the project was never built, or when `.comline/` was written in +another IR format: `comline doc` checks the store's +[IR format stamp](../../guide/ir/cas.md#the-ir-format-stamp) before reading any +built version, and `comline build` rebuilds the store in the current format. diff --git a/docs/docs/reference/tools/inspect.md b/docs/docs/reference/tools/inspect.md index 7671323..0234264 100644 --- a/docs/docs/reference/tools/inspect.md +++ b/docs/docs/reference/tools/inspect.md @@ -8,6 +8,12 @@ comline inspect [--json] [guarantees](../../guide/idl/protocol.md#giving-up-a-guarantee) it keeps. Like `comline check`, it compiles the package and writes nothing to `.comline/`. +It reads the latest build's facts from `.comline/`, so it first checks the +store's [IR format stamp](../../guide/ir/cas.md#the-ir-format-stamp). A store +written in another IR format is refused, exiting `2`, with a hint to run +`comline build`, which rebuilds it in the current format. A project never built +has no store to check, and shows no facts. + ## What it shows For each protocol, the package's own and then its dependencies':