Deprecated argument names

[Jonathan M Davis]

On Tuesday, March 08, 2011 10:11:12 bearophile wrote:
> spir:
> >I read 2-3 times Walter thinks warnings are bad. Things are either
> >correct, or not.<
> 
> D compiler has the "-d" switch that allows deprecated features.
> 
> The old name becomes an alias of the true argument name when the "-d" is
> used... but maybe a less blunt  switch is better.
> 
> auto somefunction(@deprecatedName(x) int y) { ...

The workflow with regards to deprecating something in Phobos is to initially mark 
it as "scheduled for deprecation" in the documentation. If a pragma can be 
targeted to the item in question, then a pragma is added as well to print out 
when that item is used in order to warn developers that the item in question is 
scheduled for deprecation (generally, that only works when deprecating an entire 
module or when deprecating a template function - otherwise you usually get the 
pragma whether you used the soon-to-be deprecated item or not). It has been 
suggested that another level of deprecated be added for this (perhaps by giving 
deprecated an argument - e.g. deprecated(soft)), but that hasn't happened.

Regardless, after the item in question has been scheduled for deprecation for 
some period of time, it will be marked as deprecated. At that point, code which 
uses it will not compile unless you compile with -d. However, you _can_ still 
use it. After another period of time has passed, then the item will be removed 
entirely.

Essentially, we first warn programmers that the item in question is going to go 
away, but it doesn't affect their builds yet. Then we deprecate it, so if they 
haven't yet heeded the warnings that we gave them (albeit not warnings in the 
compiler sense of the term), then they'll have adjust their build to use -d. 
Finally, the item will be removed entirely, and if they haven't heeded the 
warnings by then, developers will just have to use an older version of Phobos or 
copy the item in question to their own code.

I don't believe that the exact periods of time that something will be marked as 
scheduled for deprecation and how long it will it will be deprecated have been 
decided yet (it may depend on what's being deprecated), but the basic workflow 
has already been decided on and has been put into motion in a number of cases 
(e.g. std.date is currently scheduled for deprecation now that we have 
std.datetime).

So, if we introduced deprecated parameter names as Bearophile is suggesting, 
then they would presumably fit into the normal deprecation framework, acting just 
like deprecated does.

- Jonathan M Davis