[phobos] Split std.datetime in two?

[Lars Tandle Kyllingstad]

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