Difference between @Deprecated and @deprecated

Question

What’s the difference between @Deprecated as an annotation in the class and @deprecated in the documentation of the same? When to use one and when to use the other?

/**
 * Combo box that shows the status of playlist items.
 *
 * @deprecated Use CustomComboBox from Custom-UI.
 */
@Deprecated
public class CustomComboBox extends JComboBox {}

Thank you.

Answer 1

@Deprecated is an annotation interpreted at compile time to indicate that the method/class is deprecated. This will generate warnings and markups in the IDE when you use a deprecated feature.

@deprecated is a javadoc tag, to document some detail about the depreciation of the method/class. Usually this documentation explains why the depreciation and what to use as a replacement. It only makes sense to use this documentation if you actually have the element being documented marked as @Deprecated

For example:

/**
 * Método que faz alguma coisa
 * @deprecated Esse método possui uma falha muito grave e não deve ser utilizado, agora deve-se utilizar {@link #metodoFazAlgoMelhorado()}.
 */
@Deprecated
public void metodoFazAlgo() {
    // ...
}

public void metodoFazAlgoMelhorado() {
    // ...
}