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

Subject: Re: [Boost-users] [range] questions about documentation and usage
From: Vicente J. Botet Escriba (vicente.botet_at_[hidden])
Date: 2012-11-02 13:23:55

Le 02/11/12 18:20, Robert Ramey a écrit :
> 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.
I disagree here. The requirement is on the expression boost::begin(a) 
not on how this expression can be provided.
I suspect that it could help if the documentation has a section "Models 
of" for each Concept" which includes the models the library provided 
already.
> 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?
>
I don't think Nathan was suggesting that you provide these patches.

Best,
Vicente