Skip to content

docs: TypeScript does lib mode, and both generators import cross-schema types - #29

Merged
Kinflou merged 1 commit into
mainfrom
docs/typescript-generation
Oct 13, 2026
Merged

Kinflou merged 1 commit into
mainfrom
docs/typescript-generation

Conversation

@Kinflou

@Kinflou Kinflou commented Oct 13, 2026

Copy link
Copy Markdown
Member

Docs for comline-typescript#32, plus two things from already-merged CLI work that never reached the docs.

lib mode

library-generation.md said lib was "rust only" and that "a schema
whose namespace is nested (a/b)" was "not done yet". Both stale: rust's
ModuleTree has handled nested namespaces all along, and typescript now
does too. The lib section gains a typescript half — the package shape, the
index.ts-per-level barrel and why it mirrors namespaces instead of
flattening (std is implicit in every package, so a flat barrel makes your
own Request ambiguous with std/http's, which TypeScript refuses
outright), and the one restriction both generators share: a namespace can be
a schema or a parent of deeper schemas, not both.

Cross-schema references

generating-code.md only documented rust's crate::-qualified paths. Added
the typescript equivalent — import type by relative specifier, aliases
importing the name the other module exports, unused uses producing
nothing — along with the assumption that carries: code mode needs the
layout to keep each namespace in the file-name position. Every layout
the docs show does, including the default.

Flags that were never documented

scripts/check-cli-drift.py was failing on main:

`comline generate`
  + --no-external-std    in the CLI, not in the docs

--no-external-std (cli#58) was missing from cli.md entirely, and
--dry-run was in the flag list but unexplained. Both documented, and the
external_std default is now stated (on in lib, off in code). The drift
check is clean again:

No drift: the docs match comline 0.2.0.

The [[generate.target]] section also still described a block as what
decides whether a language is generated — the behaviour cli#59 fixed — so
that carries over here too.

Both drift scripts pass. mkdocs isn't installed locally, so the site build is
unverified.

…hema types

Catches the codegen guide up with two merged changes and one shipping now.

`lib` mode was documented as "rust only" with nested namespaces "not done
yet" - stale for rust, whose `ModuleTree` has handled them all along, and now
wrong for typescript too (comline-typescript#32). `library-generation.md`
gains a typescript section: the package shape, why the barrel mirrors
namespaces rather than flattening them, and the one restriction both
generators share (a namespace is a schema or a parent, not both).

`generating-code.md`'s cross-schema reference section only covered rust's
`crate::`-qualified paths; typescript now emits `import type` by relative
specifier, which carries an assumption worth stating - `code` mode needs the
layout to keep a namespace in the file-name position.

Also from cli#58 and cli#59, neither of which reached the docs:
`--no-external-std` and `--dry-run` were missing from `cli.md` entirely
(caught by `scripts/check-cli-drift.py`, which is now clean again), and the
`[[generate.target]]` section still described a block as what decides whether
a language is generated rather than how.
@Kinflou
Kinflou merged commit 5977fbc into main Oct 13, 2026
3 checks passed
@Kinflou
Kinflou deleted the docs/typescript-generation branch October 13, 2026 08:13
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.

1 participant