First experience with std.algorithm: I had to resort to writinga

[KennyTM~]

On Jun 9, 10 03:19, Jonathan M Davis wrote:
> Andrei Alexandrescu wrote:
>
>> On 06/08/2010 06:59 AM, bearophile wrote:
>>> Bernard Helyer:
>>>> bool contains(T)(const(T)[] l, T a)
>>>> {
>>>>         foreach(e; l) {
>>>>             if (a == e) {
>>>>                return true;
>>>>             }
>>>>         }
>>>>         return false;
>>>> }
>>>
>>> See also:
>>> http://d.puremagic.com/issues/show_bug.cgi?id=3923
>>
>> That issue stems from the fact that find is quite flexible. I agree it
>> has lost modularity in the process. I'll work on restoring its modularity.
>>
>> Andrei
>
> The biggest issue is the documentation rather than the function, I think. If
> find() can be broken up, that could help, but the main issue is what the
> documentation looks like. It's just too complicated - especially the
> function signature. Pretty much the only sane way to figure the
> std.algorithm functions out is to focus on the examples (which while good
> are still fairly sparse). As it stands, I expect the documentation to scare
> away potential users of std.algorithm. It looks far scarier than it actually
> is. We need to find a way or ways to make the documentation simple like the
> functions are simple to use (since, for the most part they're pretty easy to
> use in spite of their nasty signatures).
>

I agree. Especially the return type of many templated methods are so 
complicated that it just adds close to zero information, for example:

   Take!(Sequence!("a.field[0] + n * 
a.field[1]",Tuple!(CommonType!(B,E),uint))) iota(B, E)(B begin, E end);

A better representation is

   auto iota(B, E)(B begin, E end);

Granted, this means some information is lost when reading the signature, 
but no one is going to actually use the Take!(Sequence!whatever)) type 
directly, why bother.

(There's no need to modify ddoc, just add a Javascript on the page is 
enough.)

Another thing is the documentation feels too "crowded", in particular 
that crazy "navigation bar" on the top is a joke. Why can't it laid out 
vertically?

There should be sections within a module to divide relevant functions 
into groups, e.g.

   1. Capability checking

        template isInputRange(R)
        template isOutputRange(R,E)
        ...

   2. Information of range

        size_t walkLength(Range)(Range range, size_t upTo = size_t.max);

   3. Modifying ranges

        auto retro(R)(R input);
        auto stride(R)(R input, size_t n);
        ...

   4. Constructing ranges

        auto recurrence(alias fun, State...)(State initial);
        auto iota(B, E)(B begin, E end);
        ...