@deprecated means “this is widely used library code that was either invalid or replaced with something better. It is no longer recommended for use but we will allow you some buffer time (eg.a year or so), in which to change the referring code to use the better suggestion, and the library code is removed completely”
However too often methods are deprecated when it would be almost as painless to fix up the few instances that call it. Code referencing @deprecated methods in client applications tends to stay that way, so you need a compelling reason to deprecate as opposed to removing code. Developers will accept the change if it is explained properly.
Text and examples are Copyright © 2015 Murray Brandon.
