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.
My comment was partly to invite others that have struggled with the same area to come forward and tell me I'm wrong. They might yet do so.
> 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 put this forward as a hypothesis based on the previous email where you suggested that it wasn't obvious which types worked with range algorithms. The types need to be a model of the appropriate concepts. It's as simple as that from my perspective. Therefore I can only imagine someone that finds it hard to comprehend which types work with range algorithms having difficulty with the language used to expression the requirements.
> 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.
Please demonstrate what you would consider an improvement. I think many of us have tried to obtain something from you to help us. I appreciate that negative criticism is to some extent useful, but you aren't giving me clear enough suggestions for positive corrective action. I can't do anything for you until I understand potential solutions. I accept that my failure to understand your suggestions may simply be that I'm doing a poor job of understanding your suggestions.
> The algorithm
> documentation clearly defines the minimum Range Concept that the
> template types must model.
I would disagree that it's clear.
I'm comfortable to disagree with you on this. Boost.Range being largely Concept-based is a major reason the library is so general and interoperable with existing standard Containers and containers from other libraries. This evidently contributes to usefulness. Perhaps being an early adopter of Concept-based approaches comes with some learning-curve disadvantage. I believe the learning-curve is well worth the effort for using this library, for using other libraries, and for writing your own libraries. Of course, that's just my opinion.
> 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.
That's a good suggestion. I'm happy to try and find time to do this. I'm also happy to accept your patches to 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.
I was not suggesting you were less smart. I think it is fair to point out that your criticism of the documentation is the first of this nature despite the library being adopted by many. It doesn't make you wrong, but it is evidence that the documentation is not lacking to the point of making the library extremely difficult to use. It might be that you have less experience with Concepts; that is an entirely different suggestion to suggesting that you aren't as smart. I assume there are a very large number of subjects where you would understand fundamental material that I am absolutely clueless about.
> Boost.Range is heavily designed around Concepts to great advantage.
I'm suggesting that Boost.Range has this wrong.
Yes you are, but frustratingly again without any positive suggestive action which is annoying and unhelpful. I'm trying very hard to comprehend your issues and I've asked previously for you to put forward something constructive. I think this would help me comprehend your points. It's perhaps harder for me to see deficiencies in the documentation that any random person since I've been so immersed in the library for so long. I'm perhaps simply assuming something, but I require more constructive feedback to understand the issue you having and the solution you are proposing. Where you have provided positive suggestions such as increased examples I have immediately been able to understand and put this onto my todo list.
> 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?
To the readers. Many documents / papers I read have a better enumeration of the pre-requisite subject matter that is expected to be understood as foundational material. I was trying to find actions to make the documentation better. I wondered if this might help address your concerns. However your response shows that I have misunderstood the source of your confusion anyhow, so this isn't a valid solution.
Regards,
Neil Groves