On Thu, 2011-02-10 at 02:14 -0800, Jonathan M Davis wrote: > On Thursday 10 February 2011 01:49:24 Lars Tandle Kyllingstad wrote: > > On Wed, 2011-02-09 at 21:54 -0800, Jonathan M Davis wrote: > > > [...] > > > So, what are everyone else's thoughts on this? Andrei and Walter favored > > > std.datetime being one giant module, and I don't exactly disagree, but I > > > do think that splitting _some_ of its functionality out would make it > > > more digestible, and I know that there are at least a few folks who > > > think that std.datetime is just plain too large. > > > > I don't think std.datetime should be split. Keeping it in one file is > > consistent with the way the other Phobos modules are organised. Rather, > > the Phobos documentation as a whole (and possibly DDOC itself) should be > > improved. > > > > [...]
> Splitting along the major concepts - time points, time intervals, and > durations > - makes a lot of sense to me. The time point code doesn't need to care about > the > internals of the durations that it uses, and the time interval code doesn't > need > to care about the internals of the durations or the time points that it uses, > but some of the D types in each of the three categories need to know about > the > other D types in the same category. So doing something like splitting SysTime > from Date, TimeOfDay, and DateTime wouldn't work very well. Also, > conceptually, > I don't think that that it makes sense to separate them precisely because > they're all time points and thus very similar. Not to mention, while Date, > TimeOfDay, and DateTime are designed with calendar-based uses in mind, > SysTime > has all of the same functions so that you can use _it_ for a calendar > solution > just fine. It's just less efficient for that due to its internal > representation, > and you do have a time zone with it, which may or may not be what you want > for > calendar-based stuff. But from an API perspective, DateTime and SysTime are > very > similar. It's mostly a difference in representation and therefore efficiency. > Regardless, the various time types are all similar enough that splitting them > up > doesn't really make sense IMO. > > Time intervals on the other hand just _use_ time points and durations, so > they > _can_ be put in a separate module quite cleanly. It's kind of like the > difference > between std.range and std.algorithm. For the most part, std.range deals with > defining range stuff whereas std.algorithm uses the range stuff. They're > related > but separate. Ok. I should probably get more familiar with std.datetime before continuing the debate, lest I make a fool of myself. ;) > As for improving the documentation, I've been working on that, but you can't > separate it out without separating the code into separate modules. It makes a > lot of sense to me to have the time intervals separate. That reduces how much > documentation is on the one page for std.datetime, and it makes it _much_ > easier > to sort out and find the interval and range types and functions. But without > dividing the module, you can't divide the documentation - not with how ddoc > currently works. > [...] I don't necessarily think that the documentation for std.datetime (or any other large module) needs to be split over several pages. My main gripes with the current documentation are: 1. The table of contents at the top sucks. It's just one big lump of text, and it's impossible to see whether something is a free function, a member function, a type, an alias, an enum, etc. 2. The documentation only uses indentation to indicate the relationship between the different elements. Look at the documentation for DateTime.fromISOString(), for instance. You have to do a fair bit of scrolling to figure out whether it is a free function or a member function, and of which type it is a member. 3. It is not possible to impose any structure on the documentation, beyond the one given by the code. In the recent discussion about the std.algorithm docs, Adam Ruppe suggested a Tag: section, so you could tag an std.algorithm function with 'searching', 'set operation', 'sorting', etc. That would probably do wonders for std.datetime as well. Fixing these issues would go a LONG way in improving the documentation. (And it seems Andrei and Adam have both been working on this lately.) -Lars _______________________________________________ phobos mailing list [email protected] http://lists.puremagic.com/mailman/listinfo/phobos
