Re: [boost] [iterator] indirect_iterator->

From: Orjan Westin (orjan.westin_at_[hidden])
Date: 2005-11-22 12:24:01

David Abrahams wrote:
> "Orjan Westin" <orjan.westin_at_[hidden]> writes:
>
> You're right; the documentation is wrong, or at least very obtuse.  In
> the synopsis for indirect_iterator, it only shows the parts of the
> interface that are added to what it inherits from iterator_adaptor,
> and iterator_adaptor is not shown as a base.  The only hint you have
> is in:
>
>
> http://www.boost.org/libs/iterator/doc/indirect_iterator.html#indirect-iterator-models
>
> which, in combination with the standard iterator requirements,
> actually tells you that operator-> is present.

Yes, but for those of us who do not have a copy of the standard, it could do
with making it a tad more explicit, if I may say so.

>> Just out of curiosity, do you ever think you (and the "you" here is
>> the boost community, not you David) fall for the temptation to do
>> things more powerful and complex than they need be?
>
> Why would that be tempting?

The messages I've seen about adding hex dump to the logging library lately
illustrate what I mean, I think.

>> Just looking at the <counts> 14-18 includes in indirect_header.hpp
>> is a bit scary, really
>
> Why?  Most of those headers define a single component whose name
> corresponds exactly to the header name.  Would you rather see
>
>   #include <big_mess_o_stuff.hpp>
>
> instead?

No, of course not.  But since I found the documentation unclear, I thought I
have a look at the code, and seeing this many dependencies for what I at
first thought ought to be a relatively straightforward couple of classes was
intimidating, since I would have to follow a fair few of those includes to
be able to understand the code.

>> , and personally I found the code a bit hard to follow.
>
> The first motivation in producing the library is to make it as useful
> and useable as possible.

Granted. A library user should never have reason to look at the code. This
puts a lot of demands on the documentation, though.

> Occasionally code clarity suffers.  However,
> in this case -- aside from more comments which would be nice -- I
> can't see how the clarity could be improved.  I certainly don't see
> how fewer #includes would aid clarity.

By itself, reducing the number of #includes wouldn't do anything.  The code
would still be quite complex, and require an understanding of pointee, mpl,
ia_dflt_help in order to be understood.

>> This is not unique to the iterator library either - I often get a
>> feeling when looking at things in boost and other publicly
>> accessible libraries that things are somethimes done not so much
>> because that's what needs to be done, but because they are
>> interesting, technologically challenging or cool.  I know I
>> sometimes find myself overengineering simply because I think
>> "wouldn't it be cool if..."
>
> Feel free to design something simpler that works just as well, if you
> think it can be done.

I don't think it can be done.  I've been using something I wrote some years
ago, and it has served me well enough, but it's far from as powerful.  It's
quite small and simple to understand, though.

The reason I had a look at the boost::indirect_iterator was that I've been
preparing something I thought I'd release in the wild, and so it might be a
good idea to use the standard one instead of mine.

> Often, to provide easy-to-use interfaces,
> libraries need to do complicated things in their implementations.  The
> fact that the docs were not quite adequate in this case aside, users
> are expected to understand the libraries from their documentation.

Agreed.

> Libraries are not written primarily so that users will be able to
> understand their implementations, but so that they will provide users
> with the best service.

And again, I agree.

I did not mean to critisise - as I said, it was just idle curiosity.

Cheers,
Orjan