[phobos] Deprecation messages and templates

[Andrei Alexandrescu]

I think it would be best to lobby Walter for deprecated("message").

Andrei

On 5/26/11 9:52 PM, Jonathan M Davis wrote:
> 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...
> _______________________________________________
> phobos mailing list
> phobos at puremagic.com
> http://lists.puremagic.com/mailman/listinfo/phobos