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

From: David Abrahams (dave_at_[hidden])
Date: 2004-01-08 21:01:42

"Keith MacDonald" <boost_at_[hidden]> writes:

> "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.

That's correct.  Your Node* _is_ an existing iterator, as are all
pointers.

> Even the name "iterator_adaptor" provides no clue that it can also be used
> to create an iterator.  

It's actually very rare that there's a non-iterator which provides
enough of the useful iterator operations to be used with iterator
adaptor (e.g. int, used with counting_iterator).  I don't think
there's anything wrong with making those details less apparent.

> 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?  

If you spell everything out in the introduction, you need to write a
new introduction.

> 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.  

How many times do I have to repeat that

  We're working on the docs.  That document is the standards proposal,
  but the Boost (user-level) docs aren't complete yet.

??

> 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 ;-)

I'm providing free software *and* free documentation as time allows; I
really don't need to have my motivations insulted that way.  A smiley
doesn't make it funny.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com