RE: [boost] Re: reminder about Date/Time formal review

From: Jeff Garland (jeff_at_[hidden])
Date: 2002-04-23 15:26:40

>Issues I find with the library that should be addressed at some point:
> 
> 1.  Documentation needs to be made "static".  There is too much of the
> documentation that resides on the Wiki, and I'm not sure any of it should be
> there.  Such documentation is unusable in an "offline" manner, which is how
> most (all?) documentation should be used.

Agreed.
 
> 2.  The generic "infrastructure" code found in the gdtl namespace needs
> documentation.  This is the core of the library, and probably the most
> important piece.

Yes, this clearly needs improvement.
 
> 3.  The Gregorian calendar system needs more documentation.  The Gregorian
> calendar isn't a simple system, and there are a lot of things not documented
> about GDTL's implementation of this system.  For example, historical dates
> in a Gregorian system are dependent not only on the date, but also on the
> location.  To clarify, different geographical locations adopted the
> Gregorian system at different times, and this effects historical dates.  The
> two most common "change over dates" used in gregorian date algorithms are
> Oct. 4, 1582 and Sept. 14, 1752.  I think it's important to document which
> "change over date" is used, since date projections before this date are not
> accurate.

Agreed.
 
> (Trivia related to the above:  Did you know that Sept. 2, 1752 was followed
> by Sept. 14, 1752?  Or that George Washington's birthday, which we give
> today as Feb. 22, 1732 was recorded on that day as Feb. 11, 1731?  Gotta
> love this date stuff, no?)

It makes your head spin after awhile :-)
 
> 4.  The string conversion and parsing routines should simply be removed.
> Instead, we should have iostream capabilities for the various date systems
> which obey the locale.  This is, after all, a C++ library and not a Java
> library.

I think this will take some discussion as I think some folks would really 
like to have string conversion routines (I for one).  And while I agree
we need locale compliant streaming, in my experience this isn't usually
enough.  That each different parts of the GUI etc want to extract different
dates and times using different parts and pieces.  So I would suggest
we add the streaming and leave the string conversions.
 
> 5.  I still disagree about the presence of a "universal representation" and
> the ability to convert to/from this representation and a particular time
> system.  I believe the precision issues to be no more important then the
> loss of precision that can occur when converting to/from the various numeric
> representations, and that so long as the precision is documented for a given
> system it's possible for the user to deal with any loss.  That's something
> that's their responsibility.  As for the vagaries of the various political
> factors of many time systems... documentation will again save the day in
> most cases.  Historical artifacts can be addressed in the time system, while
> future variations, such as leap seconds, are simply documented as being
> possibly innacurate.  The programmer takes full responsibility when creating
> such future dates in the first place, so innacurate conversions to a
> universal system causes no more grief then what was already present in the
> representation any way.

See my other mail.  I think we are actually in agreement here.
 
> I do not agree, however, that this "universal representation" should include
> mathematical capabilities, as others have argued.  Adding such capabilities
> to the universal representation causes choices to be made about the
> representation and its resolution and precision that should be made instead
> in the specific time systems.

We definitely agree here.
 
> Politics and local conventions can make date/time handling routines
> difficult.  But they should not prevent the conversion of dates in one
> system into dates in another system, and with an extendable framework where
> the time systems available is open ended, the only possible solution is to
> provide conversions to/from a "universal representation".  Failing to
> include this seems to guarantee nothing but trouble in the future.

Again, see the other mail.
 
> 6.  <personal opinion>I don't care for the doxygen documentation.  I believe
> in the concept of keeping the documentation in the code, but I think there
> are issues with the Doxygen generated documentation that will make it
> problematic for Boost (such as the size of generated documentation), and as
> someone else pointed out most of the technical documentation currently can
> only be found in the Doxygen generated documentation.  I think this will
> cause nothing but trouble for Boost users.</personal opinion>

Fair enough.  Regardless of the extractor I intend to keep the core
of the code documentation inline so that it can be read by browsers of 
the code.  I have been doing this since way before doxygen was ever 
invented. My thought is to include an 'extender guide' that provides 
examples of how to use the library components to build new date-time 
systems. Of course we still need direct documentation of the components.
Anyway, I'm committed to making the documentation work better.

Jeff