[boost] GDTL Review Comments

From: Ron Garcia (garcia_at_[hidden])
Date: 2002-04-24 15:19:53

Currently, vote a qualified YES on the acceptance of this library
into Boost. Overall I like this library, especially having seen the
presentation in Tampa, but I would like to see my comments addressed
prior to offering an unqualifed acceptance vote.

This review is based solely on a review of the documentation. 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.

DOCUMENTATION
The documentation is as much a part of a library as the code itself,
and the interfaces defined by the library are more important than the
underlying implementation (assuming that the interface is
implementable).  I get the impression that Jeff is waiting on GDTL's
acceptance into BOOST before polishing the documentation.  While I
understand this sentiment, and I by no means feel that the docs should
be pristine by review time,  I still feel that they should adequately
portray the purpose of the library, the interfaces it defines, and its
basic use.

GDTL's introductory documentation (Intro, Motivation)  
seems more like a placeholder than real content.  I would like to see
this fleshed out more.  Some mention is made to the limitations of
other libraries, but I get no tangible sense of the scope of this
library, which based on other review discussions does seem to have
some limitations.  

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.  

GENERICITY
Looking through the interfaces, I get the sense that the "genericity"
(in the sense of generic programming) aspect of this library is a bit
overstated.  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;  that's
fine, but in that case, I'd drop the "generic" reference and
simply call it the Date Time library.  On the other hand, it may very
well be generic.  If that is the case, then I think that some of the
most important aspects of such a library, the Concept descriptions,
are missing.

In any case, the mentioned means for extending the library do not seem
to be well documented, making it difficult to evaluate them.

RATIONALE

This has been mentioned by others, but I think that more design
decisions should be documented since not all appear to be intuitive
(i.e., conversions between time systems).  A discussion of the
library's scope, and rationale for that scope seems necessary.

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.

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

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.

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.

- 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?