"David Abrahams"
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. Even the name "iterator_adaptor" provides no clue that it can also be used to create an iterator. 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? 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. 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 ;-) Keith MacDonald