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. JUSTIFICATION : 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 : EXPECTED - 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) ======================================================================
|