Skip to content

docs(emitters): state Kotlin's reserved sets for units - #1335

Open
OmarAlJarrah wants to merge 6 commits into
docs/emitters-enum-value-typesfrom
docs/emitters-kotlin-reserved-sets
Open

OmarAlJarrah wants to merge 6 commits into
docs/emitters-enum-value-typesfrom
docs/emitters-kotlin-reserved-sets

Conversation

@OmarAlJarrah

Copy link
Copy Markdown
Member

Summary

docs/emitters/refine/reserved-names.md leaves three scopes to each target. Kotlin's naming document stated only the type scope, so a Kotlin emitter had nothing to reserve for a group's module or package (the units) or for what the SDK declares beside the spec's names in a unit, and T-19 had no fixture to name. The issue asked for a measured answer on what Gradle and kotlinc refuse, so each set below comes from a build, not from documentation.

The units: build, buildsrc in any letter case, gradle, src. These are the names Gradle gives a meaning at a build's root, where a group's module now explicitly sits (targets/kotlin/overview.md).

  • A module named build lives inside the root project's output directory. It builds, but gradle clean on the root deleted the module's sources.
  • A module named buildsrc failed the build on macOS. Gradle found it as buildSrc, its build-logic build, since the file system is case-insensitive.
  • gradle (the wrapper and version catalog) and src (the root project's sources) built, but a module there shares their directory. They are reserved so that a later wrapper or root source file never lands inside a module.

Not units names: hard keywords and kotlin.

  • Backticked keywords as package segments compile in a package and an import. fun, object, when, is, in and typealias compiled for the JVM, JS and macOS Native and linked into an Objective-C framework. Twelve more (class, val, interface, as, true, null, this, super, package, return, throw, try) compiled on the JVM. So keywords take the existing escape, and renaming them would be needless.
  • kotlinc refuses kotlin only as a package's first segment ("Only the Kotlin standard library is allowed to use the 'kotlin' package"). That segment is the root's, which the options name. probe.kotlin compiled.

A unit: Client, a group unit's sub-client, and the runtime names the root unit declares. These are ApiFailure, ApiException, ClientException, ServerException, each taxonomy kind's exception, Fault, OtherResponse, OtherResponseException, Response, RawBody, Optional, Duration, Authenticator and Transport, plus Decimal and OffsetDateTime on Multiplatform. That is every runtime type the Kotlin documents name. The list is held the way a function's bound names are: each runtime template declares what it declares, so it is derived from the templates rather than kept apart from them.

T-19 now names a group after each units name, and requires that a Kotlin clean leave every module's sources.

On the golden spec (spec @319dc756, morphic @b206dc99), no group's name normalizes to any units name but shared, which the shared reservation already covers.

Closes #1187

Test plan

  • Probes with Kotlin 2.4.0, Gradle 9.8.2 and Corretto 25 on darwin/arm64, all offline:
    • JVM, 18 backticked keyword packages, imported from another package: compile, 19 classes emitted;
    • Multiplatform, 6 keywords: compileKotlinJvm, compileKotlinJs, compileKotlinMacosArm64 and linkDebugFrameworkMacosArm64 pass, and the header declares the classes;
    • package kotlin.probe fails with the error quoted above, and package probe.kotlin compiles;
    • modules build, gradle, src, shared and fun build; buildSrc and buildsrc fail; gradle clean on the build probe removed build/src/main/kotlin.
  • CI: the doc tests.

Stacked on #1334, so it lands after the other emitter-design PRs (#1329 ← #1331 ← #1332 ← #1334). It edits targets/kotlin and T-19 only. After each base lands, "Update branch" is a merge of main that conflicts nowhere.

Kotlin's naming document stated only the members it gives every type,
so a Kotlin emitter had no names to reserve for a group's module or for
the declarations a unit holds beside the spec's, and T-19 no fixture.

Measured with Kotlin 2.4.0 and Gradle 9.8.2: a module named build sits
in the root project's output, which clean deletes with the module's
sources; one named buildsrc is taken for Gradle's buildSrc on a
case-insensitive file system and fails the build; gradle and src share
the wrapper's and the root sources' directories. Those four are the
units set, and a group's module is placed at the build root so the set
applies. Hard keywords need no reservation: backticked as package
segments they compile on the JVM, JS and Native and link into a
framework, and kotlin is refused only as the first segment, which the
options name. The unit set is Client, a group's sub-client and the
runtime names the root unit declares.
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