41

I'm able to deprecate a function or class with the @Deprecated annotation.

But there is a @deprecated javadoc tag in a javadoc comment itself marking the class/function as deprecated. Does the @deprecated javadoc tag actually make the class/function deprecated?

David Rawson
  • 17,631
  • 6
  • 78
  • 112
N K
  • 2,953
  • 4
  • 20
  • 37
  • Do you mean the Javadoc comment? What XML comment are you asking about? – Elliott Frisch Dec 19 '13 at 05:35
  • @ElliottFrisch, Yes it's. I'm a C# developer, I said it in my perspective. Javadoc is the term in Java. – N K Dec 19 '13 at 05:37
  • @Bohemian, please read the answers of questions you marked as original. They all enforce to use either only @@Deprecated or both. Not only @@deprecated – N K Dec 19 '13 at 05:48

2 Answers2

101

@Deprecated is an annotation that is read by the compiler, used to mark a method as deprecated to the compiler and will generate a deprecation compile-time warning if the method is used.

@deprecated is a javadoc tag used to provide documentation about the deprecation. You can use it to explain why the method was deprecated and to suggest an alternative. It only makes sense to use this tag in conjunction to the @Deprecated annotation.

Example usage:

/**
 * This method does ...
 * @deprecated As of <product> <version>, because ... use
 *             {@link #replacementMethod()} instead.
 */
@Deprecated
public void deprecatedMethod() {
    // ...
}

Here is a guide on deprecation, check it out for more information.

To answer your question more specifically, you should either use @Deprecated or both. The @Deprecated annotation marks your method as deprecated to any tool that cares about it, as it is available during both run-time and compile-time. The javadoc tool takes notice of @Deprecated and documents the deprecation even if you didn't use the @deprecated tag.

If we document a method as deprecated by using the javadoc tag, but without annotating it with the annotation, then the information about the deprecation will not be available in the compiled class files.

Ben Barkay
  • 5,115
  • 2
  • 18
  • 29
  • 1
    The "Guide on deprecation" link is not more active. I suggest you fix it. thanks – gersonZaragocin Apr 21 '15 at 17:50
  • 1
    You could say the link was... deprecated! :D Anyway, does anyone know why Eclipse strikes through and marks in red the invocations of a `@deprecated` method, but not of a `@Deprecated` method? I would expect it the other way around or marked for both. It also doesn't show me a warning for the usage of either, but that might be because of my setting. – Fabian Röling Feb 13 '18 at 11:17
  • @Fabian Eclipse (and most other IDEs) understands javadoc (among a variety of other languages/formats), and thus it seems to use this information to mark your function as deprecated. I suppose that my answer suggests that an IDE shouldn't do that, which I suppose is debatable -- What will happen when you use that project as a compiled jar dependency, and there is no javadoc? Will your method still be marked deprecated? – Ben Barkay Feb 13 '18 at 16:39
  • I will try that... one day. I put it on my todo list, so it can take a while. – Fabian Röling Feb 13 '18 at 19:34
19

@deprecated Javadoc Tag: You can use the @deprecated tag to make Javadoc show a program element as deprecated. The @deprecated tag must be followed by a space or newline.

@Deprecated Using the @Deprecated annotation to deprecate a class, method, or field ensures that all compilers will issue warnings when code uses that program element. In contrast, there is no guarantee that all compilers will always issue warnings based on the @deprecated Javadoc tag

refer here

Nambi
  • 11,454
  • 3
  • 34
  • 49