Skip to main content

DSL markers without explicit targets

DiagnosticDSL_MARKER_WITHOUT_EXPLICIT_TARGETS
Default severityError
Gradle propertydslMarkerWithoutExplicitTargets
Exemption@IntentionallyWrongDslMarkerTargetsForBackwardsCompatibility

What it reports​

A @DslMarker annotation class without @Target, or with an empty @Target():

@DslMarker
public annotation class DefaultTargetsDsl
@DslMarker
@Target()
public annotation class EmptyTargetsDsl

Rationale​

The default targets omit TYPE and TYPEALIAS and let callers apply markers without a DSL scope effect. An empty target set prevents every usage.

Don't​

@DslMarker
public annotation class HtmlDsl

Do​

@DslMarker
@Target(
AnnotationTarget.CLASS,
AnnotationTarget.ANNOTATION_CLASS,
AnnotationTarget.TYPE,
AnnotationTarget.TYPEALIAS,
)
public annotation class HtmlDsl

Notes​

  • The check applies to markers of any visibility.
  • The check accepts any non-empty subset of CLASS, ANNOTATION_CLASS, TYPE, and TYPEALIAS.
  • DSL markers with no-op targets checks explicit ineffective targets.

Exemption​

If this is intended, apply @IntentionallyWrongDslMarkerTargetsForBackwardsCompatibility to the DSL marker.

Use the exemption if an explicit target set on a published marker rejects existing user code:

@IntentionallyWrongDslMarkerTargetsForBackwardsCompatibility(
description = "Published without targets in 1.0.",
)
@DslMarker
public annotation class HtmlDsl

The annotation doesn't have a reason parameter. Its description is optional.

Configuration​

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

For a direct compiler call:

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

See also​