RE: [boost] Re: About iostate.zip 5

From: Brey, Edward D (EdwardDBrey_at_[hidden])
Date: 2002-03-25 15:00:30

> From: Daryle Walker [mailto:darylew_at_[hidden]]

Thanks for the comments on the review comments.

> For example, we'll start a talk-show sub-library.
>  To stop 
> the sprawl of
> headers in the top boost header directory, components for 
> talk-shows will go
> in a "talk_show" namespace (within the "boost" namespace).  
> To make the new
> headers easy to find, the headers for stuff in the 
> "talk_show" namespace
> will go into the new "BOOST_ROOT/boost/talk_show" directory.

I like that you are applying a methodical approach here.  Before jumping
into it though, it would probably be useful to identify the advantages of
stopping the "sprawl".

I find your use of the term sub-library curious.  Wouldn't we want to limit
the collection of top-level directories to one per library, or else face a
sprawl of TLDs?

> Forward declarations, like <iosfwd>, make some applications of a class
> easier.  We could make the forward declaration header
> <boost/talk_show/fwd.hpp>, but I like <boost/talk_show_fwd.hpp> better
> because I don't like a lot of headers with the short name 
> "fwd.hpp".

Singling out foward headers won't help in the general case.  There would
still tend to be multiple files with the same name, such as "exception.hpp",
from the various libraries.  What problem arises with identically names
files?  How does the name length affect the issue?

> > - Contents of index.html should be merged into 
> iostate.html, since this is
> > such a small library.  Having the extra level in between 
> the main boost
> > library page and the actual documentation of the library slows down
> > browsing.  When the user clicks on iostate from the boost 
> library index
> > page, the first think that he should see is a brief 
> description and a
> > "Hello, world" example.
> 
> No.  See my future namespace, forwarding header, and 
> sub-library philosophy post.

What is your vision for the io library?  E.g. should lexical_cast be part of
it?  What other features do you see being added?  I can see creating an io
namespace if we have a general road-map on how to fill it.  Otherwise, I
would be in favor of keeping ios_state a top-level utility.

> > - The fact that the iostate.html header includes any other 
> headers should not
> > be part of the public interface.  Hence, it would be better 
> to show it in the
> > documented synopsis.  Part of the problem stems from the 
> fact is that document
> > lists a "header synopsis", which isn't exactly what the 
> reader needs to know.
> > The information that should be presented is simply a list 
> of classes are
> > guaranteed by be declared/defined when a header is included.
> 
> So what should I do here?

It depends on the answer to the above question.  If ios_state stands by
itself, I'd say eliminate index.html and put the link to the header down in
an implementation section of ios_state.html.

If the io namespace makes sense, index.html would remain as a general index
into all the io library components.

> > -What is your evaluation of the documentation?
> > It is too much "how it was done" and not enough user level 
> "how to use".
> 
> The rationale shows a function that may need the savers, and 
> the example
> shows how the savers can fix the problem.

It would be good to have those two right next to each other in the
documentation, and right at the beginning, so that a user can come in cold,
read for a minute or less, and use the class.

> > Wish list:
> > 
> > - A predefined saver that saved all formatting adjustments 
> would be quite
> > nice.  Specifically, this would combine the savers flags, 
> precision, width, fill, and locale.
> 
> Added (though not in that combination).

What do you think of that combination?  It seemed like a good catch all for
all "common" formatting needs.  That is, the remainder (tie, rdbuf,
exception) are probably quite rarely set within code that would need to save
the state.  Then again, maybe exception would be somewhat common.  The
question then becomes one of a performance benefit of avoiding saving tie
and rdbuf.  I suppose it's too small to justify the complexity of another
saver combination.  What do you think?
 
> > - A manipulator version would be nice.  A sample usage would be:
> > cout << save_stream_format << setw(5) << x;
> 
> This would involve combining saver techniques with temporary 
> objects, which
> I don't want to tackle (due to the subtle issues).

Ah, yes, it is indeed much harder than it looked.  The implementation I had
in mind didn't work.