On 2014-12-27 09:32, Mike Parker wrote:

> The proverbial straw that prompted my blog rant back then was to do with
> std.string. I wanted to split a string on a specific character. So I
> looked in the std.string docs for a split function. There wasn't one.
> There's a 'splitLines' -- I don't recall if it existed then, but it
> wouldn't have been what I was looking for anyway. So I searched the docs
> and found std.array.split. I don't recall what the docs looked like
> then, but now this is what we have.
>
> pure @safe S[] split(S)(S s) if (isSomeString!S);
>
> This above is grokkable -- it's fairly clear that S is a string and that
> an array of strings is returned. Then we get these next two versions:
>
> auto split(R, E)(R r, E delim) if (isForwardRange!R &&
> is(typeof(ElementType!R.init == E.init)));
> auto split(alias isTerminator, R)(R r) if (isForwardRange!R &&
> is(typeof(unaryFun!isTerminator(r.front))));
>
> Umm... all I want is to split a string on a specific character. What's
> all this mess about ElementTypes and Rs and Es and unaryFuns and....
>
> The description, "Eagerly splits s into an array, using delim as the
> delimiter." suggests this is what I'm looking for. I suppose I can just
> pass it a string and a character and see what happens. But, that's just
> trial and errro. The docs don't help me understand it. I don't like
> using functions I don't understand. Heaven help me if I find a need for
> std.array.join:
>
> ElementEncodingType!(ElementType!RoR)[] join(RoR, R)(RoR ror, R sep) if
> (isInputRange!RoR && isInputRange!(Unqual!(ElementType!RoR)) &&
> isInputRange!R && is(Unqual!(ElementType!(ElementType!RoR)) ==
> Unqual!(ElementType!R)));
> ElementEncodingType!(ElementType!RoR)[] join(RoR)(RoR ror) if
> (isInputRange!RoR && isInputRange!(Unqual!(ElementType!RoR)));
>
> So the function to split a string on line breaks, which is
> string-specific, is in std.string. The function to split a string on
> whitespace, again string-specific, is in std.array. The function to
> split any range on any element is in std.array. Which means I have to
> think of strings not just as arrays, but as ranges, and have to
> understand that some range functions are in std.range, others in
> std.array and still others in std.algorithm. That means that I don't
> always know where to look when I want to do something I've not done
> before. Even if I do manage to find what I'm looking for, I then may
> discover that it doesn't work because I want an array, but the function
> returns a range and I need to convert it to an array, which means arrays
> aren't really ranges like I thought and...

There's also "split" vs "splitter" and "join" vs "joiner". This doesn't make it easier.

-- 
/Jacob Carlborg

On 2014-12-27 09:32, Mike Parker wrote:

> auto split(R, E)(R r, E delim) if (isForwardRange!R &&
> is(typeof(ElementType!R.init == E.init)));
> auto split(alias isTerminator, R)(R r) if (isForwardRange!R &&
> is(typeof(unaryFun!isTerminator(r.front))));
>
> Umm... all I want is to split a string on a specific character. What's
> all this mess about ElementTypes and Rs and Es and unaryFuns and....

What we need is simplified signatures in the documentation. The template constrains could be hidden, then have a button to show them. Same thing with special default values, i.e. __FILE__, __LINE__ and so on.

https://issues.dlang.org/show_bug.cgi?id=13676

-- 
/Jacob Carlborg

On Saturday, 27 December 2014 at 11:42:45 UTC, Jacob Carlborg wrote:
> On 2014-12-27 09:32, Mike Parker wrote:
>
>> The proverbial straw that prompted my blog rant back then was to do with
>> std.string. I wanted to split a string on a specific character. So I
>> looked in the std.string docs for a split function. There wasn't one.
>> There's a 'splitLines' -- I don't recall if it existed then, but it
>> wouldn't have been what I was looking for anyway. So I searched the docs
>> and found std.array.split. I don't recall what the docs looked like
>> then, but now this is what we have.
>>
>> pure @safe S[] split(S)(S s) if (isSomeString!S);
>>
>> This above is grokkable -- it's fairly clear that S is a string and that
>> an array of strings is returned. Then we get these next two versions:
>>
>> auto split(R, E)(R r, E delim) if (isForwardRange!R &&
>> is(typeof(ElementType!R.init == E.init)));
>> auto split(alias isTerminator, R)(R r) if (isForwardRange!R &&
>> is(typeof(unaryFun!isTerminator(r.front))));
>>
>> Umm... all I want is to split a string on a specific character. What's
>> all this mess about ElementTypes and Rs and Es and unaryFuns and....
>>
>> The description, "Eagerly splits s into an array, using delim as the
>> delimiter." suggests this is what I'm looking for. I suppose I can just
>> pass it a string and a character and see what happens. But, that's just
>> trial and errro. The docs don't help me understand it. I don't like
>> using functions I don't understand. Heaven help me if I find a need for
>> std.array.join:
>>
>> ElementEncodingType!(ElementType!RoR)[] join(RoR, R)(RoR ror, R sep) if
>> (isInputRange!RoR && isInputRange!(Unqual!(ElementType!RoR)) &&
>> isInputRange!R && is(Unqual!(ElementType!(ElementType!RoR)) ==
>> Unqual!(ElementType!R)));
>> ElementEncodingType!(ElementType!RoR)[] join(RoR)(RoR ror) if
>> (isInputRange!RoR && isInputRange!(Unqual!(ElementType!RoR)));
>>
>> So the function to split a string on line breaks, which is
>> string-specific, is in std.string. The function to split a string on
>> whitespace, again string-specific, is in std.array. The function to
>> split any range on any element is in std.array. Which means I have to
>> think of strings not just as arrays, but as ranges, and have to
>> understand that some range functions are in std.range, others in
>> std.array and still others in std.algorithm. That means that I don't
>> always know where to look when I want to do something I've not done
>> before. Even if I do manage to find what I'm looking for, I then may
>> discover that it doesn't work because I want an array, but the function
>> returns a range and I need to convert it to an array, which means arrays
>> aren't really ranges like I thought and...
>
> There's also "split" vs "splitter" and "join" vs "joiner". This doesn't make it easier.

