Friday, November 29, 2002 06:57 PM
Taken from http://java.sun.com/j2se/1.3/docs/guide/misc/deprecation/deprecation.html
How to Deprecate
To deprecate a class or method, use the @deprecated tag, as explained in How to Write Doc Comments for JavaDoc. The paragraph following the @deprecated tag should explain why the item has been deprecated and suggest how the user can avoid using it.
It is not necessary to deprecate individual members of a deprecated class, unless of course the programmer wants to explain some specific point about one member.
Note: Deprecation applies to classes and to individual members, not to their names. It is possible for a single method to have deprecated and non-deprecated overloadings. It is possible for a non-deprecated member to hide or override a deprecated one, which removes deprecation. It is the responsibility of the programmer to deprecate overrides of a deprecated method, if in fact they should be deprecated.
It is probably not good to specifically mention a timetable for phase-out of the deprecated API; this is a business decision that needs to be communicated other ways.
When a feature is deprecated, it is a good idea to notify the engineering organization of this fact, so that other engineers can respond to the change (pro or con) in a timely manner.