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

Subject: Re: [Boost-users] [range] questions about documentation and usage
From: Nathan Ridge (zeratul976_at_[hidden])
Date: 2012-11-02 17:37:33

> My concern is very simple:
> 
> The page 
> http://www.boost.org/doc/libs/1_51_0/libs/range/doc/html/range/concepts/single_pass_range.html 
> is crystal clear.  It says that any SinglePassRange must implement the 
> expression boost::begin(a) where a is a model of a SinglePassRange.
> 
> This is not actually a requirement on any model of a SinglePassRange but 
> rather a requirement on boost::begin. But boost::begin is not supplied by 
> the user!  This documentation doesn't tell me what operation the type 
> argument has to support in order to be used as argument to a range. It's 
> just non-sensical and therefore confusing.  There is nothing on this page 
> which would indicate to me that something like <vector> would satisify the 
> concept.  The page is does not document a "concept" in the C++ manner.

It is common practice in Boost libraries for a concept to be associated with
two sets of interfaces: an interface that the consumer of the concept uses
to work with models of the concept, and the interface that the provider of
the concept (that is, the programmer who is writing a type to model the
concept or adapting a third-party type to model the concept) uses to make
his type model the concept.

It is of course possible for the two interfaces to be the same, but in some
cases this is problematic. If this single interface uses member functions,
then third-party types which do not have those member functions cannot 
be adapted to model the concept. An interface that uses non-member functions
avoids this problem, but sometimes there are pre-existing conventions
(e.g. container classes having begin() and end() member functions) that
that are already in wide use and it would be annoying if every class that
already uses those conventions would now have to write member function
wrappers to model the interface.

Having two different interfaces solves this problem: consumers of the
concept use the interface meant for them, and providers of models of
the concepts use mechanisms meant for them to model the concept. The
library defining the concept provides the glue between the two.

This is the case with Boost.Range: the interface for consumers is
boost::begin() and boost::end(). Model providers have a choice of
either using member begin() and end() functions, or non-member
range_begin() and range_end() functions found using ADL.

The C++0x concepts proposal was going to alleviate this need for
two interfaces by providing a language construct named "concept_map"
which allowed writing the glue code that allows adapting a type with a
different interface to model a concept with the required interface.
Sadly, that proposal did not pass, so in Boost today we have to keep
using this work-around with two interfaces.

>>> d) I forgot to add this.  The exposition of each  function, template
>>> etc,  could
>>> benefit by including a small example.  This is common practice
>>> among other similar libraries.  It is generally very helpful.
>>
>> Agreed. Once again, I'm sure the maintainers would welcome patches.
> 
> lol - so by making this observation it's incumbant on me to to create and 
> test 100 examples of each feature of the library?

Not at all. I'm just pointing out that *someone* has to do it, and in the
world of free/open-source software, often the person with sufficient
motivation to implement a feature (or write documentation snippet etc.) 
is the one who asks for it.

Regards,
Nate