Skip to main content

Public types marked as internal API

DiagnosticPUBLIC_TYPE_WITH_INTERNAL_API
Default severityAlways an error while enabled
Gradle propertypublicTypeWithInternalApi
Exemption@IntentionallyExposedInternalApiForBackwardsCompatibility

What it reports​

A type marked with an internal API annotation in a public API signature:

@InternalAnnotationMarker
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
public annotation class InternalLibApi
@InternalLibApi
public class InternalModel
public fun loadModel(): InternalModel = InternalModel()

Rationale​

Callers must use the types in a supported declaration's signature. An internal API type has no supported compatibility contract, so changes can break those callers.

Expose a supported type instead:

public class Model
public fun loadModel(): Model = Model()

Notes​

  • The check skips @PublishedApi internal signatures.
  • An internal API annotation on an enclosing class also marks its nested types.
  • Type aliases don't hide internal API annotations on the alias or its expanded type.
  • If the exposing declaration is also internal API, mark it with the internal API annotation.

Exemption​

If this is intended, apply @IntentionallyExposedInternalApiForBackwardsCompatibility to the declaration, a parameter, or a type usage.

Both fixes break the users of a published declaration. One removes the type from the signature. The other adds an internal API annotation with an opt-in requirement. The exemption doesn't have a reason parameter, because backwards compatibility is the only valid reason. Its description is optional:

@InternalAnnotationMarker
@Target(AnnotationTarget.CLASS)
public annotation class InternalLibApi
public class InternalModel
@IntentionallyExposedInternalApiForBackwardsCompatibility(description = "Shipped in 1.0.")
public fun loadModel(): InternalModel = InternalModel()

On a class, the annotation covers the supertypes and the type parameter bounds, not the members. Each member that exposes an internal type needs its own annotation, so a new member stays checked. The exemptExistingApi task adds the annotation to the reported declaration.

Configuration​

publicTypeWithInternalApi is true by default. The check can't report warnings. To disable it:

build.gradle.kts
apiWatchdog {
publicTypeWithInternalApi = false
}

For a direct compiler call:

-P plugin:org.jetbrains.kotlinx.library.api.watchdog:publicTypeWithInternalApi=false

See also​