Boost logo

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

> 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

Boost-users list run by williamkempf at, kalb at, bjorn.karlsson at, gregod at, wekempf at