This guide covers principles and practices for developing new Analysis API endpoints, including design patterns, implementation guidelines, and documentation standards.
For information about the Kotlin Analysis API itself, check the Analysis API documentation.
For information about evolving existing APIs, see the API Evolution Guide.
Not all existing parts of the Analysis API strictly follow every guideline in this document. There are several reasons for these deviations:
When working with existing code, strive to follow these guidelines for new APIs while respecting the constraints of existing implementations. During refactoring, gradually align older code with these guidelines where possible without breaking compatibility.
[!TIP] Build APIs that solve real problems elegantly, prioritize Kotlin idioms, and maintain consistency with language concepts.
When designing or refactoring any part of the Analysis API, the following fundamental principles guide our decisions.
Start by understanding how developers currently tackle the problem you're addressing. Research existing use cases and identify common patterns in workarounds. This ensures your API addresses actual needs rather than theoretical scenarios. Use the endpoint card when working with complicated endpoints.
Provide simple, intuitive solutions for frequent use cases while offering sophisticated APIs for complex scenarios. You can apply different stability guarantees to each tier.
// Simple API for common cases: get just the target symbol expression.mainReference.resolveToSymbol() // Advanced API for complex scenarios: get all information about the call expression.resolveToCall()?.singleFunctionCallOrNull()?.argumentMapping
Test your API design by implementing it in real scenarios. This reveals usability issues and missing functionality early. If you find yourself writing wrapper functions or complex workarounds, revisit the design.
Design APIs that feel natural in Kotlin code. Use Kotlin's language features to create convenient and safe endpoints.
// Leverage extension functions for better readability val KaClassSymbol.allSuperTypes: Sequence<KaType> // Good fun allSuperTypes(symbol: KaClassSymbol): Sequence<KaType> // Less idiomatic // Use Kotlin function types instead of Java interfaces fun processTypes(filter: (KaType) -> Boolean) // Good fun processTypes(filter: Predicate<KaType>) // Less idiomatic
The Analysis API reflects semantic meaning, not syntactic structure (for which there is the Kotlin PSI). If you still need to expose syntactic information, use clear naming conventions, e.g., isMarkedThing or sourceThing.
// Checking semantic visibility (considering all modifiers and context) val KaSymbol.visibility: KaSymbolVisibility // Checking the presence of a syntactic marker for nullable types (e.g., 'T?') val KaType.isMarkedNullable: Boolean // Not just 'isNullable'
Align with widely recognized conventions from Kotlin stdlib and the ecosystem.
// Reuse standard interfaces instead of custom wrappers where appropriate interface KaAnnotationList : List<KaAnnotation>, KaLifetimeOwner { operator fun contains(classId: ClassId): Boolean operator fun get(classId: ClassId): List<KaAnnotation> } // Use conventional method names interface KaType { override fun toString(): String // Not 'debugString()' or 'asString()' }
Align terminology and concepts with official Kotlin documentation, language specification, and KEEPs. Avoid direct mirroring compiler internals if they don't match user mental models.
[!TIP] APIs require attention to detail and forward-thinking design. Carefully design entity hierarchies, check whether endpoints are evolution-friendly, and provide comprehensive documentation together with tests.
Always enable explicit API mode to ensure all public declarations have explicit visibility modifiers and return types. This prevents accidental API surface expansion.
abstract class KaDefinitelyNotNullType : KaType { // Visibility must be specified final override val isNullable // Return type must be specified get() = withValidityAssertion { KaTypeNullability.NON_NULLABLE } }
[!NOTE] To keep examples clean and focused, the
publicmodifier is omitted in most code snippets.
Use the binary-compatibility-validator tool to catch breaking changes. The API must remain binary-compatible across minor versions.
Stick to stable Kotlin language features in generally available Analysis API endpoints. Experimental features may change syntax or semantics between Kotlin versions, requiring API clients to opt into unstable language features, or may be removed completely.
When exposing an experimental feature for early adopters, always annotate affected declarations with an opt-in annotation.
Don't expose internal compiler representations directly. Create abstractions that have predictable backward compatibility and make sense to API users.
// Bad: Exposing internal enum from compiler interface KaConstantValue { val constantValueKind: ConstantValueKind // Internal compiler enum can be changed at any time } // Good: API-specific abstraction sealed interface KaConstantValue { val value: Any? interface IntValue : KaConstantValue { override val value: Int } interface StringValue : KaConstantValue { override val value: String } // ... }
Interfaces provide more flexibility for implementations and have better binary compatibility characteristics than classes. Use abstract classes only when you need to share implementation details or state.
// Preferred: Interface allows for context-tailored implementations interface KaType : KaLifetimeOwner, KaAnnotated // Avoid unless needed: Class restricts implementation abstract class KaType : KaLifetimeOwner, KaAnnotated
Complex inheritance structures increase cognitive load and maintenance burden. Consider alternative approaches before creating deep hierarchies.
Avoid marker interfaces created solely for member sharing. Rule of thumb — ask yourself, “Would it make sense for clients to pass instances of this type around”? If not, the interface might be unnecessary.
// Good: Clear, purposeful hierarchy interface KaSymbol interface KaDeclarationSymbol : KaSymbol { val modality: KaSymbolModality val visibility: KaSymbolVisibility val isExpect: Boolean val isActual: Boolean } // Bad: Unnecessary complexity interface KaSymbol interface KaSymbolWithModality : KaSymbol { val modality: KaSymbolModality } interface KaSymbolWithVisibility : KaSymbol { val visibility: KaSymbolVisibility } interface KaMultiplatformSymbol : KaSymbol { val isExpect: Boolean val isActual: Boolean } interface KaDeclarationSymbol : KaSymbolWithModality, KaSymbolWithVisibility, KaMultiplatformSymbol
Keep different concepts separate in your type hierarchies. Prefer composition to inheritance.
Such as, a class symbol should not also be a scope, even if it contains declarations:
// Bad: Mixing concepts interface KaClassSymbol : KaSymbol, KaScope // Good: Separate concepts with clear relationships // Even better: move out the scope API to a session component interface KaClassSymbol : KaSymbol { val staticScope: KaScope val memberScope: KaScope }
When you do need interfaces for sharing members, use clear suffixes that indicate the relationship:
// "Owner" for ownership relations interface KaContextParameterOwnerSymbol : KaFunctionSymbol { val contextParameters: List<KaContextParameterSymbol> } // "Container" for weaker containment relations interface KaDeclarationContainerSymbol : KaSymbol { val declarations: Sequence<KaDeclarationSymbol> }
Sealed classes and enums create strong API commitments because you cannot add new subtypes without breaking compatibility (exhaustive when). Consider your evolution needs carefully.
// Good: Sealed class with escape hatch for evolution sealed class KaAnnotationValue { data class IntValue(val value: Int) : KaAnnotationValue() data class StringValue(val value: String) : KaAnnotationValue() // A private subclass forces 'else' branches in client code private class UnknownValue : KaAnnotationValue() } // Alternative: Statics for more flexibility (and no exhaustive 'when') class KaSeverity private constructor(val name: String) { companion object { val ERROR: KaSeverity = KaSeverity("ERROR") val WARNING: KaSeverity = KaSeverity("WARNING") } }
For simpler hierarchies, prefer placing inheritors inside a sealed class or interface. This way, users can immediately see all subtypes at a glance, and subtypes can have simpler names.
Note that with the emerging context-sensitive resolution feature, specifying outer class names won't be needed in many cases.
sealed class KaSeverity { object Error : KaSeverity() object Warning : KaSeverity() private object Unknown : KaSeverity() // Forces 'else' branches in exhaustiveness checks }
When you have two or more inheritance levels in a sealed hierarchy, or when individual classes are meant to be passed around independently, implement them as top-level classes:
sealed class KaClassifierSymbol : KaDeclarationSymbol() sealed class KaClassSymbol : KaClassifierSymbol() abstract class KaNamedClassSymbol : KaClassSymbol() abstract class KaAnonymousObjectSymbol : KaClassSymbol() abstract class KaTypeAliasSymbol : KaClassifierSymbol()
@SubclassOptInRequired for Non-Extendable TypesIf an interface or class isn't intended to be subclassed by clients, make this explicit:
// Clients aren't supposed to create their session implementations @SubclassOptInRequired(KaImplementationDetail::class) interface KaSession
On the other hand, if you expect users to create subtypes of your class or interface, provide detailed instructions on not only how to use each of the members, but also how to implement them correctly.
KaLifetimeOwnerEntities containing symbols or types typically require lifetime management. Consider how your entity will be used outside analysis sessions.
// Needs lifetime management: Contains symbols interface KaCallInfo : KaLifetimeOwner { val targetFunction: KaFunctionSymbol // Symbol requires lifetime } // Doesn't need lifetime management: Pure data sealed interface KaConstantValue { val value: Any? val sourcePsi: KtElement? fun render(): String }
Data classes aren't designed for API evolution. They expose implementation details through generated methods and make compatibility harder to maintain.
// Bad: Data class in public API data class KaCallInfo( val targetFunction: KaFunctionSymbol, val arguments: List<KaArgument> ) // Good: Interface with explicit contract interface KaCallInfo { val targetFunction: KaFunctionSymbol val arguments: List<KaArgument> }
If your type overrides equals() and hashCode(), clearly specify the equality contract.
Ensure the contract confirms to the Java requirements for Object.equals() and Object.hashCode(). If conformance is impossible, document the reasons.
/** * [KaType.equals] implements *structural type equality*, which may not match * with the usual intuition of type equality. Structural equality * is favored for `equals` because it is fast and predictable, and * additionally it allows constructing a hash code. * * For semantic type comparisons, [semanticallyEquals] should be used, as it * implements the equality rules defined by the type system. */ interface KaType
[!TIP] Design properties and functions that are intuitive, evolution-friendly, and follow Kotlin conventions. Pay attention to parameter names, return types, and error handling.
In many languages, properties are often used for simple operations that don‘t involve expensive computation, or when the result is already known, while functions represent more complex operations. However, as the Analysis API features on-demand code analysis, it’s rarely possible to predict the amount of computation required for a given endpoint.
So instead, choose between properties and functions based on the endpoint semantic, and aesthetic of its usages:
KtClassOrObject.symbol means “get a symbol that represents the given class”. The user doesn't care whether the symbol is newly computed or taken from the cache.// Property: No user-visible side effects val KaClassSymbol.isData: Boolean // Function: May involve computation or have parameters fun KtElement.resolveToCall(): KaCallInfo? fun KaClassSymbol.isSubClassOf(superClass: KaClassSymbol): Boolean
If you have a function endpoint with a parameter which is often omitted (for instance, by providing a trivial value, such as null, an empty collection, or a true-returning lambda), consider adding a convenience property with the same name:
val KaScope.callables: Sequence<KaCallableSymbol> fun KaScope.callables(nameFilter: (Name) -> Boolean): Sequence<KaCallableSymbol>
On incorrect or incomplete input, the Kotlin compiler may return a partial resolution result. Never assume a reference or a call can always be resolved.
Don't expose an API relying on unsafe assumptions:
// Bad: Throws on analysis failure fun KtCallExpression.resolveSymbol(): KaFunctionSymbol // Throws if resolution fails // Good: Returns 'null' on analysis failure fun KtCallExpression.resolveSymbol(): KaFunctionSymbol?
Use appropriate return types to indicate absence or failure:
// Bad: Throwing for missing elements fun getClass(classId: ClassId): KaClassSymbol // Throws if not found // Good: Null for not found fun findClass(classId: ClassId): KaClassSymbol? // Good: Result or a custom class for operations that can fail with details interface KaCompilerFacility { fun compile(file: KtFile): KaCompilationResult }
Throwing exceptions is appropriate for:
// Good: Exception on API misuse val KtFunction.symbol: KaFunctionSymbol get() = withValidityCheck { check(this.isValid) ... }
Parameter names cannot be changed without breaking source compatibility:
// If you ship this fun findClass(className: Name): KaClassSymbol? // You won't be able to change to this without breaking clients fun findClass(name: Name): KaClassSymbol? // Breaks named parameters!
Default parameters break binary compatibility when changed. Use overloads instead:
// Bad: Adding/changing defaults breaks binary compatibility fun findFunctions(name: Name, scope: KaScope? = null): Sequence<KaFunctionSymbol> // Good: Explicit overloads fun findFunctions(name: Name): Sequence<KaFunctionSymbol> fun findFunctions(name: Name, scope: KaScope): Sequence<KaFunctionSymbol>
While @JvmOverloads may look like a solution, it still generates the $default function, compatibility of which breaks on signature changes. E.g., for the following function:
@JvmOverloads fun test(i: Int = 0, s: String = "") {}
The following set of JVM methods is generated:
public final class FacadeKt { public static final void test(int, java.lang.String); public static void test$default(int, java.lang.String, int, java.lang.Object); public static final void test(int); public static final void test(); }
Now, if the test() function gets a new parameter, the old $default will disappear.
Overloaded or similar methods should behave predictably:
interface KaSymbolProvider { // Bad: No common patterns fun findClass(classId: ClassId): KaClassSymbol? fun findTypeAlias(fqName: FqName): Result<KaTypeAliasSymbol> fun findFunction(classId: ClassId?, name: Name): KaFunctionSymbol? // Good: All "find" methods return 'null' for not found fun findClass(classId: ClassId): KaClassSymbol? fun findTypeAlias(classId: ClassId): KaTypeAliasSymbol? fun findFunction(callableId: CallableId): KaFunctionSymbol? }
Reduce cognitive load by providing a single entry point with specialized overloads:
// Base extension for all declarations val KtDeclaration.symbol: KaDeclarationSymbol // Specialized versions with more specific return types val KtClass.symbol: KaClassSymbol val KtNamedFunction.symbol: KaFunctionSymbol val KtProperty.symbol: KaPropertySymbol // Users only need to remember ".symbol"
Select return types that provide flexibility for implementations and users. Avoid choosing the List unconsciously – consider also Sequence, Collection or Iterable.
// Good: Sequence allows lazy evaluation (and lazy implementation!) val KaType.allSupertypes: Sequence<KaType> // Document iteration capabilities /** * Returns a sequence of all supertypes of the given [KaType]. * * Supertypes may be traversed lazily. * The sequence can be iterated multiple times. */ val KaType.allSupertypes: Sequence<KaType> // For small, always-computed collections, 'List' is fine interface KaFunctionSymbol { val valueParameters: List<KaValueParameterSymbol> }
At the same time, avoid using Sequences “just in case” – they are more heavyweight. Also, they are prone to scoping issues, as you cannot know when the sequence will be traversed. Use them when it can make the implementation significantly more efficient.
Make APIs more fluent by extending collection types:
// Good: Extension on a collection (or 'Iterable' in this particular case) val Iterable<KaType>.commonSupertype: KaType? get() = computeCommonSupertype(this) // Usage is clear with collections val supertype = listOf(stringType, intType).commonSupertype // When collection literals come to Kotlin, this will look even nicer val supertype = [stringType, intType].commonSupertype // Less idiomatic: Standalone function fun commonSupertype(types: List<KaType>): KaType?
Provide nullable helpers for members of subtypes that are used extremely often:
// Calling a popular 'symbol' property requires an explicit cast interface KaType : KaLifetimeOwner, KaAnnotated interface KaClassType : KaType { val symbol: KaClassLikeSymbol } // Now users can easily get a symbol when it's available val KaType.symbol: KaClassLikeSymbol? get() = when (this) { is KaClassType -> symbol else -> null }
This approach is particularly valuable when you expect users to mostly work with base types. Avoid implementing helpers as default interface methods – those are still virtual and can be overridden by clients.
Reserve operators for their conventional meanings:
// Good: Conventional operator usage interface KaScope { operator fun contains(name: Name): Boolean operator fun get(name: Name): KaSymbol? } // Avoid: Unconventional operators outside DSLs operator fun KaType.plus(other: KaType): KaType // What does this mean?
Infix functions are rarely used in ordinary Kotlin code. Although the syntax might feel tempting, reserve it for DSLs:
// Bad: Nice-looking in theory, awkward in practice infix fun KaType.isSubtypeOf(supertype: KaType) myType isSubtypeOf serializableType // Good: Keep it simple fun KaType.isSubtypeOf(supertype: KaType) myType.isSubtypeOf(serializableType)
Help the compiler with smart casts using contracts:
inline fun KaSession.buildSubstitutor(build: KaSubstitutorBuilder.() -> Unit): KaSubstitutor { contract { callsInPlace(build, InvocationKind.EXACTLY_ONCE) } return createSubstitutor(KaSubstitutorBuilder(token).apply(build).mappings) }
When adding top-level functions or properties, consider the JVM facade name:
// File: KaTypeUtils.kt @file:JvmName("KaTypes") // Better than "KaTypeUtilsKt" fun KaType.isSubtypeOf(other: KaType): Boolean val KaType.isNullable: Boolean
Object.clone()The clone() method is fundamentally broken in Java. It performs shallow copying, bypasses constructors, and requires manual casting. Offer explicit copying methods instead:
// Bad: Using clone() interface KaAnnotation : Cloneable // Good: Explicit copy with clear semantics interface KaAnnotation { /** * Creates a deep copy of this annotation with all its values. * The copy is independent and can be safely modified. */ fun copy(): KaAnnotation }
[!TIP] Inline functions and constants are copied into client code at compile time. Changes to their implementation won't affect existing compiled code.
When you use const val or inline fun, the implementation is copied directly into client bytecode. This means:
// If clients compile against version 1.0 const val DEFAULT_TIMEOUT = 1000 inline fun performOperation(action: () -> Unit, timeout: Int = DEFAULT_TIMEOUT) { ... } // Changing DEFAULT_TIMEOUT to 2000 in version 1.1 won't affect already-compiled clients! // They will continue using 1000 until recompiled
Inline functions have limited evolution possibilities and expose implementation details:
// Bad: Inline function limits future evolution inline fun <reified T : KaSymbol> KaModule.topLevelSymbolsOfType(): Sequence<T> // Good: Regular function allows internal changes fun <T : KaSymbol> KaModule.topLevelSymbolsOfType(klass: KClass<T>): Sequence<T> // Convenience: You can still provide an inline function with a trivial, delegating body inline fun <reified T : KaSymbol> KaModule.topLevelSymbolsOfType(): Sequence<T> = topLevelSymbolsOfType(T::class) // Even better: let the users filter symbols by themselves // or provide distinct functions for specific symbols val KaModule.topLevelSymbols: Sequence<KaSymbol>
For critical inline functions like analyze, embed hooks for future functionality:
inline fun <R> analyze( element: PsiElement, action: KaSession.() -> R ): R { // Current implementation val session = createSession(element) // Hook for future additions without breaking compatibility beforeAnalysis?.invoke(session) return try { session.action() } finally { // Future cleanup hook afterAnalysis?.invoke(session) } }
Be prepared for suspension! Unless the lambda parameter of an inline function is marked with crossinline, or a lambda runs inside a synchronized block, a suspend call may happen inside the passed lambda, and your function body may never be fully executed.
Components group related functionality, providing APIs through the KaSession:
interface KaSession : KaLifetimeOwner, KaResolver, KaSymbolRelationProvider, KaDiagnosticProvider, KaScopeProvider, ...
Before adding a new component, verify that your functionality doesn't fit within an existing one:
// Before creating KaInheritanceComponent, check if KaTypeProvider already handles similar functionality interface KaTypeProvider : KaSessionComponent { val KaType.directSupertypes: Sequence<KaType> // Type inheritance is part of types val KaType.allSupertypes: Sequence<KaType> }
For every component function and property, provide a bridge that accepts a session component as a context parameter:
interface KaScopeProvider : KaSessionComponent { val KaDeclarationContainerSymbol.memberScope: KaScope } /** * @see KaScopeProvider.memberScope */ @KaContextParameterApi context(context: KaScopeProvider) val KaDeclarationContainerSymbol.memberScope: KaScope get() = with(context) { memberScope }
[!TIP] Write clear, comprehensive KDocs covering happy paths, edge cases, also providing examples. Mention contracts, exceptions, and nullability behavior.
Your documentation should answer:
Collection or similar, is the item order specified (or at least stable)?Sequence, can the sequence be iterated over more than once?null or empty collections?When including code examples in documentation, ensure they demonstrate real-world scenarios that help users understand practical usage. Examples should be copy-paste ready, correctly handle all necessary cases, and follow proper Kotlin code style.
Use meaningful names that reflect the domain or are just more pleasant to see, rather than generic placeholders. Avoid random variable names like a, x, or temp. The often-used Foo placeholder may be acceptable when discussing declarations in general terms.
/** * The function symbol for the original Java getter method. * * #### Example: * * ``` * public class JavaClass { * private int field; * * public int getField() { * return field; * } * } * ``` * * In the synthetic property for `field`, [javaGetterSymbol] is the function symbol for `getField`. */ val javaGetterSymbol: KaNamedFunctionSymbol
KDoc is not just a custom comment syntax – it supports Markdown tags. Inside longer documentation comments, use Markdown headers (###) for individual comment sections.
/** * The abbreviated type for this expanded [KaType], or `null` if this type has not been expanded from an abbreviated type or the * abbreviated type cannot be resolved. [...] * * ### Resolvability * * Even when this [KaType] is an expansion, the abbreviated type may be `null` if it is not resolvable from this type's use-site module. * This can occur when the abbreviated type from a module `M1` was expanded at some declaration `D` in module `M2`, and the use-site * module uses `D`, but only has a dependency on `M2`. Then the type alias of `M1` remains unresolved and [abbreviation] is `null`. * * ### Type arguments and nested abbreviated types * * The type arguments of an abbreviated type are not converted to abbreviated types automatically. That is, if a type argument is a type * expansion, its [abbreviation] doesn't automatically replace the expanded type. [...] * * ### Transitive expansion * * Types are always expanded to their final form. That is, if we have a chain of type alias expansions, the [KaType] only represents the * final expanded type, and its [abbreviation] the initial type alias application. [...}] */ val abbreviation: KaUsualClassType?
Use the documentation viewer in IntelliJ IDEA (F1 by default) to check how your documentation looks like for the users.
As explained in the Choose between properties and functions based on semantics section, function and property endpoints are different. The difference should be reflected in the documentation.
For functions, explain what the action does:
/** * Creates a new [KaType] based on the given type with the updated nullability specified by [isMarkedNullable]. * @retur */ fun KaType.withNullability(isMarkedNullable: Boolean): KaType
@param and @return tags can be omitted if the user can get the same information from a more natural description at the beginning of the KDoc. However, add them if there are special cases that need explanation, or to make the description more concise so understanding the general goal of a function is easier.
For properties, just explain what the user gets (or sets) when accessing the property. Avoid verbs like “returns”, “computes” or similar:
/** * A [KaScope] containing the top-level declarations (such as classes, functions and properties) in the given [KaFileSymbol]. */ public val KaFileSymbol.fileScope: KaScope
Try to “hack” your own KDoc. Look for ambiguities or missing information. Don't leave users guessing about special cases:
/** * The compile-time constant initializer for the given property, if available. */ val KaPropertySymbol.compileTimeInitializer: KaConstantValue? // Questions that should be answered: // - Is the expression evaluated or just parsed? // - What happens if the property is not `const`? // - What happens if the initializer isn't a compile-time constant, but it still can be evaluated? // - Does the property work for non-Kotlin (e.g., Java) declarations, including `KaSyntheticJavaPropertySymbol`?
Before committing:
After adding or modifying APIs:
If your API isn't implemented for K1, make it clear:
/** * A list of [KaContextParameterSymbol]s directly declared in the callable symbol. * * As context parameters are not supported in the K1 Kotlin compiler, * in the K1 API implementation the resulting list is always empty. */ @KaK1Unsupported val KaCallableSymbol.contextParameters: List<KaContextParameterSymbol>
Also, if the behavior differs between K1 and K2, describe those differences:
/** * Compiles the given [file] in-memory (without dumping the compiled binaries to the disk). * The file might be either a Kotlin source file, or a [KtCodeFragment]. * * The function rethrows exceptions from the compiler, wrapped in [KaCodeCompilationException]. The implementation should wrap the * `compile()` call into a `try`/`catch` block when necessary. * * ### K1 Implementation Limitations * * The K1 implementation of [compile] does not support [KtCodeFragment]s. * The only existing use-case for code fragment compilation is code evaluation in the JVM debugger, and in the K1 Kotlin plugin for * IntelliJ IDEA compilation is implemented on the IDE side. */ fun compile(file: KtFile, configuration: CompilerConfiguration, target: KaCompilerTarget): KaCompilationResult
Always refer to the K1 compiler and the K1 implementation simply as “K1”. Avoid adjectives such as “legacy”, “classic”, “old” or similar.
Entity naming in the Analysis API differs on whether an entity is referred from inside the same entity hierarchy or from another place. Such as, accessing a getter symbol of a KaPropertySymbol is different from accessing a KaPropertySymbol corresponding to a KtProperty.
For cross-references inside a single entity hierarchy, prefer simpler names to avoid verbosity:
interface KaTypeParameterOwnerSymbol : KaSymbol { val typeParameters: List<KaTypeParameterSymbol> // Not 'typeParameterSymbols' }
Across domain boundaries, prefer more descriptive names:
KaSymbolssymbol (not declaration!) for an arbitrary symbol and when no disambiguation is needed (almost always)functionSymbol for a KaFunctionSymbol and its subtypespropertySymbol for a KaPropertySymbol and its subtypesclassSymbol for a KaClassSymbolfileSymbol for a KaFileSymbolKaTypestype for an arbitrary typeclassType, functionType and others when referring specifically to a function, class, or type (rarely needed)PsiElementspsi for a PsiElement, or for a KtElementdeclaration for a KtDeclaration or its subtypes (when no disambiguation is needed)expression for a KtExpression or its subtypescallExpression (not call!) for KtCallExpressiontypeReference (not type!) for KtTypeReferencescript for a KtScriptRule of thumb: is it clear for the user that they get an entity of a different API domain?
KaSymbol ↔ KaTypeFor example:
sealed class KaClassType : KaType { // From `KaType` to `KaSymbol` val symbol: KaClassLikeSymbol } // From `KaSymbol` to `KaTye` val KaClassifierSymbol.defaultType: KaType
ka and kt PrefixesDon't use ka and kt prefixes for callable names unless absolutely necessary to resolve conflicts:
// Good: Clean names val type: KaType val annotations: List<KaAnnotation> val declaration: KtDeclaration // Bad: Unnecessary prefixes val kaType: KaType val kaAnnotations: List<KaAnnotation> val ktDeclaration: KtDeclaration // Might work, but think of alternatives (e.g., `KaModuleProvider.find(element)`) fun PsiElement.findKaModule(): KaModule?
However, if you handle both API layers in a single place (e.g., you map the Kotlin PSI to FIR), prefer adding prefixes at least for non-primary entities:
fun findDeclaration(file: FirFile, ktDeclaration: KtDeclaration): FirDeclaration
Check for both syntactic and semantic naming conflicts within the API and with external libraries. Before introducing new names, verify they don't clash with existing functionality or create confusion:
// Bad: Clash with 'kotlin.Array' sealed class KaAnnotationValue { class Array : KaAnnotationValue() } // Good: A distinct name sealed class KaAnnotationValue { class ArrayValue : KaAnnotationValue() }
Avoid get prefixes unless they carry special meaning. Choose verbs that reflect the operation's nature. Function names should clearly indicate their behavior and return characteristics:
// Bad: Unnecessary 'get' prefix fun getSupertypes(): List<KaType> fun KtElement.getDiagnostics(filter: KaDiagnosticCheckerFilter): List<KaDiagnosticWithPsi<*>> fun getClass(classId: ClassId): KaClassSymbol? // Good: Direct naming val supertypes: List<KaType> fun KtElement.diagnostics(filter: KaDiagnosticCheckerFilter): List<KaDiagnosticWithPsi<*>> fun findClass(classId: ClassId): KaClassSymbol? // 'find' indicates nullable result // Good: Use appropriate verbs for actions fun buildClassType(classId: ClassId): KaType fun KaType.render(): String fun KtExpression.evaluate(): KaConstantValue?
Don't repeat type information or parameter details in names unless ambiguity takes place. Keep names concise and meaningful.
// Bad: Redundant type information val annotationList: List<KaAnnotation> fun findClassByClassId(classId: ClassId) // Good: Clean, descriptive names val annotations: List<KaAnnotation> fun findClass(classId: ClassId)
Use prefixes that clearly convey the intent and distinguish between different boolean concepts. Boolean property names should indicate what they're checking and when the check is performed:
// Bad: Ambiguous meaning val nullable: Boolean val overridden: Boolean val inline: Boolean // Good: Clear intent with appropriate prefixes val isNullable: Boolean // Current state val hasTypeParameters: Boolean // Existence check val canBeOverridden: Boolean // Capability check val shouldBeInlined: Boolean // Recommendation // Good: Distinguish between temporal states val shouldBeEvaluated: Boolean // Future action recommended val willBeEvaluated: Boolean // Future action will happen val isEvaluated: Boolean // Past/current state
Check that the names of flags are grammatically correct, and they mean exactly what they say.
Mind a difference between an actor and an object. E.g., shouldResolve is a property of the resolver itself, while for a declaration the correct flag name is shouldBeResolved.
Use simple names for nested sealed class implementations, also dropping the Ka prefix. Reserve complex names for top-level classes.
// Good: Simple names for nested implementations sealed class KaConstantValue { class StringValue : KaConstantValue() // Without 'Value', will clash with 'kotlin.String' class IntValue : KaConstantValue() class CharValue : KaConstantValue() } // Good: Descriptive names for top-level sealed implementations sealed class KaClassifierSymbol : KaDeclarationSymbol() sealed class KaClassSymbol : KaClassifierSymbol() abstract class KaTypeAliasSymbol : KaClassifierSymbol()
Use established single-word forms for compound terms commonly used in the programming language industry.
supertype and subtype (not superType or subType)builtin (not builtIn)uint (not uInt, but UInt when in PascalCase)The Analysis API serves various projects with different stability requirements. To prevent accidental usage of unstable APIs or usage-tailored functionality, the Analysis API uses a set of opt-in annotations.
Note that the binary compatibility checker doesn't propagate opt-in annotations from outer classes. If the outer class is annotated, add the same opt-in annotation to all nested classes as well.
@KaExperimentalApi@KaPlatformInterfaceThese APIs are intended to only be used in a specific project, or a group of projects.
@KaNonPublicApi@KaIdeApi@KaImplementationDetail@KaK1UnsupportedThese APIs are intended for all users but depend on unstable language features.
@KaContextParameterApiWhen existing annotations don't cover your use case, consider adding new opt-in annotations.
@KaExperimentalApi) with a dedicated comment is preferred.Experimental APIs have relaxed evolution rules, but they still should maintain quality standards. Write proper documentation and cover the endpoints with tests. When applicable, explain why the API is kept experimental.
Remember – an experimental API becomes stable someday. Avoid breaking your first clients without a strong reason.
All experimental API must be marked with the @KaExperimentalApi annotation.
For detailed information about the lifecycle of experimental APIs and their transition to stable status, see the API Evolution Guide.
[!TIP] API Implementations don't need to provide API compatibility guarantees. However, you should prevent their accidental usage outside the implementation module where possible. Use the fail-fast approach – check input values and throw consistency exceptions when necessary.
internal by DefaultImplementation declarations should be internal unless they need to be part of the public API surface (like KaFirDiagnostic). Minimize accidental exposure of implementation details.
If you cannot make the declaration internal, mark it with @KaImplementationDetail.
All API implementations must validate lifetime ownership and fail fast on invalid access.
Lifetime safety is critical for preventing memory leaks and ensuring correctness:
internal class KaFirNamedClassSymbol( override val firSymbol: FirClassSymbol, override val analysisSession: KaFirSession ) : KaNamedClassSymbol { override val name: Name // Either use 'withValidityAssertion' (preferred) or 'assertIsValidAndAccessible()' get() = withValidityAssertion { firSymbol.name } override val typeParameters: List<KaTypeParameterSymbol> get() = withValidityAssertion { firSymbol.typeParameters.map { it.toKaSymbol() } } }
For endpoints consuming PsiElements, use withPsiValidityAssertion() instead:
override val KtFile.symbol: KaFileSymbol get() = withPsiValidityAssertion { KaFirFileSymbol(this, analysisSession) }
Remember to guard properties you declare in the primary constructor:
class KaScopeWithKindImpl( private val backingScope: KaScope, private val backingKind: KaScopeKind, ) : KaScopeWithKind { override val scope: KaScope get() = withValidityAssertion { backingScope } override val kind: KaScopeKind get() = withValidityAssertion { backingKind } }
For equals(), hashCode() and toString() implementations, avoid validation as these methods are often used in uncontrolled contexts.
Fail fast with clear messages, use appropriate exception types, and document error conditions.
Robust error handling improves developer experience. Use checkWithAttachment, requireWithAttachment, and errorWithAttachment, passing the relevant information. Never pass sensitive information such as code snippets, or names from source code (e.g., names of individual classes or functions) in the exception message directly.
private fun calculateLazyBodyForResultProperty(firProperty: FirProperty, designation: FirDesignation) { val newInitializer = revive<FirAnonymousInitializer>(designation) val body = newInitializer.body requireWithAttachment(body != null, { "${FirAnonymousInitializer::class.simpleName} without body" }) { withFirDesignationEntry("designation", designation) withFirEntry("initializer", newInitializer) } ... }
Document throwing behavior:
/** * @throws IllegalArgumentException if [name] is a special name like <init> */ fun findFunctions(name: Name): Sequence<KaFunctionSymbol> { require(!name.isSpecial) { "Special names are not supported: $name" } // ... }