Deprecated Block Tag
ID |
kotlin.deprecated_block_tag |
Severity |
info |
Remediation Complexity |
medium |
Remediation Risk |
low |
Remediation Effort |
medium |
Resource |
Code Smell |
Language |
Kotlin |
Tags |
deprecation, documentation |
Description
Reports KDoc comments that contain a @deprecated tag instead of the @Deprecated(…) annotation.
The Kotlin compiler only enforces deprecation warnings on callers when the @Deprecated annotation is present.
A @deprecated KDoc tag is documentation-only and silently ignored at compile time.
Rationale
Using @deprecated in KDoc gives readers a deprecation hint in the documentation but produces no compiler warning
for callers. Code that depends on the old API will compile without warning until the developer happens to read
the KDoc.
// Bad — compiler does not warn callers
/**
* @deprecated Use newMethod() instead.
*/
fun oldMethod() {}
// Good — compiler enforces the deprecation
@Deprecated("Use newMethod() instead", ReplaceWith("newMethod()"))
fun oldMethod() {}