Boost Users :
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
>> 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
> 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
That's correct. Your Node* _is_ an existing iterator, as are all
> 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
> 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
Boost-users list run by williamkempf at hotmail.com, kalb at libertysoft.com, bjorn.karlsson at readsoft.com, gregod at cs.rpi.edu, wekempf at cox.net