Skip to main content

Required parameters after optional ones

DiagnosticREQUIRED_PARAMETER_AFTER_OPTIONAL
Default severityError
Gradle propertyrequiredParameterAfterOptional
Exemption@IntentionallyRequiredParameterAfterOptional

What it reports​

Every required value parameter after a defaulted or vararg parameter in a public API function or constructor. The last parameter is exempt if it accepts a trailing lambda.

public fun request(retries: Int = 3, host: String) { }

Rationale​

To omit an earlier default, callers must name the later required argument. Put required parameters before optional ones.

Don't​

public fun connect(retries: Int = 3, host: String) { }

Do​

public fun connect(host: String, retries: Int = 3) { }

Notes​

The check skips overrides and @PublishedApi internal functions and constructors.

The trailing-lambda exception applies to function types, fun interface types, and Java SAM interfaces in the last position. It doesn't apply to reflection types such as KFunction or to earlier parameters.

Exemption​

If this is intended, apply @IntentionallyRequiredParameterAfterOptional to the function or constructor.

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

@IntentionallyRequiredParameterAfterOptional(
reason = ExemptionReason.FOR_BACKWARDS_COMPATIBILITY,
)
public fun connect(retries: Int = 3, host: String) { }

Configuration​

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

For a direct compiler call:

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

See also​