From 40eaa113521339094b2a8920f5d1e6a261745be3 Mon Sep 17 00:00:00 2001 From: Owen Carey <37121709+owenthcarey@users.noreply.github.com> Date: Wed, 16 Sep 2026 20:21:00 -0700 Subject: [PATCH] docs: record the rule behind generator target names Add a Target names section to the naming reference that states how a generator's target is named (after the language when the output is idiomatic to one language, after the runtime when several languages consume it equally, never after a deployment platform), and records why dotnet and kotlin are both applications of that rule, including why the android target became kotlin in schema 0.9.0. --- docs/src/reference/naming.md | 50 ++++++++++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/docs/src/reference/naming.md b/docs/src/reference/naming.md index e2c4a08e..49bc4e97 100644 --- a/docs/src/reference/naming.md +++ b/docs/src/reference/naming.md @@ -1,8 +1,9 @@ # Naming and Package Conventions This page has two halves. The first is the naming policy for the WeaveFFI -project itself: brand names, repository slugs, and package names across -registries. The second is the naming policy the **generators** apply to +project itself: brand names, repository slugs, package names across +registries, and the names of the generator targets. The second is the +naming policy the **generators** apply to the identifiers they emit from your IDL: C symbols, wrapper classes, functions, error types, and the Kotlin package. Every rule in the second half was checked against the output of `weaveffi generate` for the @@ -31,6 +32,51 @@ Rationale: condensed top-level slugs unify handles across registries and are ergonomic to type; hyphenated subpackages remain idiomatic and map cleanly to ecosystems that normalize to underscores or CamelCase. +### Target names + +A generator's target name is the one identifier that appears everywhere +the generator does: the `--target` flag, the `[generators.]` +table in `weaveffi.toml`, the output directory under `generated/`, the +`weaveffi-gen-` crate, and the page under +[Generators](../generators/README.md). The eleven targets are `c`, `cpp`, +`swift`, `kotlin`, `node`, `wasm`, `python`, `dotnet`, `dart`, `go`, and +`ruby`. + +The rule is to name the target after the thing a consumer holds and +identifies with, which is sometimes a language and sometimes a runtime: + +- When the emitted surface is idiomatic to one language, the target is + that language (`swift`, `python`, `dart`, `go`, `ruby`, `kotlin`). +- When one runtime serves several languages equally, the target is the + runtime (`dotnet`, `node`, `wasm`). Two targets that emit the same + language for different runtimes are named by runtime so they can be + told apart (`node` and `wasm` both emit JavaScript). +- A deployment platform is never a target name. Where a target runs on + more than one platform, the platform is a setting under its + `[generators.]` table, so adding a platform never renames the + target. + +The two cases that look inconsistent are both applications of the same +rule: + +- `dotnet`, not `csharp`. The generator emits C#, but the P/Invoke surface + and the NuGet package are consumed equally from C#, F#, and Visual Basic, + so the runtime is what a consumer identifies with. +- `kotlin`, not `android` or `jvm`. The generator was called `android` + through schema `0.8.0`. It was renamed because the same output runs on + Android and on a desktop JVM (the conformance harness drives it with + `kotlinc` and `java`, with no Android SDK), so a platform name described + only one of its runtimes. It isn't `jvm` because the emitted API depends + on Kotlin-only features (`suspend fun` for async, sealed classes for rich + enums, data classes for records), and a Java caller would not find it + idiomatic; naming it after the runtime would promise a language-neutral + surface the generator doesn't provide. + +A new generator should pick its name by the same test: if a second +language could consume the output as naturally as the first, name the +target after the runtime; otherwise name it after the language. Don't +name it after the platform it happens to ship on first. + ### Code identifiers by ecosystem - Rust: hyphenated subcrates on crates.io (`weaveffi-core`), imported with