[Boost-users] Re: Converting from const tonon-constwithiterator_adaptor

From: Keith MacDonald (boost_at_[hidden])
Date: 2004-01-09 04:59:25

We're clearly on different wavelengths here.  I've often found that if
someone asks an apparently dumb question about my software, or its
documentation, then it's better to improve the area in question, rather than
tell the person he's not using or reading it correctly.  That way, I've
still got a happy customer and one less support issue to have to keep
responding to.

I was only trying to be helpful.

Keith MacDonald

"David Abrahams" <dave_at_[hidden]> wrote in message
news:u7k017ud5.fsf_at_boost-consulting.com...
> "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