[phobos] Deprecation messages and templates

[Jonathan M Davis]

Since there's not currently a way to give a message with deprecated or to mark 
something as scheduled for deprecation (regardless of whether there's a 
message), the only way that I'm aware of to give a message when someone uses a 
symbol which has been deprecated or scheduled for deprecation (other than the 
error you get when using a deprecated symbol without -d) is to use a pragma. 
And the only way to restrict a pragma such that it's printed only when the 
symbol it's associated with is actually used is to have that symbol be 
templated and put the pragma in the template. That's how we've generally been 
handling deprecation messages. It does pose one problem, however, which hadn't 
occurred to me. If the function wasn't templated before and we make it 
templated (albeit with the constraint restricting its arguments to what they 
were before), you can no longer pass the function as a predicate to other 
functions such as filter or sort (at least, not without changing your code to 
explicitly instantiate them, and the whole point of the message prior to 
actually deprecating them was to avoid breaking code).

So, the question that this raises is: In cases where adding a deprecation 
message requires templatizing a currently untemplatized function where that 
function's signature is such that there's a decent chance that it was passed 
as a predicate to another function and therefore templatizing it would break 
such code, should we just avoid templatizing it and only put the deprecation 
message in the documentation? Or should we just templatize it, and while some 
code might break due to the change, any code which doesn't use the function as 
a predicate should be fine?

I'm torn. I'd very much like the deprecation message to print, and I _don't_ 
want it to print if the deprecated (or scheduled to be deprecated) symbol 
isn't actually used. If there's no message printed, the only way that anyone 
is going to realize that the function is being deprecated is if they read its 
documentation, which they probably aren't going to do, since they're already 
using the function, so the waiting period prior to actually deprecating the 
symbol is next-to-useless. On the other hand, if the function is templated and 
some code does break, then for those cases, it's pretty much just as if we had 
immediately deprecated the symbol rather than scheduling it for deprecation. 
So, I really don't know which to do. In cases where a function clearly 
wouldn't be used as a predicate, I'd definitely templatize it, but in cases 
where it probably would be (such as a function like std.ctype.isdigit), 
there's a high risk of breaking code.

If deprecated were improved to include a message and to allow for soft 
deprecation (i.e. scheduled for deprecation), then that solves the problem 
quite neatly. We wouldn't have to be hacky about it with pragmas anymore, but 
that would likely take some work to implement, and we may not have such an 
improvement anytime soon. So, we need to decide on what we're going to do as 
long as we just have pragmas.

Should we favor putting the deprecation message in the documentation only 
where it will likely have almost no effect and thus only delay the surprise of 
code breaking when the function is deprecated, or should we favor templatizing 
them and avoid the surprise for the cases where the templatization doesn't 
matter but immediately surprise those who used the function as a predicate? 
Both solutions suck IMHO, but I don't see any other options (other than just 
not deprecating some stuff, but that means that we're stuck with code that 
needs to be fixed until deprecated is improved, which would just increase the 
cost of deprecating stuff, since it will have been used that much longer and 
by that many more people and so more code will break when the change is made).

- Jonathan M Davis


P.S. This post seems a bit long, now that I've typed it. That seems to happen 
a lot. I should probably learn how to be more concise one of these days...