RE: [boost] GDTL Review Comments

From: Jeff Garland (jeff_at_[hidden])
Date: 2002-04-24 16:04:02

Ron Garcia wrote:
>In short, I really like the direction that this library is headed in, 
>but I would like to see more work done, especially on the documentation.

Obviously you are not alone here.

>GDTL's introductory documentation (Intro, Motivation)  
>seems more like a placeholder than real content.  I would like to see
>this fleshed out more. 

Yes, this can be expanded.

>Currently, the documentation html makes calls out of the tarball to
>the Wiki (I happened to be offline when reviewing the docs).  This
>documentation should be part of the library documentation.  

Yes, I apologize for this.  I tried to summarize what I thought were
some of the more relevant aspects of the Wiki discussion into the
'offline' docs.  It is obvious from the comments that way too 
much was cut.

>GENERICITY
> I find little in the way of Concept documentation or a
> sense of how the concrete objects supplied by the library fit 
> into a generic framework.  Perhaps the library is not really generic, 
> but instead is a collection of useful components; 

Again this was my mistake for not documenting the extension mechanisms.  
At the end of the day, I'm not sure where GDTL fits on the 'generictity' 
scale, but I'll leave that debate to others -- I've got work to do ;-)

>Specific notes on the GDTL docs:
>
>Introduction:
>- Say more.  Flesh out the introduction
>- Collection of libraries?  Isn't this a collection of components that
>interact as one library?  
>
>Motivation:  
>- The discussion of limitations is really vague...calculate what?
>convert to or between what? format what? And what other functionality?
>I don't really get a feel at all for what this library is capable of
>or what its limitations are or are not.

Agreed.

>Usage Examples:
>- What is "d1" in the first example?
>- What is "d2" in the first example?

Dates -- cut and paste error -- will fix.

>Domain Concepts:
>
>What documentation there is looks pretty good, but I will most
>definitely want to see the documentation collected in the tarball
>before acceptance of the library.

Yes.

>I would like to see concept definitions and see how these relate to
>date and time algorithms.  The library documentation fails to express
>the genericity of the library.  Concept documentation clarifies and
>emphasizes the genericity of the library.  Right now it just looks
>like a few loosely related components.

Agreed.  The essence of the 'concept model' is that 
date/time systems should provide time points, durations, 
and intervals.  These 3 types have some fundamental relationships 
that happen to be useful as well.  All systems also have one or
more 'labeling' forms for describing these concepts and have 
different rules for performing the various calculations.  A clock
device is a separate component that many systems will provide 
to measure the current date/time.  

Most libraries don't split things like clocks and dates, so it
becomes very difficult to adapt add new clocks (say a network
time source) to existing systems.  Or they tie the range of
represented times to the clock source, which given the range 
of most clock systems makes the representation inadequate for 
many applications.

>- It appears from the documentation that a date is merely a time with
>a maximum resolution of one day.  This does not seem clear from the
>documentation, (i.e. separate date_iterators and
>time_iterators)  Where is the commonality?

Yes, there has been some discussion of this already.  date_iterator is 
perhaps misnamed.  The real issue addressed with the date_iterator template
is the ability to bind in a functor that has complex rules such as
'add a month'.  I suspect after I figure out how to refactor this
using iterator adaptors this may just go away.  

Jeff