Re: [Boost-users] [range] questions about documentation and usage

Subject: Re: [Boost-users] [range] questions about documentation and usage
From: Robert Ramey (ramey_at_[hidden])
Date: 2012-11-03 19:29:53

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