Kotlin Java Library Design

Quick start

• Read references/kotlin-java-library.md before changing public Kotlin APIs for Java consumers.
• Design Kotlin APIs as if the primary caller is Java: explicit overloads, stable names, and predictable nullability.
• Use JVM interop annotations (@JvmOverloads, @JvmStatic, @JvmField, @JvmName) to shape the Java surface.
• Prefer Java-friendly top-level functions with @file:JvmName, and use @file:JvmMultifileClass when splitting across files.
• Use fun interface for Java callbacks; avoid function types that return Unit.
• Document checked exceptions with @Throws and return defensive copies for read-only collections.
• Follow binary compatibility rules: add overloads or new members instead of changing published signatures.
• Validate examples with scripts/verify-examples.java when changing the reference or public API patterns.

Workflow

1. Identify which public APIs must be Java-friendly (constructors, factories, utilities, callbacks, records).
2. Shape the Java surface with JVM annotations and explicit overloads.
3. Audit public signatures for Java stability (names, nullability, overload sets, and collection exposure).
4. Apply backward-compatibility rules before publishing; treat @PublishedApi members as public.
5. Validate with Java call-site examples.
6. Run jbang skills/kotlin-java-library/scripts/verify-examples.java; if it fails, fix the sample or document why it cannot be tested.