Skip to main content

Boolean parameters in public API

DiagnosticBOOLEAN_PARAMETER_PUBLIC_API
Default severityError
Gradle propertybooleanParameterPublicApi
Exemption@IntentionallyBooleanParameter

What it reports​

Boolean and Boolean? value and context parameters of functions in the public API. For a vararg parameter, the check uses its element type. Type aliases don't exempt a parameter.

public fun doWork(optimizeForSpeed: Boolean) {}

Rationale​

A positional call such as setLogging(true) doesn't show what the Boolean controls. Separate operations or a domain type make the call readable.

Don't​

public fun setLogging(enabled: Boolean) {}

Do​

public fun enableLogging() {}
public fun disableLogging() {}

Notes​

The check skips:

  • Overrides.
  • Constructors and factory functions named after their return type, such as fun Widget(visible: Boolean): Widget.
  • Legacy context receivers.
  • @PublishedApi internal functions.

Nullable Booleans in public API also reports Boolean? parameters.

Exemption​

If this is intended, apply @IntentionallyBooleanParameter to the function or Boolean parameter.

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

@IntentionallyBooleanParameter(reason = ExemptionReason.API_DESIGN)
public fun setIsVerbose(enabled: Boolean) {}

Configuration​

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

For a direct compiler call:

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

See also​