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-02 13:20:58

Nathan Ridge wrote:

> This is documented both in the Introduction page of the documentation:
>
> "This library therefore provides the means to adapt standard-like
> containers,
> null terminated strings, std::pairs of iterators, and raw arrays (and
> more),
> such that the same generic code can work with them all. The basic
> idea is
> to add another layer of indirection using metafunctions and
> free-standing
> functions so syntactic and/or semantic differences can be removed."
> [1]
>
> and in the page that documents Method 1 of making types model ranges:
>
> "The primary templates in this library are implemented such that
> standard
> containers will work automatically and so will boost::array. Below is
> given
> an overview of which member functions and member types a class must
> specify to be useable as a certain Range concept." [2]

This is all beside the point.

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.

Looking at this some more, It does raise questions to me about the design of 
the library and extenstion mechanism.  But it would be pre-mature to 
consider them now..

>> 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?

Robert Ramey