kotlin-stdlib/kotlin/Deprecated

Deprecated

@Target(allowedTargets = [AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.PROPERTY_SETTER, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.TYPEALIAS])
annotation class Deprecated(val message: String, val replaceWith: ReplaceWith = ReplaceWith(""), val level: DeprecationLevel = DeprecationLevel.WARNING)(source)

Marks the annotated declaration as deprecated.

A deprecated API element is not recommended to use, typically because it's being phased out or a better alternative exists.

To help removing deprecated API gradually, the property level could be used. Usually a gradual phase-out goes through the "warning", then "error", then "hidden" or "removed" stages:

  • First and by default, DeprecationLevel.WARNING is used to notify API consumers, but not to break their compilation or runtime usages.

  • Then, some time later the deprecation level is raised to DeprecationLevel.ERROR, so that no new Kotlin code can be compiled using the deprecated API.

  • Finally, the API is either removed entirely, or hidden (DeprecationLevel.HIDDEN) from code, so its usages look like unresolved references, while the API remains in the compiled code preserving binary compatibility with previously compiled code.

Since Kotlin

1.0
@Target(allowedTargets = [AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.PROPERTY_SETTER, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.TYPEALIAS])
annotation class Deprecated(val message: String, val replaceWith: ReplaceWith = ReplaceWith(""), val level: DeprecationLevel = DeprecationLevel.WARNING)(source)

Marks the annotated declaration as deprecated.

A deprecated API element is not recommended to use, typically because it's being phased out or a better alternative exists.

To help removing deprecated API gradually, the property level could be used. Usually a gradual phase-out goes through the "warning", then "error", then "hidden" or "removed" stages:

  • First and by default, DeprecationLevel.WARNING is used to notify API consumers, but not to break their compilation or runtime usages.

  • Then, some time later the deprecation level is raised to DeprecationLevel.ERROR, so that no new Kotlin code can be compiled using the deprecated API.

  • Finally, the API is either removed entirely, or hidden (DeprecationLevel.HIDDEN) from code, so its usages look like unresolved references, while the API remains in the compiled code preserving binary compatibility with previously compiled code.

Since Kotlin

1.3

Properties

Link copied to clipboard
val level: DeprecationLevel

Specifies how the deprecated element usages are reported in code. See the DeprecationLevel enum for the possible values.

Since Kotlin 1.0
val level: DeprecationLevel

Specifies how the deprecated element usages are reported in code. See the DeprecationLevel enum for the possible values.

Since Kotlin 1.3
Link copied to clipboard
val message: String

The message explaining the deprecation and recommending an alternative API to use.

Since Kotlin 1.0
val message: String

The message explaining the deprecation and recommending an alternative API to use.

Since Kotlin 1.3
Link copied to clipboard
val replaceWith: ReplaceWith

If present, specifies a code fragment which should be used as a replacement for the deprecated API usage.

Since Kotlin 1.0
val replaceWith: ReplaceWith

If present, specifies a code fragment which should be used as a replacement for the deprecated API usage.

Since Kotlin 1.3