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

From: Jan Langer (jan_at_[hidden])
Date: 2002-04-22 18:22:02

Jeff Garland wrote:
> > > - it was not easy to find out how some classes or many member functions
> > behave because the documentation says nothing about it.
> >   e.g. it says for a whole class like day_functor only one short
> > sentence, which is imho too few.
> 
> Agreed that should be improved.  Any other specific cases?

yes, you should go through the whole documentation and write a few more
sentences about each class and non-trival member functions. i just used
day_functor as an example to ilustrate the problem.
a few more examples: date_itr, dst_calculator, ...

perhaps it would be useful to have a distinction between the classes
which should be used be the user and the internal ones. often i want to
use a class or a type and don't want to look through the entire hierachy
to find out how it works.
eg: i want to use an iterator to iterate over days. i see day_iterator,
date_iterator in gregorian with no documention. then i must look at
gdtl::date_itr and gdtl::date_itr_base with few documentation which are
quite complicated, because they are generic components. finally i search
in the examples and find print_month which tells enough for my simple
test program but still leaves it unclear why i can compare an
day_iterator with a date.

> > - then i wanted to test the generic part and tried to write my own
> > date-class which has only a resolution of one year. but i found no point
> > in the documention describing how to start. what i would like to see is
> > a description how the generic components of gdtl should and can be used.
> 
> This is a criticism that has been raised by another reviewer offline and I
> agree should be addressed.  However, I have been somewhat reluctant to write
> spend time writing this documentation until there was some further review
> of the library.  There is no point spending my time on this if the library
> is rejected...

ok, but normally the library _and_ the documentation should be complete
before the review :-)

> However, in general, the goal with GDTL has been to keep individual components
> of the date-time library as separate as possible.  For example, the parts that
> retrieve from a clock are separate from the parts that represent a date/time.
> In this way, we can add a new clock source(say a network clock) that provides
> a date/time component without disturbing the basic temporal types (as long as
> a reasonable mapping can be made, of course).  It also means that the date or
> time system can be used to represent historical times even if the clock cannot
> (of course it doesn't make sense for a clock to do this).
> 
> So for example the dimensions of extension include:
> * Add clocks to existing date-time systems
> * Add new parsers/formatters to a date or time system
> * Add new date/time systems

i think the lib should concentrate more on the description of the
concepts it used and the generic components it provides in namespace
gdtl. the existing grgorian and ptime sublibs are sufficient for most
usages. but the possible "implementors" of new date/time systems by
means of gdtl must be supported more. mainly in terms of documentation.

 
> > - i wanted to output the names of the months in my native languages, but
> > it seems to be impossible. is there any support for
> > internationalisation?
> 
> Support for C++ locales and facets needs to be added.

gdtl's usage is quite limited by this fact. it should definitly be fixed
before gdtl is added to boost.
but this doesn't change my overall vote.

-- 
jan langer ... jan_at_[hidden]
"pi ist genau drei"