Should I use JavaDoc deprecation or the annotation in Java?

java annotations javadoc deprecated
corgrath picture corgrath · Feb 18, 2011 · Viewed 23.1k times · Source

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?

Answer

Rawrgramming picture Rawrgramming · Feb 18, 2011

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

Related questions

How do I add package level annotations or edit package-info.java?

I'm trying to add package level annotations but I don't have a clue on how to do it. Examples are appreciated.

Read More
codestyle; put javadoc before or after annotation?

I know that it isn't the most vital of issues, but I just realised that I can put the javadoc comment block before or after the annotation. What would we want to adopt as a coding standard? /** * This is a …

Read More
Do I need to @Nonnull again at the implementation?

While I think there should be a general rule for inheriting annotations or not, I'm specifically interested in making FindBugs recognize my rules, so this question is FindBugs specific. AFAIK, JavaDoc comments are taken from the interface and are ignored …

Read More