[boost] Boost I/O Library Review (Ed B.)

From: Ed Brey (brey_at_[hidden])
Date: 2003-03-11 11:22:24

First, a reminder that today is the last day for sumbitting a review for the update to the I/O library.

This is my review of the I/O library, which is separate from my role as review manager.

I vote that the library update be accepted into boost.  I examined the documentation and code.  The new manipulaters will certainly be handy.  The streambuf and array stream components will be used less often, but have their place.  Following are suggestions for improvement:

Code/design suggestions:

array_stream.hpp:

- In the basic_array_stream classes, the char_type and traits_type definitions seem to duplicate those provided by the basic_wrapping_istream base class.

- The functions in the three basic_array_stream classes could be factored into a single base class to avoid copied code.

- Why stop at stream buffers?  Why not define array_stream templates?

Specific documentation suggestions:

streambuf_wrapping:

- Provide a short hello world example at the beginning of the documentation showing how the library is useful.  Since I haven't had reason to explicitly work with stream buffers for many months, it was very confusing coming on cold to this library.  For the example, the reader should be able to deduce how the library makes his life easier versus not using it.  Clearly, your array stream class would serve as a good example, but it needs to be digested down to a one minute tutorial version for the streambuf_wrapping documentation.

array_stream:

- Here again, a motivating example would be a good start to the documentation, especially if there is an array_stream class ready to use out-of-the-box.  An example could be formatting I/O for output to a fixed-character device such as an LCD.

iomanip:

- skipl:
    Rationale: a dual to boost::io::newl -> Rationale: a counterpart to newl

General documentation comments:

- Remove references to namespace boost:io, except once in the documentation header.