Proposal on improvement to deprecated

[Jonathan M Davis]

There has been a fair bit of discussion about improving deprecated in this 
pull request: https://github.com/D-Programming-Language/dmd/pull/345

It's quite clear that we want to add the ability to give a message with 
deprecated. It's also pretty clear, that deprecated needs to be improved in 
other ways, since as soon as you use -d, the deprecation errors go away, and 
you never see them again and end up with no explanation as to how to fix your 
code when a deprecated symbol is actually removed. There has also been some 
discussion on how to work in "scheduled for deprecation." The current method 
of using pragmas only works with templates, and various folks have found the 
messages annoying, since the only way to get rid of them is to cease using the 
symbol which has been scheduled for deprecation and the fact that they're 
pragmas means that they can't really tell you where in your code the symbol 
which has been scheduled for deprecation has been used.

I think that we really need to get this sorted out before the next release, so 
I'd like to make a proposal based on that discussion.

1. deprecated will be changed so that it will be able to have a message with 
it. e.g.

deprecated("message") void func() {}

If you do not include a message, then the message that you get will be 
essentially what you get right now.

2. deprecated will be changed so that it has a second parameter indicating 
whether the deprecation is soft or hard. e.g.

deprecated("message", soft) void func1() {}
deprecated("message", hard) void func2() {}

If no soft or hard is given, then it defaults to soft (which is the closest to 
the current behavior).

3. Regardless of whether the deprecation is soft or hard, code which uses a 
deprecated symbol will not compile unless it uses -d or -di (which would be a 
new flag). This is the same as the current behavior.

4. Soft deprecation means that if you compile with -d or -di, then the code 
will compile even if you use the deprecated symbol. If you use -d, then no 
deprecation messages are printed. If you use -di, then deprecation messages 
are printed, but they have no effect on compilation. They are neither errors 
nor warnings, just messages.

5. Hard deprecation means that the code will not compile at all if the 
deprecated symbol is used. -d and -di will have no effect on hard deprecation. 
The idea is that instead of outright removing the symbol (which then gives no 
indication as to what should be used instead now that the symbol is gone), you 
get a message telling you what to use instead. But the code still won't 
compile, so you'll still be forced change your code.


The way that Phobos will then deal with depreaction is as follows:

1. A symbol which is going to be removed will be scheduled for deprecation. 
This means that its documentation will mark it as scheduled for deprecation, 
and it will be noted in the changelog that it has been scheduled for 
deprecation. But there will be _no_ compiler messages of any kind about the 
change. So, it's up to the programmer to pay attention and notice if anything 
has been scheduled for deprecation.

2. After a period of time, the symbol will be soft deprecated. So, if neither 
-d nor -di is used, then any code using the symbol will fail to compile. If 
the programmer does not want to immediately change their code but still wants 
it to compile, they can then choose to either use -d and get no deprecation 
messages or use -di and get deprecation messages.

3. After a period of time, the symbol will be hard deprecated. So, at that 
point, the programmer _must_ change their code if they want it to continue to 
compile. But unlike right now, they get a decent error message about how to fix 
their code.

4. After a period of time, the symbol is completely removed.


I think that this solution is simple enough to be reasonable. It doesn't stray 
wildly from the current behavior, and it gives programmers the option as to 
whether they really want to see deprecation messages or not before they're 
forced to change their code.

Does this scheme seem acceptable? Are there any reasons why would _shouldn't_ 
go forward with this proposal?

- Jonathan M Davis