Rewrite of std.range docs (Was: Re: Making sense of ranges)

[Mike Parker]

On 3/27/2012 7:26 PM, Marco Leise wrote:
> Am Tue, 27 Mar 2012 06:00:58 +0200
> schrieb "Jesse Phillips"<jessekphillips+D at gmail.com>:
>
>> On Monday, 26 March 2012 at 00:50:32 UTC, H. S. Teoh wrote:
>>
>>> This thread has further convinced me that std.range's docs
>>> *need* this
>>> rewrite. So here's my first attempt at it:
>>>
>>> 	https://github.com/quickfur/phobos/tree/stdrange_docs
>>
>> I find that opening to be much better. Look forward to the
>> improvement.
>
> I agree. To the newcomer it is now easy to see the rationale behind ranges and why they should take the time to understand the concept. What I missed when I started with D, was some explanation that the returned ranges from many algorithms are compile time generated structs. I often found myself wondering why I don't get an array returned when I put one into the algorithm and had to do array(...) all over the place, when actually I could often have passed on the ranges directly to a following foreach or similar.
>

Yes. When I saw that the implementation of ranges required more than a 
few minutes of digging around to comprehend, I just avoided them 
completely for quite a while. When I finally did decide to roll up my 
sleeves and get dirty, the lack of documentation in Phobos or on the web 
site was particularly frustrating. I was going to complain about it here 
in the newsgroups (not sure if I did or not), but then Ali announced the 
translation of his book chapter on ranges and I was enlightened.

> "Ranges whose elements are sorted affords ..."<- insert a comma before affords perhaps? It would help non-native speakers.
>

Actually, a comma there would be incorrect. But because 'Ranges' is 
plural, 'affords' should lose the 's' (Ranges whose elements are sorted 
afford...). If the wording is confusing, perhaps it could be rewritten 
as "Sorted ranges afford..."