Skip to main content

Pair and Triple in public API

DiagnosticPAIR_OR_TRIPLE_PUBLIC_API
Default severityError
Gradle propertypairOrTriplePublicApi
Exemption@IntentionallyPairOrTriple

What it reports​

Pair or Triple 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 locate(): Pair<Int, Int> = 0 to 0

Rationale​

first, second, and third don't name the components' meanings. A domain class names each component and can add properties while its return type stays the same.

Don't​

public fun dimensions(): Triple<Int, Int, Int> = Triple(0, 0, 0)

Do​

public class Dimensions(
public val width: Int,
public val height: Int,
public val depth: Int,
)
public fun dimensions(): Dimensions = Dimensions(0, 0, 0)

Notes​

The check skips:

  • Extension receivers on these types.
  • Overrides.
  • @PublishedApi internal declarations.

Exemption​

If this is intended, apply @IntentionallyPairOrTriple 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.

@IntentionallyPairOrTriple(reason = ExemptionReason.API_DESIGN)
public fun dimensions(): Triple<Int, Int, Int> = Triple(0, 0, 0)

Configuration​

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

For a direct compiler call:

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

See also​