Repository navigation
docs: external_std applies to both generators, and document two missing keys - #31
Merged
Merged
Conversation
…sing keys comline-typescript#33 gave typescript its own std package (`@comline/std`, the counterpart of `comline_std`), so `--external-std` is no longer a Rust thing: `cli.md` said "makes generated Rust reference `comline_std`". Two keys turned out to be undocumented in `comline-toml.md` altogether: - `external_std` — never documented, and it defaults *on* in `lib` mode, so the behaviour it controls was the undocumented default - `only` — the narrowing key cli#59 added; it reached the codegen guide but not the reference, and it is also the escape hatch for a declared language with no compiled-in generator Both now have their own sections. The `[[generate.target]]` intro still described a block as something you "pin or override" without saying it doesn't decide *whether* a language is generated — the distinction cli#59 turned into an error — so that's stated here too, and the `mode` row still claimed `lib` was rust-only. The `lib` examples in `library-generation.md` used `std/http` to illustrate nesting, which `external_std` now makes a misleading choice — std is exactly the namespace a `lib` build doesn't carry. Switched to a plain nested namespace, with std's own behaviour given its own short section.
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.
Follows comline-typescript#33, which gave typescript its own std package (
@comline/std, the counterpart ofcomline_std).--external-stdwas documented as a Rust featurecli.mdread "makes generated Rust referencecomline_std". It now namesboth packages.
Two keys were undocumented in
comline-toml.mdexternal_std— not documented at all, and since it defaults on inlibmode, the behaviour it controls was the undocumented default. Nowhas its own section: what it does, the package per language, why
codemodedefaults it off, and the fact that neither package is published yet.
only— added by cli#59; it reached the codegen guide but never thereference. It's also the documented escape hatch when a declared language
has no generator in your build, which made its absence worse than cosmetic.
Also in that file: the
[[generate.target]]intro described a block assomething you "pin or override" without saying it doesn't decide whether a
language is generated — the distinction cli#59 turned into a hard error — and
the
moderow still claimedlibwas implemented forrustonly.The
libexamples used std to show nestinglibrary-generation.mdillustrated nested namespaces withstd/http, whichis now the one namespace a
libbuild specifically does not carry. Thatwould have read as a contradiction against the new
external_stdsection, sothe examples use a plain nested namespace and std gets its own short section
explaining that it's a dependency rather than a copy.
The cross-schema reference sections in
generating-code.mdalso said everynon-local schema "is inlined", for both languages; both now note the std
exception, with the subpath form for typescript
(
import type { Request } from "@comline/std/http").Both drift scripts clean.