[phobos] Split std.datetime in two?

[Jonathan M Davis]

On Thursday 10 February 2011 02:46:36 Lars Tandle Kyllingstad wrote:
> 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.)

Yes. Fixing stuff like the links at the top would definitely help. The docs are 
not currently setup to deal with classes and structs very well - the biggest 
offense being that the links act like _all_ functions are free-functions and 
can't handle the fact that there are multiple functions with the same name in 
the file - even when they're in separate structs or classes. The links really 
should group struct and class functions as part of their associated struct or 
class. But my issue here isn't so much that as the fact that time points and 
time intervals are distinct concepts that I'd like to be able partition.

In particular, what I find frustrating is that I would like to be able to section 
off the range-related functions and group them in an obvious and easy-to-find way. 
While they _are_ grouped in the file, you do have to do a bit of searching for 
them unless you already know what they're named. For the moment, the range-
generating functions are all marked with "Generates a range-generating function 
for intervals" so that they're easily searchable (and the fwdRange and bwdRange 
functions on the interval types mention that), but that's kind of dumb IMO. It's 
just the best that I could think of thus far, short of splitting them out into a 
separate module. If the interval stuff and range stuff were in their own module, 
then it would all be clearly grouped. In dealing with time intervals and their 
associated ranges, it feels to me like they really should be separated from the 
rest of std.datetime - they use it, but they're definitely different from most of 
the rest of it (most of which focuses on time points). Time points and time 
intervals (and their associated ranges) are distinct concepts that I'd like to 
separate.

So, I'd like to split the interval and range-based stuff into its own module. I 
think that it would just plain be cleaner that way. But obviously, I'm not going 
to just move them into their own module without some sort of agreement on the 
matter from other Phobos developers.

- Jonathan M Davis