Re: [boost] [range] irange is not very eloquent

Subject: Re: [boost] [range] irange is not very eloquent
From: vicente.botet (vicente.botet_at_[hidden])
Date: 2010-04-28 06:31:46

----- Original Message ----- 
From: "Neil Groves" <neil_at_[hidden]>
To: <boost_at_[hidden]>
Sent: Wednesday, April 28, 2010 9:48 AM
Subject: Re: [boost] [range] irange is not very eloquent

> 
>> Hi Neil,
>> I know that irange is a function. This why I said "I will expect in this
>> section (Provided ranages) ranges and not functions".
>>
>>
> I'll add it to both sections. There is no harm in doing that.

Great.  
 
>> You have not commented nothing related to the name.
>>
>>
> The name is irange. I normally prefer long names but it was a frequent
> review comment that my names were excessively long. Amusingly the make_
> prefix you suggested was the target for much negative commentary. The
> integer range is probably going to be frequently used and we will soon
> recognize it. Having to type integer_range is lengthy and upon reading can
> easily be mistaken for iterator_range.

Unfortunately I didn't spent enough time during the review. I really think "irange" is a bad name.
 
>> I'm afraid, but I don't find integer_range in iterator_range section.
>>
>>
> There isn't an integer_range and this is why you can't find the
> documentation! I think you are misreading the code or docs. It is exactly
> the ease of this misreading that is the reason the name is 'irange' and not
> 'iterator_range'.
 
Then you need to change the prototypes in the documentation See below [1] ***integer_range***

template<class Integer>
[1] ***integer_range***< range_detail::integer_iterator<Integer> >
irange(Integer first, Integer  last);
 
 
>> BTW, it is not clear from the documentation on which file are declared each
>> one og the classes or functions. It would be great to have this information
>> in the pages contained in the Reference section.
>>
>>
> There is a header files section for this purpose. Again this is incomplete
> on the trunk and release branch with updates coming within the next couple
> of days.
Great. 
 
>> In Reference section maybe tou can add a Core section that will include the
>> first 3 subsections
>> Overview
>> Synopsis
>> Semantics
>>  Metafunctions
>>  Functions
>>
>> The section Utilities is out of the reference section. I suppose that this
>> was just a nesteing error.
>> Utilities
>>  Class iterator_range
>>  Class sub_range
>>  Function join
>>
>> Aren't the new headers missing from the section "Library Headers"?
>>
>>
> Many are missing. I have been working on this for some time. There are a
> number of issues with the current docs. There are also tests that haven't
> yet been included into the trunk or release branch. They do however pass and
> will be introduced into the trunk soon.
> 
> The additional documentation I will be committing within a day or two to the
> trunk. I expect to be able to merge this to release shortly afterwards.
> 
> 
>> I see also some interfaces in the documentation using the range_detail
>> namespace. For example in
>>   template<class Integer>
>>  integer_range< ***range_detail::integer_iterator<Integer>*** >
>>  irange(Integer first, Integer  last);
>>
>> It would be better to replace this details by implementation_defined and
>> add what are the expected behaviour, and how a user can use this types that
>> depends on the implementation. For example how a user can assign the result
>> of the irange function to a variable?
>>
>>
> Actually I need to properly document my return ranges. This was part of the
> review feedback. The return types are not mere implementation details as I
> originally intended. User of the library do need to know them sometimes. I
> also need to better document the Range Return Categorys in the Range
> Adaptors documentation.

My preceding comment wasn't about  range return types, but about a detail implementation on the doc.
 
>> integer_range< ??? > var = irange(0,5);
>>
>> I was wondering if irange can be used with integral types as char and bool?
>> For example,
>>
>> integer_range< ??? > lower_case = irange('a','z'+1);

Could you comment the above?

>> >From the Boost.Iterator doc. counting_iterator is a model of a random
>> access iterator if the integral type provide the needed functions. So what
>> is the difference between counting_range and irange functions?

Could you answer the preceding question?

>> It is a shame that we can not have links between different libraries, so
>> links to the Incrementable requirements defined in Boost.Iterator can be
>> linked from Boost.Range, or can we?
>>
>>
> I'm not sure if this is possible either. I confess to being a bit of a
> newbie to the Boost documentation tool chain. If this is possible then I
> shall improve this aspect sometime after the release of 1.43.
> I hope to add to the documentation after the release anyhow. I think the
> documentation would benefit from several tutorials.

Why these tutorials have not been written before releasing the new Boost.Range library?

Best,
Vicente