On Friday, March 29, 2013 06:42:41 Andrej Mitrovic wrote: > Why was this inconsistency introduced?
The main problem with TickDuration is that it was written by SHOO rather than by me and was adjusted to fit into core.time rather than being part of the original design. I've made some improvements over time, but I think that the overall situation with TickDuration is less than ideal. And honestly, if I were to go back, I'd probably get rid of it entirely. I don't see much benefit in keeping the time in system ticks (like TickDuration does) rather than hnsecs (like Duration does), particularly when the system ticks are often less precise than hnsecs anyway (and testing TickDuration is a royal pain). If I could, I'd probably have a type specifically for dealing with the monotonic clock (like TickDuration is used for now), but for stuff like StopWatch, I'd just use Duration. But I don't know how much can be done to improve the TickDuration situation at this point without breaking code. I totally agree that it could use some improvements though. > I've seen this type of property documentation copied everywhere in > date/time-related structures and classes, it's not clear from the > documentation that these are setters, they should be documented as > such. I'm sure that improvements can be made, but no one has pointed out much other than the fact that the docs are unwieldy with them all being on one page, so I haven't had specific suggestions as to sections that should be rewritten or anything like that. > Another example, I once had to convert a long type which represented > Unix time into DateTime. Here's the code to do it: > > return cast(DateTime)SysTime(unixTimeToStdTime(cast(int)d.when.time)); > > It's unbelievable how ugly this is, and it took me way over half an > hour searching the docs and trying various stuff out to figure this > out. Well, on some level, dealing with unix time _should_ be ugly, because you shouldn't be doing it normally (though obviously you're forced to sometimes), but it is the way it is mainly because making dealing with unix time super simple and clean was never really a goal. But the situation could certainly be improved. I wouldn't provide a way to convert time_t to a DateTime, since DateTime has nothing to do with the system time, and you need a way to control what time zone you're converting to, but it's certainly not out of the question to provide a function for converting directly from a time_t to a system. So, you could get something like return to!DateTime(unixTimeToSysTime(d.when.time)); which is at least somewhat better. > Anyway, maybe time and datetime are power-houses in Druntime and > Phobos, but they trade their features for simplicity. I don't think that it's really all that complicate ultimately - or at least most of the parts are quite simple and straightforward - but there are a lot of parts to it, and the way the documentation is laid out makes it difficult to figure it out. And that's ultimately the biggest problem with it IMHO. > Perhaps the real problem is the documentation, or the actual layout of > the API itself. The API seems to contain a ton of functionality, and > maybe the more specialized functions should be moved into separate > modules (and make datetime be part of its own package). > > The docs for std.datetime for example are huge. I think that the main problem is that it's all sitting in one page with a bunch of useless links at the top. It's a great example of a place that ddoc does _not_ shine. The ddox version is much better: http://vibed.org/temp/d-programming-language.org/phobos/std/datetime.html What I'd really like to do though is to split std.datetime into a package with several modules in it where importing std.datetime imports all of them, but that requires implementing some variant of DIP 15 or 16. With something like that implemented though, I'd jump at the chance to split it up. It really should have been split up in the first place, but there was resistance to that when I originally presented it as split (probably to a great extent because my initial split for it was very bad, and the design evolved quite a bit after that; I have a much better idea of how to split it cleanly now), so it unfortunately ended up being merged in as one module. If I were to go back in time, I'd probably split it up and then have it reviewed in pieces rather than all together so that each piece got reviewed better. On the whole, I think that what's there is quite solid (assuming that you can figure out what's there in spite of the documentation issues), but there are a few things that could have been done better (e.g. range support, which I'd still like to try and improve at least somewhat one of these days), and ultimately, I think that it was too much to review at once. But it was the first module to go through the review process, so we didn't have any experience with it at the time. It _did_ improve quite a bit through the review process though, and I do think that it's a good example of how the review process can help to improve code before it goes into Phobos, even if the end result isn't perfect. - Jonathan M Davis
