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

Subject: Re: [Boost-users] [range] questions about documentation and usage
From: Neil Groves (neil_at_[hidden])
Date: 2012-11-03 15:10:27

>
> >
> > It is common practice in Boost libraries for a concept to be
> > associated with
> > two sets of interfaces:
> ...
>
> I confess I didn't understand any of this.
>
> It doesn't seem to address my (simple?) observation:
>
> There is no way to read the documentation of SinglePassRange concept and
> know whether some specific type will work with a range algorithm.
>
>
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 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 recommend studying Concepts they formalise generic programming
in a manner that makes it easier to reason about complex large-scale
generic designs. The information is correctly stated in the documentation
AFAICT and with the appropriate background knowledge I believe it is clear
and unambiguous.  The algorithm documentation clearly defines the minimum
Range Concept that the template types must model. 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.

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.

Boost.Range is heavily designed around Concepts to great advantage. It is
therefore inherently necessary to comprehend Concepts to understand
Boost.Range.

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.

Robert Ramey
>
>
HTH,
Neil Groves