Exemptions and internal API
Four mechanisms exclude a declaration from a check while the check stays enabled for the project:
| Mechanism | Excludes | From |
|---|---|---|
| Exemption annotation | One declaration | One check |
| Dependency exemption | Every use of a dependency's types in the module | One check |
| Internal API annotation | One declaration and the declarations nested in it | Every public API check |
| Annotation ignore rule | Every declaration with a given annotation | One 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:
| Parameter | Type | Default |
|---|---|---|
description | String | "" |
reason | ExemptionReason | OTHER |
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
expectdeclaration, such as Boolean parameters in public API, reads the exemption there. The compiler reportsACTUAL_ANNOTATIONS_NOT_MATCH_EXPECTwhen anactualdeclaration doesn't have an annotation of itsexpectdeclaration, so put a copy on eachactualdeclaration. - A check that reports an
actualdeclaration, such as Kotlin-only API without JvmSynthetic, reads an exemption on thatactualdeclaration. It also reads an exemption on theexpectdeclaration. That exemption then needs a copy on eachactualdeclaration.
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
expectclass 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
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:
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 watchedpublic 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:
- Exemptions without explanation,
- DSL markers with no-op targets,
- DSL markers without explicit targets, and
- DSL markers on no-op type positions.
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:
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.
import org.jetbrains.kotlinx.library.api.watchdog.WatchdogChecksapiWatchdog {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.