Skip to main content

Exhaustive public API

DiagnosticEXHAUSTIVE_PUBLIC_API
Default severityError
Gradle propertyexhaustivePublicApi
Exemption@IntentionallyExhaustive

What it reports​

An enum class, sealed class, or sealed interface in the public API.

public enum class Status {
ACTIVE,
INACTIVE,
}

Rationale​

Users can match an enum or sealed hierarchy without an else branch. A new entry or subtype then makes those expressions fail to compile.

Don't​

public enum class LogLevel {
DEBUG,
INFO,
ERROR,
}

Do​

public class LogLevel {
public companion object {
public val DEBUG: LogLevel = LogLevel()
public val INFO: LogLevel = LogLevel()
public val ERROR: LogLevel = LogLevel()
}
}

Don't​

public sealed interface Event {
public class Started : Event
public class Stopped : Event
}

Do​

@SubclassOptInRequired(InternalMyLibrarySubclassApi::class)
public interface Event {
public class Started : Event
public class Stopped : Event
}

Notes​

  • Open and abstract subclasses of a sealed hierarchy can also need subclass opt-in. See Open API without subclass opt-in for more details.
  • @PublishedApi internal types aren't reported.

Exemption​

If this is intended, apply @IntentionallyExhaustive to the enum or sealed hierarchy.

Use the exemption when the declaration is part of the API design or must stay for backwards compatibility.

@IntentionallyExhaustive(reason = ExemptionReason.API_DESIGN)
public enum class LogLevel {
DEBUG,
INFO,
ERROR,
}

Configuration​

build.gradle.kts
apiWatchdog {
exhaustivePublicApi = WatchdogSeverity.ERROR
}

For a direct compiler call:

-P plugin:org.jetbrains.kotlinx.library.api.watchdog:diagnosticSeverity=EXHAUSTIVE_PUBLIC_API:error

See also​