Neil Groves wrote:
Frankly, I re-read this documentation and its completely obvious whether a type will work with a range algorithm to me. I then got a small sample of developers I know to read it, and none had an issue. If the type is a proper model of the Concept it will work.
I'm not disputing that I'm in the minority here.
I would hazard a guess that you are finding it hard to determine if a type will work with a range algorithm because you haven't yet got a clear understanding of Concepts and what it means for a type to model a Concept.
I would disagree with this as well - not that it's relevant.
I recommend studying Concepts they formalise generic programming in a manner that makes it easier to reason about complex large-scale generic designs.
Thanks for this advice.
The information is correctly stated in the documentation AFAICT and with the appropriate background knowledge I believe it is clear and unambiguous.
Of course this is the crux of our disagreement.
The algorithm documentation clearly defines the minimum Range Concept that the template types must model.
I would disagree that it's clear.
The documentation could always use more examples. I did put these into a separate area in the documentation because I wanted to make them all have tests. The change of layout might not have been optimal and I'll think about this.
I would suggest that each template class/function have a small example. The fusion library in particular does this and I've found it very helpful. I also suspect it helps detect errors in the documentation.
Boost.Range has had these Concepts and fundamentally the same documentation about the fundamental aspects of Ranges for many versions. It does not appear to have been a barrier to entry, or caused much confusion among the general Boost user population.
I'm suggesting improvements for those of that aren't so smart.
Boost.Range is heavily designed around Concepts to great advantage.
I'm suggesting that Boost.Range has this wrong.
It is therefore inherently necessary to comprehend Concepts to understand Boost.Range.
I don't believe that it is necessary for users to comprehend Concepts to use a library. Definitely helpful - but not necessary. I personally find it helpful - that is why I carefully read the documentation concerning them - and found the documentation misleading and in need of improvement.
The only thing I can think of doing to the documentation to address this is to perhaps make more clear the importance of understanding Concepts.
To whom? Robert Ramey