[Boost-users] Re: Converting from const to non-constwithiterator_adaptor

From: Keith MacDonald (boost_at_[hidden])
Date: 2004-01-08 15:55:46

"David Abrahams" <dave_at_[hidden]> wrote in message
news:u7k021gic.fsf_at_boost-consulting.com...

> I realize the measure of docs is in their effectiveness, but do you
> really think there's anything wrong with painting with a broad brush
> on the main page and then providing detailed revision in specific
> docs?
> -- 

Only if the broad brush information paints a false picture:

"In order to ease the implementation of new iterators, the Boost.Iterator
library provides the iterator_facade class template, which implements many
useful defaults and compile-time checks designed to help the author iterator
ensure that his iterator is correct. It is common to define a new iterator
which behaves like another iterator, but which modifies some aspect of its
behavior. For that purpose, the library supplies the iterator_adaptor class
template, which is specially designed to take advantage of as much of the
underlying iterator's behavior as possible."

By reading that, I was led to believe that I should use iterator_facade to
create new iterators, and iterator_adaptor to modify existing iterators.
Even the name "iterator_adaptor" provides no clue that it can also be used
to create an iterator.  If you approach the Introduction in
iterator_adaptor.html with those preconceptions, it's easy to miss the
implication that the base type need not be an iterator.  Why not spell it
out?  In my opinion, for what it's worth, the documentation seems to be
aimed at the developers of the library (so you're all singing from the same
hymn sheet), rather than potential users.  Clearly, both audiences need to
be catered for - unless it was just an academic excercise.  Of course, if
you're already writing the text book for us users, then I completely
understand the advantages of impenetrable free documentation ;-)

Keith MacDonald