[Boost-users] Re: iterator_adaptor: disguise iterator as const_iterator?

From: David Abrahams (dave_at_[hidden])
Date: 2004-12-02 13:07:48

Martin Wartens wrote:
 >>> I have to say that the documentation was not of much help to me.
 >>> There are lots of complicated implementation details but only
 >>> small examples.
 >>
 >> You're not kidding?  Did you go through the tutorial starting with
 >>  iterator_facade (http://tinyurl.com/2gzpz#tutorial-example) which
 >>  continues on to the iterator adaptor tutorial
 >> (http://tinyurl.com/58e2p#tutorial-example)?  Gee, it looks from
 >> the below like you did!
 >
 > No, I am serious. Looking at the iterator_facade doc, first of all it
 > does not tell me what it is all about. The one sentence in the
 > abstract is indeed very abstract.

Wow, good point.

 > I would like to see the doc
 > starting with a motivating use case. It should explain me why I would
 > want to use it. Then the overview is concerned mainly with the
 > implementation history and why policy classes are not used anymore.

Yep.  You're supposed to jump to the tutorial, but that really belongs
at the front, doesn't it?

 > These are details that I would expect in the darkest corner of the
 > appendix.

Yep.

 > The doc continues with more implementation details and
 > describes problems that had to be solved. That is interesting, but it
 > doesn't give me a start on how to use this library. The Reference
 > listing with the class interface I would expect at the end of the
 > doc. I noticed that the template parameters are not explained before
 > the tutorial.

Okay.

 > I would like to see more examples, if that is possible.

Hm.  Examples of what?

 > I hope this didn't sound rude, I know it must be hard to write a doc
 > for such a complicated library.

Yes, but that usually means the library needs to be simplified ;-)

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com