Boolean parameters in public API
| Diagnostic | BOOLEAN_PARAMETER_PUBLIC_API |
| Default severity | Error |
| Gradle property | booleanParameterPublicApi |
| 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 internalfunctions.
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