David Abrahams wrote:
"Orjan Westin" <orjan.westin@gmx.net> 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-itera...
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