Deprecated Annotation

The @Deprecated annotation in Kotlin is a built-in marker applied to program elements (such as classes, functions, properties, or type aliases) to indicate that their usage is discouraged and slated for future removal. Unlike Java’s standard deprecation marker, Kotlin’s implementation is highly configurable, allowing developers to define strict compiler severity levels and provide automated code migration paths directly within the annotation metadata.

@Deprecated(
    message = "Explanation of deprecation",
    replaceWith = ReplaceWith("newFunction()"),
    level = DeprecationLevel.WARNING
)
fun oldFunction() {}

Annotation Parameters

The @Deprecated annotation accepts three parameters that dictate the compiler’s behavior and the IDE’s static analysis tooling:

1. message (Required) A String literal detailing the reason for deprecation and identifying the preferred alternative. This message is surfaced in compiler logs and IDE tooltips.

2. replaceWith (Optional) An instance of the ReplaceWith annotation. It defines a structural replacement for the deprecated element, enabling IDEs to offer automated quick-fixes.

• expression: A string representing the new code snippet.
• imports: An array of strings specifying any fully qualified imports required for the new expression to compile.

3. level (Optional) A DeprecationLevel enum value that instructs the Kotlin compiler on how to handle references to the annotated element.

Deprecation Levels

Kotlin enforces deprecation at the compiler level using three distinct states:

• DeprecationLevel.WARNING (Default): The compiler emits a standard warning during the build process. The code will still compile and execute successfully.
• DeprecationLevel.ERROR: The compiler treats any reference to the element as a fatal compilation error, halting the build. This forces consumers to migrate away from the element immediately.
• DeprecationLevel.HIDDEN: The element is completely removed from the public API resolution scope. It cannot be referenced or called from Kotlin source code. However, the element is preserved in the compiled bytecode, maintaining binary compatibility for legacy compiled clients that already reference it.

Syntax Visualization

// Demonstrating automated migration and strict compiler enforcement
@Deprecated(
    message = "Use the optimized computeHash() instead.",
    replaceWith = ReplaceWith(
        expression = "computeHash(data)",
        imports = ["com.example.utils.computeHash"]
    ),
    level = DeprecationLevel.ERROR
)
fun calculateMD5(data: String): String {
    return "..."
}

JVM Interoperability

When Kotlin code is compiled to JVM bytecode, the Kotlin @Deprecated annotation is automatically translated to the standard @java.lang.Deprecated annotation.

Because Java does not natively support Kotlin’s advanced deprecation mechanics, the replaceWith and level parameters are ignored by the Java compiler. Consequently, a Kotlin element marked with DeprecationLevel.ERROR or DeprecationLevel.HIDDEN will only manifest as a standard warning when invoked from Java source code. To hide deprecated Kotlin elements from Java callers entirely, the @JvmSynthetic annotation must be applied alongside @Deprecated.

Master Kotlin with Deep Grasping Methodology!

Learn More