Javadoc style guide: deprecations

[javier-godoy]

There is a @Deprecated annotation, and there is also a @deprecated javadoc tag (that predates the annotation).

There should be a guideline on which one to use.

  /** Sets the foo.
   * @param foo the foo to be set.
   * @deprecated Use {@code setFooBar} instead.*/
  @Deprecated(forRemoval = true)
  void setFoo(Object foo) {
    // ...
  }

[javier-godoy]

IMHO both must be required.

• The annotation provides an idiomatic way of indicating deprecations. It has runtime retention and optional since/forRemoval attributes.
• The javadoc tag allows an optional message providing additional information on the deprecation (e.g. whether the method was replaced, or whether a feature does not work as intended).

[paodb]

I agree that both should be present. Here's some additional information to the reasons Javier commented before.