[phobos] Deprecation of std.date

[Jonathan M Davis]

On Saturday 15 January 2011 22:03:28 Walter Bright wrote:
> Jonathan M Davis wrote:
> > On Saturday 15 January 2011 21:50:53 Walter Bright wrote:
> >> Then leave the pragmas off.
> > 
> > ??? You mean not put the pgramas in std.date and std.dateparse? Doesn't
> > that essentially mean that they're going to get deprecated with no
> > warning when they do get deprecated? Or are you thinking that updating
> > the documentation to say that they're scheduled for deprecation is
> > enough warning? If so, I'm fine with that, but I expect that that will
> > primarily mean that new code will use std.datetime rather than the old
> > code being fixed before std.date is actually deprecated, since I
> > wouldn't really expect anyone to be reading the documentation unless
> > they weren't already using the functions and familiar with them.
> > 
> > Regardless, what you're proposing then is that I mark std.date and
> > std.dateparse as scheduled for deprecation now but that I don't actually
> > use the pragma. Then, in a release or two or whenever we decide to
> > deprecate them, we mark them as deprecated. So, anyone who reads the
> > documentation will be aware of the impending deprecation, but anyone
> > already using the functionality without looking at the deprecation won't
> > know.
> 
> Then how about fixing the functions in std.file so they don't call the
> deprecated functions?

It's not just the functions. It's the type. Several functions in std.file take a 
std.date.d_time. I've written replacements which take a std.datetime.SysTime, 
but unless we want to immediately break code, we need to keep the old versions 
there. Sure, the implementations of the functions that take a d_time could be 
changed to convert the d_time to a SysTime and call the new versions, which 
would make it so that none of the std.date functions were being called, but they 
would still be using std.date.d_time.

Also, even if I were take the approach of altering the functions that use a 
d_time so that they don't call anything in std.date, and I duplicated the d_time 
alias in std.file, you'd then need a pragma in std.file to tell programmers to 
stop using those functions - and I'm not aware of a way to stick such a pragma 
on a function so that it's shown if those functions are called (you can with 
template functions, but these functions aren't templated) - so anyone using 
std.file - even when correctly using the new SysTime functions - would get see 
the pragma.

It seems like what we really need is another level of deprecated which marks 
symbols as scheduled to be deprecated instead of actually deprecating them and 
so does not require -d. Using pragma as we are isn't precise enough to avoid 
unnecessary messages. Regardless of whether we had such a version of deprecated, 
however, the issue of telling programmers what to use instead would remain, 
since deprecated has no way of telling you what to use instead, if anything.

So, with what we currently have, I see 3 options:

1. Just deprecate the stuff. You won't get the unnecessary the pragma messages 
from using std.file, and the build output won't be flooded with them either. It 
will, however, break builds.

2. Use the pragma messages and let them show up more than they technically need 
to and let them flood the build output. No builds will be broken, however.

3. Don't use the pragma messages. Just update the documentation. Then, there's 
_some_ warning at least, when we finally go and deprecate the symbols in 
question, but it will still come out of nowhere for some people.

Regardless, there will be one function - the version std.file.lastModified which 
just takes the file name - which will break the build of anyone using it, because 
the only thing changing in its signature is its return type (SysTime instead of 
d_time), so there's no way to overload it. Fortunately, however, I think that 
it's the only function in that boat.

- Jonathan M Davis