Skip to main content

Exemptions and internal API

Four mechanisms exclude a declaration from a check while the check stays enabled for the project:

MechanismExcludesFrom
Exemption annotationOne declarationOne check
Dependency exemptionEvery use of a dependency's types in the moduleOne check
Internal API annotationOne declaration and the declarations nested in itEvery public API check
Annotation ignore ruleEvery declaration with a given annotationOne configurable check

Exemption annotations​

An @Intentionally* annotation exempts one declaration from one check. Use it when the declaration has a reason to break the rule of the check, and state the reason on the annotation.

The "Exemption" section of each check page names the exemption annotation (example for data classes).

Every @Intentionally* annotation except @IntentionallyWrongDslMarkerTargetsForBackwardsCompatibility has two parameters:

ParameterTypeDefault
descriptionString""
reasonExemptionReasonOTHER

FOR_BACKWARDS_COMPATIBILITY, API_DESIGN, and FOR_DEPRECATION explain the exemption on their own. Every other reason needs a description, or Exemptions without explanation reports the annotation. Redundant exemptions reports an exemption that its check doesn't need.

An explained exemption:

@IntentionallyDataClass(
description = "Serialized as-is by the legacy RPC layer, " +
"which reflects on componentN.",
reason = ExemptionReason.INTEROP,
)
public data class LegacyConfig(
public val host: String,
public val port: Int,
)

For a published API, the exemptExistingApi task adds the exemptions.

Exemptions in a multiplatform project​

Put the exemption on the declaration that the check reports:

  • A check that reports the expect declaration, such as Boolean parameters in public API, reads the exemption there. The compiler reports ACTUAL_ANNOTATIONS_NOT_MATCH_EXPECT when an actual declaration doesn't have an annotation of its expect declaration, so put a copy on each actual declaration.
  • A check that reports an actual declaration, such as Kotlin-only API without JvmSynthetic, reads an exemption on that actual declaration. It also reads an exemption on the expect declaration. That exemption then needs a copy on each actual declaration.

exemptExistingApi adds the exemption where the check reports and the copies on the actual declarations. See Redundant exemptions for more details about an exemption that neither the expect declaration nor its actual declarations need.

When the actual class declares a property as a val constructor parameter, put the copy of the property's exemption on that constructor parameter.

Actual type aliases​

For an actual typealias, the compiler requires the annotations of the expect class on the class that the type alias expands to, not on the type alias. exemptExistingApi doesn't add a copy to that class:

  • A class of another module can't get an annotation.
  • The exemption on the expect class doesn't exempt the class that the type alias expands to. An annotation on a class of the module is an exemption of that class only. When that class doesn't break the rule of the check, Redundant exemptions reports the annotation.

When the compiler reports ACTUAL_ANNOTATIONS_NOT_MATCH_EXPECT for an actual typealias, add @Suppress("ACTUAL_ANNOTATIONS_NOT_MATCH_EXPECT") to the type alias.

The DSL marker exemption​

@IntentionallyWrongDslMarkerTargetsForBackwardsCompatibility exempts a DSL marker from DSL markers with no-op targets and DSL markers without explicit targets. It doesn't have a reason parameter, because backwards compatibility is the only valid reason for this exemption. Its description is optional.

All exemption annotations​

AnnotationExempts
@IntentionallyOpenOpen API without subclass opt-in
@IntentionallyExhaustiveExhaustive public API
@IntentionallyUndocumentedUndocumented public API
@IntentionallyFunctionTypeAliasFunction type aliases in public API
@IntentionallyDataClassData classes in public API
@IntentionallyWithoutEqualsHashCodeOrToStringAll three stateful class checks
@IntentionallyWithoutEqualsStateful classes without equals, hashCode, and toString
@IntentionallyWithoutHashCodeStateful classes without equals, hashCode, and toString
@IntentionallyWithoutToStringStateful classes without equals, hashCode, and toString
@IntentionallyMutableCollectionMutable collections in public API
@IntentionallyPairOrTriplePair and Triple in public API
@IntentionallyBooleanParameterBoolean parameters in public API
@IntentionallyNullableBooleanNullable Booleans in public API
@IntentionallyRequiredParameterAfterOptionalRequired parameters after optional ones
@IntentionallyInconsistentParameterOrderInconsistent parameter order in overloads
@IntentionallyInlinedLogicInline functions with logic
@IntentionallyMangledJvmNameMangled JVM names in public API
@IntentionallyKotlinOnlyApiKotlin-only API without JvmSynthetic
@IntentionallyNonStaticCompanionApiCompanion function without JvmStatic and Companion property without static access
@IntentionallyDefaultFacadeNameTop-level API without JvmName
@IntentionallyWithoutJvmOverloadsDefault parameters without JvmOverloads
@IntentionallyNonTransitiveDependencyPublic types from non-transitive dependencies
@IntentionallyWrongDslMarkerTargetsForBackwardsCompatibilityDSL markers with no-op targets and DSL markers without explicit targets

Dependency exemptions​

A dependency exemption exempts every use of a dependency's types in the module from Public types from non-transitive dependencies. Use it instead of @IntentionallyNonTransitiveDependency on each declaration when the whole module exposes the dependency's types. Declare the dependency on the apiWatchdogExemptNonTransitive configuration:

build.gradle.kts
dependencies {
compileOnly("com.example:models:1.0")
apiWatchdogExemptNonTransitive("com.example:models")
}

Exempting a dependency on the check page describes the configuration.

Internal API annotations​

An internal API annotation, such as @InternalMyLibraryApi, excludes a declaration from every public API check. Use it when a declaration is public only for technical reasons and the library doesn't give a compatibility guarantee for it.

Annotate the library's internal API annotation with @InternalAnnotationMarker:

@InternalAnnotationMarker
@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
public annotation class InternalMyLibraryApi
@InternalMyLibraryApi // Internal API, not watched
public class ReflectionHelper

The public API checks skip every declaration with the marked annotation and every declaration nested in it. Four checks still run there, because they check every visibility:

The marker annotation class itself is public API and stays watched.

A public declaration without the annotation must not use an internal API type in its signature. Public types marked as internal API reports the declaration as an error.

An annotation class from a dependency can't carry @InternalAnnotationMarker. List its fully qualified name in internalApiAnnotations instead. The plugin then treats it like a marked annotation:

build.gradle.kts
apiWatchdog {
internalApiAnnotations.add("com.example.dependency.InternalDependencyApi")
}

See Without Gradle for more details about the compiler option.

Annotation ignore rules​

An annotation ignore rule skips one check on every declaration that carries a given annotation. Use it when every annotated declaration already satisfies the check.

build.gradle.kts
import org.jetbrains.kotlinx.library.api.watchdog.WatchdogChecks
apiWatchdog {
ignore(
WatchdogChecks.STATEFUL_CLASS_WITHOUT_EQUALS,
whenAnnotatedWith = listOf("com.example.GeneratedValueMembers"),
)
}

A rule works for configurable checks only, not for always-error checks. With recursive = true, the rule also covers every declaration nested in the annotated one.

The annotations artifact​

The @Intentionally* annotations, @InternalAnnotationMarker, and ExemptionReason are in org.jetbrains.kotlinx:kotlin-library-api-watchdog-plugin-annotations. The Gradle plugin adds this dependency to the project.