It would be useful to have a way to mark functions/classes/etc. as "deprecated". Two use cases (from Crell):
1) For intra-version devs (read, core devs) to know that the API they're about to use is slated for execution, so they should use the new one instead. Eg, if you're writing new arg()-using code for Drupal 8 right now, all you're doing is making more work for you or someone else to remove it soon after, *and* depriving us of an opportunity to see an arg() use case that we need to make sure is supported by whatever the new mechanism is (or decide that we want to consciously remove it, which is also legit).
2) To allow *gasp* some level of backward compatibility, by allowing one API to stick around for a version or so as a limited shell around some other new-fangled approach. Naturally this only sometimes works, but it is a way for us to, in some cases, help ease the transition by keeping around at least a few D7 utilities until D9, a few D8 methods until D10, etc. That makes module porting a bit easier. (Naturally this only works for cases that have for-reals APIs, not just naked data objects.)
---- For node/1354 (docs standards) ----
Use this tag to indicate that a function, method, or class has been deprecated and should not be used, but has not yet been removed.
A version SHOULD be specified, and should indicate the stable version in which this function was first deprecated (or, if added in a dev version, the next expected stable tag).
A prose description SHOULD be provided for additional context. At minimum, it should indicate what new mechanism to use to achieve the previous functionality or note that the functionality is slated for outright removal. An explanation of why the function was deprecated MAY be included. If known, the description MAY specify the version in which the function is expected to be removed outright.
A @see directive to a direct replacement MAY be included as well.
--- Proposal for api.drupal.org ----
On api.drupal.org, we can use this to make a prominent section looking something like this (using a class "deprecated" on the div containing all of this so it can be styled with red background like on the php.net example cited above? http://php.net/manual/en/function.split.php)
Deprecated as of Drupal 7.3, will be removed in Drupal 8.0. Use other_function() if you need to do this action, and use another_function() if you need to do this other action.
---- End of proposal
1. Adopt standards.
2. Add standards to node/1354.
3. Patch API module.
4. Start using the tag in documentation.
User interface changes
api.drupal.org will display tagged functions with some prominent markup.
Original report by tim.plunkett
We're introducing some methods that are only for backwards compatibility, and they shouldn't be used by new code.
Since we're not using it elsewhere, and I wasn't sure how api.d.o would deal with it, let's discuss that here.