On Mon, 09 May 2011 09:49:04 +0100, Russel Winder wrote:

> On Sun, 2011-05-08 at 23:52 -0700, Jonathan M Davis wrote: [ . . . ]
>> I could look at writing an article on moving from std.date to std.datetime, I suppose. We already have an article contest going, and it would make sense to put such an article on the site.
> 
> I suspect many people would be happy if you did do this, but I was thinking more copy and paste the material into a wiki page and then let everyone who has knowledge/interest help refine it.
> 
>> I don't really have anywhere online that I can post anything myself though, let alone links to whatever newsgroup posts might be useful for understanding std.datetime.
> 
> If there isn't a D/Phobos wiki then now is the time for Those in Authority, to make one so that this sort of material can go up there and be "crowd edited".

There certainly is:  http://prowiki.org/wiki4d/wiki.cgi

-Lars

Russel Winder wrote:
> My second reaction was "Jonathan should not have had to write such a long email in reply, he should have been able to say 'Please go read <URL>' for an explanation."

Better yet, that url could be right there in the deprecated message.

"std.date and std.dateparse are deprecated. Use std.datetime instead. More: <wiki link to migration guide>"


When something is renamed, just listing the new name is enough since
that's everything you need to know. But a whole new module needs
a brain shift and a link can do that better than a one line message.

While it looks like everything I'd need to know is in the std. datetime docs, they are just rather long... I looked at that and figured reading from front to back would take too long, especially considering the basic tasks I was asking of it.

So then I did a search for the std.date names, and only got the deprecated functions! So it was a scary way to get started.

"Jonathan M Davis" <jmdavisProg@gmx.com> wrote in message news:mailman.80.1304923988.14074.digitalmars-d-learn@puremagic.com...
>
> I could look at writing an article on moving from std.date to
> std.datetime, I
> suppose. We already have an article contest going, and it would make sense
> to
> put such an article on the site.
>
> I don't really have anywhere online that I can post anything myself
> though,
> let alone links to whatever newsgroup posts might be useful for
> understanding
> std.datetime.
>

You could put it on the D Wiki: http://prowiki.org/wiki4d/wiki.cgi

Or if you just want to post some non-wiki pages, I'd be happy to post them on my server for you: www.semitwist.com

> I would have hoped that the documentation in std.datetime would have been
> sufficient, but either it isn't and/or it's just too overwhelming for some
> folks, given some of the things that have been posted. There haven't been
> a
> lot of questions about it though since it got into Phobos, so either a
> fair
> number of people are understanding it well enough, or they aren't using
> it.
>

All the info that's there is good, but I think the problems, at least as I see it are:

- Like others said, it could use a migration guide. It's a fantastic module, but I think one of the biggest use-cases for it right now is migration from std.date and the old deprected funcs in std.file. And since is it so very different, a simple migration guide would be very helpful. Without that, I had a little bit of touble migrating some stuff, too (although I'm sure part of that was just me being lazy and trying to minimize effort to just get it done).

- Some of the important "overview" concepts and typical use-cases are spread out a bit much. Of course, they should certainly stay where they are for reference purposes. But it would be a big help if, for instance, what you told Adam about Durations, subtracting/comparing SysTimes, dur!"hours"(8), and olderByAtLeast8Hours were summed up in the overview. Another good thing to put up there would be this fantastic idiom, which I probably wouldn't have even noticed if someone hadn't submitted a bug report to me for Goldie that just happened to use it:

Adapted from: http://www.dsource.org/projects/goldie/ticket/18

  StopWatch sw;
  sw.start();
  scope(exit)
      writeln(sw.peek.msecs);

And maybe a quick little example of "benchmark" added to the overview. I didn't even realize that existed until I was looking through the whole page.

And of course, like you said, something like what Andrei added to the top of the std.algorithm docs would be great, too.

> Part of the problem with better explaining std.datetime though is that
> it's
> pretty much all in the documentation, so it's not generally clear what I
> should be explaining further without people asking specific questions.
>

Yea, that's definitely understandable.