Nullable Booleans in public API
| Diagnostic | NULLABLE_BOOLEAN_PUBLIC_API |
| Default severity | Error |
| Gradle property | nullableBooleanPublicApi |
| Exemption | @IntentionallyNullableBoolean |
What it reports
Boolean? in these parts of the public API, including nested type arguments and expanded type aliases:
- Function return types and property types.
- Value and context parameter types, including constructor parameters.
- Type parameter bounds.
public fun probe(): Boolean? = null
Rationale
Boolean? adds an unnamed third state. A domain type names each state so callers don't have to infer what null means.
Don't
public fun connectionState(): Boolean? = null
Do
public enum class ConnectionState {CONNECTED,DISCONNECTED,UNKNOWN,}public fun connectionState(): ConnectionState = ConnectionState.UNKNOWN
Notes
The check skips:
- Extension receivers on
Boolean?type. - Overrides.
- Java platform types.
@PublishedApi internaldeclarations.
Exemption
If this is intended, apply @IntentionallyNullableBoolean to the declaration,
parameter, or type usage.
Use the exemption when the declaration is part of the API design or must stay for backwards compatibility.
@IntentionallyNullableBoolean(reason = ExemptionReason.API_DESIGN)public fun connectionState(): Boolean? = null
Configuration
build.gradle.kts
apiWatchdog {nullableBooleanPublicApi = WatchdogSeverity.ERROR}
For a direct compiler call:
-P plugin:org.jetbrains.kotlinx.library.api.watchdog:diagnosticSeverity=NULLABLE_BOOLEAN_PUBLIC_API:error