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

"Keith MacDonald" writes:

"David Abrahams" wrote in message news:u7k021gic.fsf@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