Skip to content

Say what you use from the generated code; own schemas only through relative paths - #184

Merged
Kinflou merged 1 commit into
mainfrom
docs/what-you-use-and-own-paths
Nov 15, 2026
Merged

Kinflou merged 1 commit into
mainfrom
docs/what-you-use-and-own-paths

Conversation

@Kinflou

@Kinflou Kinflou commented Nov 15, 2026

Copy link
Copy Markdown
Member

Closes #183. Refs #182.

#183: what you use, from the generated code

  • "What you use" table at the top of the Rust and TypeScript index pages: for the default connection, the lockstep datagram, JSON-RPC (a protocol the client provides, and a server-only one) and by hand, what you implement, serve, dial and call through. Below it, what the generated files hold and which plumbing is #[doc(hidden)] (Rust) or @internal (TypeScript) but stays pub / exported for by-hand use.
  • Connections first in "Where to go next" and in the nav, then the lockstep page, then Framing.
  • Client & server is retitled "Lockstep datagram: client & server" (file name and anchors unchanged) and says it is only that case.
  • Snippets match the generators now (comline-rust#131/proposals: IPC, and Comline for systems software #132 at dd1c29e, comline-typescript#172 at d377fbf): the //! / header comment, hidden and internal plumbing, pub type Framing and pub type Connection<T>, Format / CONNECTION_IR_HASH defined once (connection.rs, or wire.ts in TypeScript) and re-exported by the protocol files, the corrected connect, handshake() and check_call for comline@2, and Layout where the TypeScript page still said Shape.
  • The example schemas on the Connections pages are now the conformance one (Chat.send(n: u32) -> u32; Events.shown(n: u32) -> bool, ping()), so the snippets are the generated text, not hand-edited.

Sources, all from ComlineProject/generation master (ac2d771), trimmed with // …:

Snippet Golden
Connections connection.rs / connection.ts / wire.ts and the senders connections_default (see below), shape cross-checked against nested_protocol
Rust async trait and sender connections_async
Rust and TypeScript JSON-RPC connection (Framing, Connection<T>, accept_with) connections_jsonrpc
Server-only JSON-RPC (RpcDispatcher, RpcClient, serveRpc) framing_jsonrpc
datagram@2 / comline@1 differences connections
Lockstep MailDispatcher / MailClient (Rust) lockstep (see below)
Lockstep Chat (TypeScript) lockstep_chat (see below)

There is no golden for the lockstep datagram and none for a connection under the real defaults (datagram@3, comline@2) with a client-provided protocol: connections pins datagram@2 / comline@1, nested_protocol is server-only, and protocol is a connection, not lockstep. For those three I added fixtures to a scratch clone of generation (not pushed anywhere), lockstep (the Mail example from these docs), lockstep_chat (the TypeScript page's Chat) and connections_default (connections with the default framing and handshake), and blessed them with the same harness and the same generator pins. No existing golden changed. Worth adding to the corpus.

#182: own schemas only through relative paths

  • Imports guide (guides/idl/use.md): own schemas only through package::, parent:: and self::; an absolute first segment always means std or a dependency; the four reserved names; import::bare-own-schema-path with its message, context, help and the quick fix that inserts package::; the examples, the path forms and "Referring to what you imported" use package::, with qualified references written by the schema's namespace (types::User), as core#285 has it; "When nothing matches" no longer uses a bare own path (use package::types::Usr; use typse::User stays import::unresolved).
  • Other snippets: guides/idl/index.md and guides/codegen/generating-code.md. A grep of every .md and .ids under docs/docs found no other bare own-schema use; the proposal pages that show the "before" form on purpose are untouched.
  • The guide says plainly that the language server doesn't offer the fix yet (language-server#122) and comline fix doesn't apply it (cli#162), since core#285 only put the fix on the diagnostic.

docs#182 stays open: groups and --group (core#284, cli#162), the config.idp group field, comline.toml [format] and its JSON Schema, the CLI reference, and the CAS and IR pages once provenance lands. None of those is documented as available here.

…lative paths

The Rust and TypeScript index pages get a "What you use" table (the default
connection, the lockstep datagram, JSON-RPC, by hand). Connections comes first
in "Where to go next" and the nav; Client & server becomes the lockstep
datagram page. The snippets on both language sections match the generators'
output after comline-rust#131/#132 and comline-typescript#172: the entry-point
header, hidden/internal plumbing, Framing and Connection<T>, Format and
CONNECTION_IR_HASH defined once.

The Imports guide and the other snippets reach a package's own schemas only
through package::, parent:: and self::, and document import::bare-own-schema-path.
@Kinflou
Kinflou marked this pull request as ready for review November 15, 2026 12:05
@Kinflou
Kinflou merged commit 19edd2f into main Nov 15, 2026
9 checks passed
@Kinflou
Kinflou deleted the docs/what-you-use-and-own-paths branch November 15, 2026 12:05
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.

Rust (and TypeScript) docs: say what you use from the generated code, default case first

1 participant