Having array in std.array is also rather confusing for a newbie, it's an extra complication in their fight with lazy when they will be trying to use std.algorithm.

On Sat, 27 Dec 2014 12:46:09 +0100
Jacob Carlborg via Digitalmars-d <digitalmars-d@puremagic.com> wrote:

> What we need is simplified signatures in the documentation. The template constrains could be hidden, then have a button to show them. Same thing with special default values, i.e. __FILE__, __LINE__ and so on.
i agree, but the direction is slightly different: we should have a script which hides them after the page is loaded and creates corresponding buttons.

On 12/27/2014 12:32 AM, Mike Parker wrote:
> Wtf is ElementType? Where is R defined? Searching the site for "random-access
> range" will eventually bear fruit, it doesn't help in understanding the whole
> function.

A token improvement:

https://github.com/D-Programming-Language/phobos/pull/2812

On 12/26/2014 8:21 AM, Andrei Alexandrescu wrote:
> I thought the std.algorithm stuff is decently documented. What would be the
> major pain points? -- Andrei

A large number of the algorithms lack one or more of:

1. examples

2. any mention of what they return, and if they do, they do not use a Returns: section

3. almost none have a Params: section

4. some terms need exposition, like: "Implements the homonym function present in various programming languages of functional flavor." I have no idea what that means. Googling "homonym function" doesn't produce anything that looks relevant. A link to an entry in http://dlang.org/glossary.html would be good.

On Saturday, 27 December 2014 at 20:24:27 UTC, Walter Bright wrote:
> 4. some terms need exposition, like: "Implements the homonym function present in various programming languages of functional flavor." I have no idea what that means. Googling "homonym function" doesn't produce anything that looks relevant. A link to an entry in http://dlang.org/glossary.html would be good.

"Homonym" is just a fancy way of saying "with the same name". But I agree:
 1) The docs should avoid overly fancy language.
 2) Analogies to other languages should never be the primary means of explanation.

David

On 12/27/2014 2:14 PM, David Nadlinger wrote:
> On Saturday, 27 December 2014 at 20:24:27 UTC, Walter Bright wrote:
>> 4. some terms need exposition, like: "Implements the homonym function present
>> in various programming languages of functional flavor." I have no idea what
>> that means. Googling "homonym function" doesn't produce anything that looks
>> relevant. A link to an entry in http://dlang.org/glossary.html would be good.
>
> "Homonym" is just a fancy way of saying "with the same name". But I agree:
>   1) The docs should avoid overly fancy language.
>   2) Analogies to other languages should never be the primary means of explanation.

Clearly, this should instead be a link to this:

   http://en.wikipedia.org/wiki/Filter_(higher-order_function)

Ironically, that article refers to std.algorithm.filter!

On 12/27/14 12:32 AM, Mike Parker wrote:
> On Friday, 26 December 2014 at 16:21:24 UTC, Andrei Alexandrescu wrote:
>> I thought the std.algorithm stuff is decently documented. What would
>> be the major pain points? -- Andrei
>
> It's fine for someone who is familiar enough with D to decipher it.
> Consider the documentation for sum.
[snip]

Great ideas, thanks. I created https://issues.dlang.org/show_bug.cgi?id=13901 -- Andrei

On 12/27/14 3:42 AM, Jacob Carlborg wrote:
> There's also "split" vs "splitter" and "join" vs "joiner". This doesn't
> make it easier.

Not to mention findSplit - my all-times favorite. -- Andrei