Should I use JavaDoc deprecation or the annotation in Java?

There are at the moment, two ways to mark code as depreacted in java.

Via JavaDoc

/**
 * @deprecated
 */

Or as an annotation:

@Deprecated

This is my problem - I find it a bit too much to declare both, when marking a method as deprecated when using Eclipse. I really just want to use one of them.

However does using the annotation give the compiler actual useful additional information?

But only using the annotation, I cannot state why the method is deprecated - I can only do that with JavaDoc, and deprecating a method without specying why is bad.

So, can I only use one of them? Or should I really just learn to specify both?

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...

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.

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(){..}

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!

This can be easily dealt with a good IDE.

Eclipse Neon, for eg. automatically adds @Deprecated annotation, when I create a javadoc @deprecated on a method or field.

So I simply write the javadoc with the appropriate explanation and let the IDE take care of adding the @Deprecated annotation, the minute I save the file.