Skip to main content

Nullable Booleans in public API

DiagnosticNULLABLE_BOOLEAN_PUBLIC_API
Default severityError
Gradle propertynullableBooleanPublicApi
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 internal declarations.

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

See also​