Should I use JavaDoc deprecation or the annotation in Java?

Solution 1:

You should use both. The Annotation allows the compiler to display a warning whenever a deprecated method is used, and the javadoc explains why. Both are important.

As per Oracle's Java Annotations tutorial:

When an element is deprecated, it should also be documented using the Javadoc @deprecated tag...

Solution 2:

From the horse's mouth:

NOTE: The Java Language Specification requires compilers to issue warnings when classes, methods, or fields marked with the @Deprecated annotation are used. Compilers are not required by the Java Language Specification to issue warnings when classes, methods, or fields marked with the @deprecated Javadoc tag are accessed, although the Sun compilers currently do so.

So basically, if you want a guarantee that there will be compiler warnings, you need to use the annotation. And because of some API designer's breathtaking incompetence, you need to specify the javadoc tag as well to give an explanation.

Personally, I'd say the annotation is useless and should be omitted until it's fixed, since any good compiler or IDE will display warnings with the javadoc tag as well.

Solution 3:

You should write both. The @Deprecated Anotation is for the Compiler and the @deprecated JavaDoc tag is for the Person who wants to know why this is deprecated.

An example can look like this:

/**
* @deprecated We dont need this Method because ...
*/
@Deprecated
public void doStuff(){..}

Solution 4:

You should specify both.

The annotation lets the compiler know about it and trigger warnings when the method is used. The JavaDoc attribute lets developers know about before they start using it.

These are two very different things!