> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Kotlin 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.
```kotlin theme={"dark"}
@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
```kotlin theme={"dark"}
// 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`.
Tired of Poor Kotlin Skills? Fix That With Deep Grasping!
Learn More
