Android Deprecated Annotation is deprecated, what's the replacement?

It was a documentation bug. (And it has been fixed!)

The Deprecated annotation is not really deprecated.

Apparently what happened is that the source code for Deprecated contained this in its javadoc comments:

 * @apiNote
 * It is strongly recommended that the reason for deprecating a program element
 * be explained in the documentation, using the {@code @deprecated}
 * javadoc tag. 

Apparently, the {@code @deprecated} was interpreted as an @deprecated javadoc tag by the metalava tool. This caused metalava to inject the "missing" @Deprecated annotations into the ".class" files in the Android JAR file. Presumably, the injected annotation was then incorporated into the generated javadocs on the website.

Kudos to Manohar Reddy for finding the bug in the issue tracker.

You can find the fix that they made here.

For what it is worth, java.lang.Deprecated is a class that originates in the Oracle / OpenJDK Java (i.e. standard Java) class libraries. Android wouldn't / shouldn't deliberately deprecate it without a very good reason. It would create another hurdle to Java <-> Android portability.

---