Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/std-drift.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
name: Std drift

# The pages under `docs/docs/reference/schema/std/` are not written by hand: they are `comline
# The pages under `docs/docs/reference/package/schema/std/` are not written by hand: they are `comline
# doc` run over the standard library package core embeds
# (`core_stdlib/packages/std`), and the std block of `docs/mkdocs.yml` is its
# generated nav. This regenerates both and fails on a difference, so a
Expand All @@ -19,7 +19,7 @@ on:
- cron: '15 7 * * 1'
pull_request:
paths:
- 'docs/docs/reference/schema/std/**'
- 'docs/docs/reference/package/schema/std/**'
- 'docs/mkdocs.yml'
- 'scripts/sync-std-docs.py'
- '.github/workflows/std-drift.yml'
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/conduct/language-implementation/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,4 @@ you want the detail; this page just needed to say it exists.

## How is a language mantained

Test
Test
4 changes: 2 additions & 2 deletions docs/docs/conduct/readiness.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ Semver for a user's schema package means nothing until a break is defined.

- The C ABI's structs, status codes and flags are final for 1.x, including
`comline_connection_size`/`init` and whether a `comline@2` changes the event
struct ([C ABI](../reference/c-abi.md)).
struct ([C ABI](../reference/languages/c-abi.md)).
- The IR and `config.idp` formats are stable, or versioned with a reader for
every older version
([core#146](https://github.com/ComlineProject/core/issues/146)).
Expand All @@ -84,7 +84,7 @@ Semver for a user's schema package means nothing until a break is defined.
corpus and ops protocol;
- the documentation model behind [`comline doc`](../reference/tools/cli/doc.md)
(version 1 today);
- the [`comline.toml` schema](../reference/package/congregation/comline-toml.md)
- the [`comline.toml` schema](../reference/package/comline-toml.md)
(`0.x` today);
- the JSON from [`comline inspect --json`](../reference/tools/cli/inspect.md).
- The extension API is part of 1.0, so it is designed, built and frozen
Expand Down
8 changes: 4 additions & 4 deletions docs/docs/design/consumer-generation-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Status: **core feature shipped** · `ComlineProject/core` + `ComlineProject/cli` · Relates to core#6, core#8, cli#1

| Piece | State |
|---|---|
| --- | --- |
| Drop frozen `generation_path` + core-side codegen | ✅ merged (core#25) |
| Drop frozen `package_versions` from the congregation | ✅ merged (core#26) |
| `comline.toml` `[generate]`, `--out`/`--layout`/`--mode`, `generate` no longer freezes, `clean`/`new`/`watch` | ✅ merged (cli#10) |
Expand Down Expand Up @@ -39,7 +39,7 @@ local path choice perturb the package's identity.
## Two files, two owners

| File | Owner | Format | Frozen into CAS | Purpose |
|---|---|---|---|---|
| --- | --- | --- | --- | --- |
| `config.idp` (congregation) | package **author** | `.idp` | yes (interpreted → `Vec<FrozenUnit>`) | package identity + declarations: name, `specification_version`, `dependencies`, `publish_registries`, and the codegen **capability declaration** `code_generation.languages` = "this package *can* be generated as `rust#1.70`, `python#3.11`" |
| `comline.toml` | package **consumer** | TOML | **no** — never enters freezing or CAS | *what this checkout generates, in what mode, and where* |

Expand Down Expand Up @@ -205,7 +205,7 @@ schemas. What is *not* in a commit:
or reordered mid-list.

So the CAS store covers only **half** of a state-freezing story: version history
+ diff-driven auto-versioning, i.e. the "track past/present state" half. It does
- diff-driven auto-versioning, i.e. the "track past/present state" half. It does
**not** yet cover the "make a rebuild reproducible" half — freezing configuration
and pinning imported / dependency schemas. For that, a version's tree needs (at
least) the frozen config committed back alongside the schema entries, and — once
Expand All @@ -228,7 +228,7 @@ units that affect that API feed the bump. The rest are *recorded* (for
reproducibility) but *not diffed*.

| Frozen config unit | Change | Version bump |
|---|---|---|
| --- | --- | --- |
| `Dependency` | **removed**, or **version changed** | **major** — conservative: without dependency resolution we cannot tell a compatible dep bump from a breaking one, and a dep's schema shapes are part of this package's effective surface. Refine later (dep-major → major, dep-minor → minor) once core#6 can diff dep schemas. |
| `Dependency` | **added** | **minor** — additive; the schema content that uses the new dep already carries its own minor/major. |
| `Dependency` | `uri` / `hash` only, same version | **patch** — provenance, not API. |
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/design/validators.md
Original file line number Diff line number Diff line change
Expand Up @@ -257,7 +257,7 @@ left to right, parenthesising each comparison.
Whether decode runs the checks is the **consumer's** call, not the schema's — it
changes the shape and cost of generated decode (a clone per decode, no "parse
now, validate later"), which is a codegen concern. So it's a `[generate]` key in
the consumer's [`comline.toml`](../reference/package/congregation/comline-toml.md), overridable per
the consumer's [`comline.toml`](../reference/package/comline-toml.md), overridable per
`[[generate.target]]`, slotting into the existing
`defaults → [generate] → [[generate.target]] → env → CLI` precedence:

Expand All @@ -279,7 +279,7 @@ validate_on_decode = "collect"
in its `TryFrom`); `"off"` leaves decode untouched.
- Matching `COMLINE_GENERATE_VALIDATE_ON_DECODE` env var and
`--validate-on-decode` flag, like the other `[generate]` keys.
- Folds into [`comline.toml`](../reference/package/congregation/comline-toml.md) when 4c ships.
- Folds into [`comline.toml`](../reference/package/comline-toml.md) when 4c ships.

### Decided

Expand Down
4 changes: 2 additions & 2 deletions docs/docs/developer/extending/encodings.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,9 +94,9 @@ still a [proposal](../../proposals/schema-compatibility.md#encoding-profiles).
For the official profiles, see the
[runtime's `profiles/`](https://github.com/ComlineProject/runtime/tree/main/runtime/conformance/profiles).

## 3. Write vectors, and prove an implementation
## 3. Writing vectors

**Vectors** are byte-exact cases. They sit beside the profile: the profile's
**Vectors** are byte-exact cases that prove an implementation. They sit beside the profile: the profile's
path with `.json` replaced by `.vectors.json`, so `profiles/lines.json` has
`profiles/lines.vectors.json`.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ comline generation

Targets come from `code_generation.languages` in `config.idp` (the scaffold
declares `rust#1.85.0`, the Rust generator's floor); output lands under `generated/` by default. Change where
and how in [`comline.toml`](reference/package/congregation/comline-toml.md):
and how in [`comline.toml`](reference/package/comline-toml.md):

```toml title="comline.toml"
[generate]
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/guides/codegen/generating-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -267,7 +267,7 @@ using cross-schema references in `code` mode needs to declare matching `mod`
statements itself.

`std` is the exception, because
[`external_std`](../../reference/package/congregation/comline-toml.md#external_std)
[`external_std`](../../reference/package/comline-toml.md#external_std)
is on by default in `lib` mode: a std type then resolves to
`comline_std::http::Request` and the crate depends on `comline_std` rather
than carrying a copy of it.
Expand All @@ -293,7 +293,7 @@ An alias imports the name the other module actually exports
nothing refers to produces no import at all.

`std` again resolves to its own package when
[`external_std`](../../reference/package/congregation/comline-toml.md#external_std)
[`external_std`](../../reference/package/comline-toml.md#external_std)
is on, by subpath import — the leading `std` segment drops, since
`@comline/std` is its own package root:

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/guides/codegen/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ detail that the generated code is pleasant to use directly rather than only as a
## Using it

`comline generation` is the command; [Generating code](generating-code.md) is the
full guide, and [`comline.toml`](../../reference/package/congregation/comline-toml.md) is where a
full guide, and [`comline.toml`](../../reference/package/comline-toml.md) is where a
consumer sets the output location, layout and mode.

Today there are `rust` and `typescript` generators, and both do `code` and
Expand Down
6 changes: 3 additions & 3 deletions docs/docs/guides/codegen/library-generation.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ the module layout. A planned third mode, `dylib`, would compile it to a library
any language's [runtime](../runtime/index.md) can load.

`comline generation`'s `mode` chooses how far generation goes. It is set per target
in [`comline.toml`](../../reference/package/congregation/comline-toml.md) (`[generate] mode` or
in [`comline.toml`](../../reference/package/comline-toml.md) (`[generate] mode` or
`[[generate.target]] mode`).

| `mode` | Output | Status |
Expand Down Expand Up @@ -71,7 +71,7 @@ import { Greeting } from "my-api/types";
Comline's standard library is implicitly part of every package, so without
help a `lib` build would vendor `std/http` and `std/validators` into every
generated package. It doesn't:
[`external_std`](../../reference/package/congregation/comline-toml.md#external_std)
[`external_std`](../../reference/package/comline-toml.md#external_std)
defaults to **on** in `lib` mode, so std's schemas are left out and the
manifest depends on std's own pre-generated package instead —
`comline_std` for rust, `@comline/std` for typescript. Your own nested
Expand All @@ -89,7 +89,7 @@ with a message naming the pair.
In either language, `<language>/` keeps this target's package from colliding
with another `lib` target sharing the same `out`; a target with `out` to
itself can set
[`flatten = true`](../../reference/package/congregation/comline-toml.md#flatten) to skip that and
[`flatten = true`](../../reference/package/comline-toml.md#flatten) to skip that and
land the package straight into `out`. `layout` plays no part in any of this —
it only applies to `code` mode. Multi-version `lib` output is not done yet.

Expand Down
8 changes: 4 additions & 4 deletions docs/docs/guides/documenting.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,7 @@ the declarations your own use, and what those use in turn, never the whole
dependency. Each dependency gets its own pages (`deps/<package>/<module>`), and
a type from it links there.

`std` links to its hosted docs instead, `https://comlineproject.github.io/docs/reference/schema/std/`.
`std` links to its hosted docs instead, `https://comlineproject.github.io/docs/reference/package/schema/std/`.
To link another dependency to its published docs rather than render pages for
it, give it a base URL in `comline.toml`:

Expand Down Expand Up @@ -211,7 +211,7 @@ and every path it returns is checked before anything is written.

## Settings

Every flag has a `[doc]` key in [`comline.toml`](../reference/package/congregation/comline-toml.md#doc),
Every flag has a `[doc]` key in [`comline.toml`](../reference/package/comline-toml.md#doc),
and the flag wins:

| Key | Flag | Default |
Expand All @@ -226,8 +226,8 @@ and the flag wins:
## The standard library, rendered

When rendering documentation of a package that uses any standard library types,
the built documentation will link to [`std` pages](../reference/schema/std/index.md), meaning
the built documentation will link to [`std` pages](../reference/package/schema/std/index.md), meaning
that the links will always lead to online

A type from `std` in your own docs links to them by default, so `std::http::Request` in a field's type links
to `https://comlineproject.github.io/docs/reference/schema/std/http/#request`.
to `https://comlineproject.github.io/docs/reference/package/schema/std/http/#request`.
2 changes: 1 addition & 1 deletion docs/docs/guides/idl/annotations.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ build.
| `@deprecated` | a struct, a `type` alias | warns wherever it's used; the value is `true` or a message | [Types](types.md#type-aliases) |
| `@settings` | any declaration | applies a named settings preset | [Settings](settings.md#named-presets-settings) |
| `@framing` | a protocol | how calls are framed on the wire | [Protocols](protocol.md#annotations) |
| `@handshake` | a protocol | what runs before the first call, with [its parameters](../../reference/wire/handshakes/index.md#parameters) if it takes any | [Protocols](protocol.md#annotations) |
| `@handshake` | a protocol | what runs before the first call, with [its parameters](../../reference/wire/handshakes/comline@2.md#parameters) if it takes any | [Protocols](protocol.md#annotations) |
| `@provider` | a protocol | which side implements it: `Server`, `Client` or `Multiple` | [Calls in both directions](protocol.md#calls-in-both-directions) |
| `@consumer` | a protocol | the other side; follows from `@provider` | [Protocols](protocol.md#annotations) |
| `@unverified` | a protocol | gives up a guarantee, with the reason | [Giving up a guarantee](protocol.md#giving-up-a-guarantee) |
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/guides/idl/index.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# IDL / Schema

The **Interface Description Language** (IDL, also called the *schema*) is what you
The **Interface Description Language** (IDL, also called __Schema__) is what you
write by hand. A schema file has the extension `.ids` and lives under a project's
`src/` directory. It defines the data shapes and the protocols that carry them,
independent of any language.
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/guides/idl/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ protocol Mail {
need to write it, but if you do, it has to agree.
- **`@handshake`** picks what runs on a connection before the first call:
`"comline@2"` (the default) checks they're compatible, and takes
[parameters](../../reference/wire/handshakes/index.md#parameters), as in
[parameters](../../reference/wire/handshakes/comline@2.md#parameters), as in
`{ name = "comline@2", scope = package }`; `"comline@1"` checks that both
ends share the schema, format and framing; `"none"` sends and checks nothing.
Without it, the protocol takes the package's `handshake` from `config.idp`,
Expand Down
21 changes: 6 additions & 15 deletions docs/docs/guides/idl/types.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Primitives:
| unsigned integers | `u8` `u16` `u32` `u64` `u128` |
| floats | `f32` `f64` |
| boolean | `bool` |
| text | `string`, `char` (see below) |
| text | `string`, `char` (see the [reference](../../reference/package/schema/types.md#text-string-and-char)) |

Plus any `struct` / `enum` name (scoped: `pkg::module::Type`), arrays (`Type[]`,
`Type[max 100]` or fixed `Type[10]`), and unions (`union(TypeA TypeB)`).
Expand All @@ -18,20 +18,6 @@ type or given by a [setting](settings.md#default-maximums). The examples in this
carry maxima so they build as written; a bare `string` or `T[]` in one of your
schemas builds only once a default is set.

## Text: `string` and `char`

- **`char`** is one Unicode scalar value: a single character, not a byte or a
UTF-16 unit. Its literal is a string of exactly one character, `"a"`; any
other length is a build error.
- **`string`** is the text type: UTF-8, the built-in name for `char[]`. An
array of `char` is always text, so `char[max 64]` is a string of at most 64
characters, not a list of 64 `char` values.
- **`str`** was an accepted spelling until it was removed. Writing it is now a
build error that tells you to use `string`.
- **`String`** (capitalised) is **not** Comline syntax. It is the Rust type that
`string` generates into, so you see it in generated Rust, never in a `.ids`
file. Writing it gets the same hint.

## Bounds

A **maximum** says how big a value may be, in its type, so a decoder can refuse
Expand All @@ -50,17 +36,22 @@ struct Customer {

- **`T[N]`** is exactly `N`. **`T[max N]`** is at most `N`. `T[]` writes no
maximum, and needs one from a setting.

- **Only a maximum.** A minimum ("not empty", "at least one") is a
[validator](validator.md#the-standard-validators): `NonEmpty`, `MinChars`,
`MinItems`. So is a range of values, `IntRange`.

- **`N` is an integer or a [constant](const.md#sizes-from-constants):**
`char[max NAME_MAX]`. It is at least 1 and at most `u32::MAX` (4294967295);
`max 0`, an exact length of 0 and a negative size are build errors.

- **`max` is a keyword only right after `[`.** Anywhere else it is an ordinary
name, so a field called `max` is fine.

- **Only strings and dynamic arrays take one.** Integers, floats, `bool`, enums,
structs, unions and `()` don't. `string[max 10]` is ten strings, each at the
package default; for a bounded string write `char[max N]`.

- **Any change to a maximum is breaking**: tightening breaks old senders and
loosening breaks old receivers.

Expand Down
6 changes: 3 additions & 3 deletions docs/docs/guides/idl/use.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,9 +102,9 @@ struct Call {
`std` and each of its modules carry [module docs](docstrings.md#module-docs):
hover `std` or `validators` in the editor to read them, with what's in each.

The full reference is on this site, [rendered from those docs](../../reference/schema/std/index.md)
by [`comline doc`](../documenting.md): [`std::http`](../../reference/schema/std/http.md) and
[`std::validators`](../../reference/schema/std/validators.md), each declaration with its fields
The full reference is on this site, [rendered from those docs](../../reference/package/schema/std/index.md)
by [`comline doc`](../documenting.md): [`std::http`](../../reference/package/schema/std/http.md) and
[`std::validators`](../../reference/package/schema/std/validators.md), each declaration with its fields
and variants.

A build includes only the std schemas a package imports. Like a dependency's,
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/guides/idl/validator.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ function there's no single value for it to check, so it's a build error.

## The standard validators

[`std::validators`](../../reference/schema/std/validators.md) ships these. A **maximum** belongs
[`std::validators`](../../reference/package/schema/std/validators.md) ships these. A **maximum** belongs
in the type ([`char[max 32]`](types.md#bounds)), where a decoder checks it before
allocating; validators check what a type can't say, a minimum or a range.

Expand Down Expand Up @@ -225,7 +225,7 @@ in `comline.toml`; `"first"` stops at the first failure), and a provider
refuses a call whose arguments fail them. Turning that off is a give-up with
its reason, `validate_on_decode = { off = "why" }`; then nothing runs until you
call `validate()`. See
[`validate_on_decode`](../../reference/package/congregation/comline-toml.md#validate_on_decode).
[`validate_on_decode`](../../reference/package/comline-toml.md#validate_on_decode).

Properties are filled in when the code is generated: the argument you wrote,
else the property's default, with constants resolved. Nothing about the
Expand Down
3 changes: 1 addition & 2 deletions docs/docs/guides/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,6 @@ The [language guides](../languages/index.md) show it in Rust and TypeScript.

- [Packages & dependencies](packages/index.md): the manifest, wire defaults,
and importing other packages.

- [Documenting your schemas](documenting.md): pages and a site from your
docstrings.
- [Extending Comline](../developer/extending/index.md): your own formats, framings,
handshakes, generators, transports and middleware.
4 changes: 2 additions & 2 deletions docs/docs/guides/ir/cas.md
Original file line number Diff line number Diff line change
Expand Up @@ -347,9 +347,9 @@ hash, and each encoding's name and parameter hash (both blake3, as hex).

See [Compatibility facts](../../reference/versioning.md#compatibility-facts) for
what they mean and how they are compared. The `config.idp` keys are in the
[config.idp reference](../../reference/package/congregation/config-id.md), and where
[config.idp reference](../../reference/package/idp.md), and where
generated code lands is set in
[`comline.toml`](../../reference/package/congregation/comline-toml.md).
[`comline.toml`](../../reference/package/comline-toml.md).

## Branches

Expand Down
4 changes: 2 additions & 2 deletions docs/docs/guides/packages/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ code_generation = {
```

Every key, its syntax and what it does is in the
[`config.idp` reference](../../reference/package/congregation/config-id.md). The ones
[`config.idp` reference](../../reference/package/idp.md). The ones
with more to them have their own sections below: [wire defaults](#wire-defaults)
and [dependencies](#dependencies).

Expand Down Expand Up @@ -82,7 +82,7 @@ Where generated code lands, in what layout, for which versions — none of which
belongs to the package author — is set by whoever runs `comline generation`, in a
separate, non-frozen `comline.toml`. See
[Generating code](../codegen/generating-code.md) and the
[`comline.toml` reference](../../reference/package/congregation/comline-toml.md).
[`comline.toml` reference](../../reference/package/comline-toml.md).

## Dependencies

Expand Down
Loading
Loading