Name: rmT116609 Date: 09/22/2004
A DESCRIPTION OF THE REQUEST :
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.
EXPECTED VERSUS ACTUAL BEHAVIOR :
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)