Re:[boost] Review of Daryle Walker's "More IO" library begins today, August 21, 2004.

From: Robert Ramey (ramey_at_[hidden])
Date: 2004-08-28 11:24:42

Some general comments:

First of all, let me say that I am a fan of Daryle's state-saver library. I
have found it to be very useful.

The documentation sections use the word "Rationale" where I think they
should be using the word "Motivation".  I see Motivation as the explanation
why the library is useful in the first place. I see Rationale (plural) as a
list of justifications for design choices. 

This is one library submission.  However, it is really several almost
disjoint or orthogonal parts.

a) new io manipulators
b) facilities for wrapping streambuf
c) a couple of new kinds of streams

These should be considered separately.

Manipulators
============

Here is the first part of the documentation:

Rationale
There are several I/O manipulators that can be useful to a general audience
besides the ones given in the Standard library. This header supplies some of
them.

Form-based Manipulator Header
The header boost/io/iomanip_form.hpp contains a class template for multiple
manipulations.

Form-based Manipulator
Objects from a boost::io::basic_ios_form template class represent
manipulators that determine what and how to affect the standard I/O
attributes via repeated calls to its member functions, then can change how a
single insertion or extraction call happens for an streamable object. Said
manipulators can be temporarily created (in-line, without a name) or created
conventionally in advance for multiple insertions/extractions.

On getting this far, I have no idea what these manipulators are supposed to
do, what problem they are meant solve. Or when I would use them.

I believe that this part of the manual should contain:

Motivating example. Problem solved by form-based manipulators. A sort of
Tutorial section.

The line-skipping an repeated-char seem a little more understandable- if
only because of their names.  Repeated_char_narrow - I would think that the
"narrowing" of characters might be something more commonly handled by
codecvt facet.

I would prefer that the html files be broken in smaller sections.

Array Based Streams
===================
Its not clear to me how this is functionally different from strstream

Stream buffer implementations
=============================
Stream buffer with variable size buffer
Stream buffer which discards output
Stream buffer which returns a constant value

These I find understandable though I'm not sure what I would use them for -
but that's not a criticism. 

The streams based on these buffers are small facilitators when don't have
much code.  OK. 

Stream buffer wrapper
=====================
I gather this is to factor out common code for making new stream buffers.
Actually, since I haven't made a streambuffer myself I don't know all of
what's involved.  I'll take your word that its useful.

Overlap
=======
I've also taken a forward look at Jon Turkanis coming offering.  I see
significant overlap. Jonathon's library is more ambitious in that it in that
it addresses composition of stream buffer adaptors.  I suspect it would
include the above as subset.

So - I'm going to recommend that the review manager for this library reserve
judgment pending the upcoming review of the Jonathon's library.  Ideally the
two managers involved would coordinate their reviews so that functionality
doesn't get duplicated.
  
>What is your evaluation of the design?

The design is a natural extension of standard C++ library and in principle I
see no problems here.

>What is your evaluation of the implementation?

I didn't run the code, but it seems to follow standard convention - a good
thing for a library like this.

>What is your evaluation of the documentation?

The documentation is pretty clear - as far as it goes.  It needs more
background, motivation, and tutorial like examples.

>What is your evaluation of the potential usefulness of the library?
>Did you try to use the library?  With what compiler?  Did you have any
>problems?

I didn't use the library.

>How much effort did you put into your evaluation? A glance? A quick
>reading? In-depth study?

Just about 1-2 hours reviewing the documentation.

>Are you knowledgeable about the problem domain?

Fairly knowledgable

>And finally, every review should answer this question:
>Do you think the library should be accepted as a Boost library?  Be sure to
>say this explicitly so that your other comments don't obscure your overall
>opinion.

a) manipulators are probably OK - but they need more documentation to
explain what they are to be used for.  With these changes, I would expect to
see them added to the io library.

b) streambuffers.  I believe that it premature to include these in Boost. I
think this will be more clear after the upcoming review of Jon Turkanis
library which has overlapping functionality.

Robert Ramey