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-04 20:45:52

Jeffrey Lee Hellrung, Jr. wrote:
> On Sun, Nov 4, 2012 at 1:42 PM, Robert Ramey <ramey_at_[hidden]> wrote:
>
> Jeffrey Lee Hellrung, Jr. wrote:
>> On Sun, Nov 4, 2012 at 10:10 AM, Robert Ramey <ramey_at_[hidden]> wrote:
>>
>> Jeffrey Lee Hellrung, Jr. wrote:
>>> On Sun, Nov 4, 2012 at 1:37 AM, Robert Ramey <ramey_at_[hidden]> wrote:

>>> Is the documentation under [1] and/or [2] unclear?
>>
>> It is.
>>
>> Method 1 provides information I would have expected to find
>> in the SinglePassRange concept. I'm assuming that the member
>> functions and types would be members of any class modeling
>> SinglePassRange.  I say "assuming becaus it doesn't actually
>> say that.
>>
>> Then...why are you assuming that?
>
> Because the documentation says they are member functions
> but it doesn't say of what type.  One has no choice to guess
> or assume.
>
> What do you mean "of what type"?

from page 
http://www.boost.org/doc/libs/1_51_0/libs/range/doc/html/range/reference/extending/method_1.html

Hmmm - upon a closer reading I see the page contains the sentence

"Below is given an overview of which member functions and member types a 
class must specify to be useable as a certain Range concept."

So my assumption is correct - if unnecessary.

> I don't think that's accurate.  If you want to make your own model
> of a concept, you just make sure your types implement all the valid
> expressions.
>

> Maybe in your world. And maybe your world is the correct one. But
> compare Boost.Fusion's Forward Sequence concept documentation [6]
> with its extension mechanism documentation [7]; it parallels
> Boost.Range's documentation.

damn.. your right about fusion describing an extention mechanism.
I either forgot about this or never had occasion to need it.  It's a little
unclear whether this is a requirement or a convenience to make
it easier to "get it right".  My view so far would be that it's
not a requirement to use the extension mechanism but rather
a convenience which helps the author of the extention to
"get it right".  I confess I don't really know though.

Another thing about fusion is that it doesn't have any concept
checking classes.  I've written some for work I was doing but
the lack of them in the library makes it less interesting for
comparison than I thought.

>> I'm sorry, I'm still not following. Can you be more concrete? I don't
>> know what you mean by building a library "concurrently with the
>> documentation", and I'm not sure what your suggestion about "how to
>> go about these things" actually is.
>

wrong link - try this one:

rrsd.com/blincubator.com/advice/

>> #include <boost/concept/assert.hpp>
>> #include <boost/range/algorithm/find.hpp>
>> #include <boost/range/concepts.hpp>
>>
>> struct X { };
>>
>> namespace boost
>> {
>> int const * begin(X&);
>> int const * end(X&);
>> } // namespace boost
>>
>> int main(int argc, char* argv[])
>> {
>>   X x;
>>   //boost::find(x, 0); // compiler error
>>   boost::range::find(x, 0); // compiler error
>>   return 0;
>> }
>> --------
>>
>> Same error comes up as in a BOOST_CONCEPT_ASSERT, pointing to a line
>> referencing range_const_iterator and range_mutable_iterator,
>> suggesting that Boost.Range cannot associate an iterator type with X.

Hmmm - I just tried your example above on both my msvc 9.0 and
gcc 4.5.3 compilers.  The program fails to compile.  It's slightly more
complex on msvc. In this case only the first find fails.  If you switch
the order of the two find statements, still it's the first one.  I'm 
guessing
this is what I was seeing before.  In any case, the find statements
fail to compile even though type X models the concept SinglePassRange
according to the documentation.

Now this is the crux of my complaint.  To me, it's an error on it's face.
I understand you don't agree with this but think we just have to
agree to disagree.

Robert Ramey