Repository navigation
Say what you use from the generated code; own schemas only through relative paths - #184
Merged
Merged
Conversation
…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.
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.
Closes #183. Refs #182.
#183: what you use, from the generated code
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 stayspub/ exported for by-hand use.datagram: client & server" (file name and anchors unchanged) and says it is only that case.dd1c29e, comline-typescript#172 atd377fbf): the//!/ header comment, hidden and internal plumbing,pub type Framingandpub type Connection<T>,Format/CONNECTION_IR_HASHdefined once (connection.rs, orwire.tsin TypeScript) and re-exported by the protocol files, the correctedconnect,handshake()andcheck_callforcomline@2, andLayoutwhere the TypeScript page still saidShape.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// …:connection.rs/connection.ts/wire.tsand the sendersconnections_default(see below), shape cross-checked againstnested_protocolconnections_asyncFraming,Connection<T>,accept_with)connections_jsonrpcRpcDispatcher,RpcClient,serveRpc)framing_jsonrpcdatagram@2/comline@1differencesconnectionsMailDispatcher/MailClient(Rust)lockstep(see below)Chat(TypeScript)lockstep_chat(see below)There is no golden for the lockstep
datagramand none for a connection under the real defaults (datagram@3,comline@2) with a client-provided protocol:connectionspinsdatagram@2/comline@1,nested_protocolis server-only, andprotocolis a connection, not lockstep. For those three I added fixtures to a scratch clone of generation (not pushed anywhere),lockstep(theMailexample from these docs),lockstep_chat(the TypeScript page'sChat) andconnections_default(connectionswith 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
guides/idl/use.md): own schemas only throughpackage::,parent::andself::; an absolute first segment always meansstdor a dependency; the four reserved names;import::bare-own-schema-pathwith its message, context, help and the quick fix that insertspackage::; the examples, the path forms and "Referring to what you imported" usepackage::, 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::Userstaysimport::unresolved).guides/idl/index.mdandguides/codegen/generating-code.md. A grep of every.mdand.idsunderdocs/docsfound no other bare own-schemause; the proposal pages that show the "before" form on purpose are untouched.comline fixdoesn'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), theconfig.idpgroupfield,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.