JDK-5105736 : (anno) Deprecated annotation needs way to add comment and/or replacement api (value)
  • Type: Enhancement
  • Component: core-libs
  • Sub-Component: java.lang
  • Affected Version: 5.0
  • Priority: P4
  • Status: Closed
  • Resolution: Won't Fix
  • OS: linux
  • CPU: x86
  • Submitted: 2004-09-22
  • Updated: 2005-10-21
  • Resolved: 2005-10-21
Name: rmT116609			Date: 09/22/2004

The @deprecated javadoc tag supports commentary which can be used to indicate a reason for deprecation and/or a replacement api.
The @Deprecated annotation does not support this.

Since the @Deprecated annotation does not support any attributes, we are left with one of three choices:
  1 - Redundantly use both the javadoc and annotation tags
  2 - Use only the @Deprecated and just don't document reasons and replacement APIs
  3 - Use only the javadoc tag

None of these options are very attractive.  In practice, #1 will degenerate into either #2 or #3, depending on the individual developer or team preference (nobody wants to do anything twice).
#2 does not allow enough information.  So we are left with #3 which begs the question of exactly why the new @Deprecated annotation was introduced in the first place.

Being an annotation, the @Deprecated tag has a potential for holding much richer information.  At a minimum, it could support a comment (value) attribute.  But it could also add rich information such as a "deprecated since" version, pointer to replacement APIs, links to additional information, etc.
(Incident Review ID: 311527) 

EVALUATION The deprecation.html page mentioned above describes this in more detail, but in short, here is the way to think about @Deprecated vs. @deprecated. The @Deprecated annotation is a Java language feature used to deprecate an element, and the @deprecated javadoc tag is the way to document when and why this was done and perhaps provide alternatives. Within a public API you should pretty much never use one without the other. Analogously, the "throws" keyword is a Java language feature used to indicate the exceptions thrown by a method, and the "@throws" javadoc tag is the way to document when those exceptions are thrown. Just as we will not be adding comments to the "throws" keyword, we should not be adding comments to the @Deprecated annotation. Javadoc serves for that purpose.

EVALUATION The @Deprecated annotation was designed to your choice #1, and is described here: http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/deprecation/deprecation.html It would seem a bit unwieldy to put doc comments in an attribute of the @Deprecated annotation. (Can annotations have attributes?) ###@###.### 2004-09-22