It's unanimous, at least among the three of us posting in this Reddit thread:

https://www.reddit.com/r/programming/comments/3wqt3p/programming_in_d_ebook_is_at_major_retailers_and/cxyqxuz

Something has to be done with the documentation for Phobos functions that involve ranges and templates. The example I gave there is

bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2) if (isInputRange!Range1 && isInputRange!Range2 && !isInfinite!Range1 && !isInfinite!Range2);

Unfortunately, that's less ugly than for a lot of functions. In some circumstances, I can see something like that reminding the author of the function about some details, but it can only confuse anyone else.

There is nothing I can do about this. Who makes these decisions? Can we change it to something useful?

Also, I think the documentation for functions involving ranges needs more "for dummies" examples. Too many of those functions leave the reader not having a clue what to do after calling the function. I know how that can be fixed.

On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
> It's unanimous, at least among the three of us posting in this Reddit thread:
>
> https://www.reddit.com/r/programming/comments/3wqt3p/programming_in_d_ebook_is_at_major_retailers_and/cxyqxuz
>
> Something has to be done with the documentation for Phobos functions that involve ranges and templates. The example I gave there is
>
> bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2) if (isInputRange!Range1 && isInputRange!Range2 && !isInfinite!Range1 && !isInfinite!Range2);
>
> Unfortunately, that's less ugly than for a lot of functions. In some circumstances, I can see something like that reminding the author of the function about some details, but it can only confuse anyone else.

If you're trying to use Phobos without knowing what template constraints and ranges are, you're going to have a bad time.

I'm not sure what else to say here. You can't expect to use the language to it's fullest without understanding these features. It's like trying to use rust with out understanding the borrowing mechanics. And you can't hide the function signature from people because it's necessary for people to know what the constraints for the template arguments are.

> There is nothing I can do about this. Who makes these decisions? Can we change it to something useful?
>
> Also, I think the documentation for functions involving ranges needs more "for dummies" examples. Too many of those functions leave the reader not having a clue what to do after calling the function. I know how that can be fixed.

I wrote that function, it's documentation, and wrote the examples. In the examples, I clearly show that the function can be used with normal arrays and the explaination in the docs of what the function does is drop dead simple to understand.

On Mon, Dec 14, 2015 at 07:04:46PM +0000, bachmeier via Digitalmars-d wrote:
> It's unanimous, at least among the three of us posting in this Reddit thread:
> 
> https://www.reddit.com/r/programming/comments/3wqt3p/programming_in_d_ebook_is_at_major_retailers_and/cxyqxuz
> 
> Something has to be done with the documentation for Phobos functions that involve ranges and templates. The example I gave there is
> 
> bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2) if
> (isInputRange!Range1 && isInputRange!Range2 && !isInfinite!Range1 &&
> !isInfinite!Range2);
> 
> Unfortunately, that's less ugly than for a lot of functions. In some circumstances, I can see something like that reminding the author of the function about some details, but it can only confuse anyone else.

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


> There is nothing I can do about this. Who makes these decisions? Can we change it to something useful?

What would constitute "useful" to you?


> Also, I think the documentation for functions involving ranges needs more "for dummies" examples. Too many of those functions leave the reader not having a clue what to do after calling the function. I know how that can be fixed.

Let's see the PR's, then.


T

-- 
The computer is only a tool. Unfortunately, so is the user. -- Armaphine, K5

On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
> It's unanimous, at least among the three of us posting in this Reddit thread:
> ...

Take for example C# Docs: https://msdn.microsoft.com/en-us/library/system.collections.arraylist.addrange.aspx

Syntax C#:

public virtual void AddRange(
	ICollection c
)

Parameters:
    c
    Type: System.Collections.ICollection
    The ICollection whose elements should be added to the end of the ArrayList. The collection itself cannot be null, but it can contain elements that are null.

Clean, simple and instructive!

On the otherhand, imagine a newbie looking:

bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2) if (isInputRange!Range1 && isInputRange!Range2 && !isInfinite!Range1 && !isInfinite!Range2);


Well, most of my friends of college that I indicated D language thinks the D docs is confusing.

Ron.

On Monday, 14 December 2015 at 19:56:29 UTC, dnewbie wrote:
> On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
>> It's unanimous, at least among the three of us posting in this Reddit thread:
>> ...
>
> Take for example C# Docs: https://msdn.microsoft.com/en-us/library/system.collections.arraylist.addrange.aspx
>
> Syntax C#:
>
> public virtual void AddRange(
> 	ICollection c
> )
>
> Parameters:
>     c
>     Type: System.Collections.ICollection
>     The ICollection whose elements should be added to the end of the ArrayList. The collection itself cannot be null, but it can contain elements that are null.
>
> Clean, simple and instructive!

You're not really comparing apples to apples here. isSameLength uses generics and type constraints while AddRange uses OOP. isSameLength will accept any type that conforms to the concept of a finite input range while AddRange will only accept values that inherit from or are System.Collections.ICollection. One is inherently more complex than the other.

> On the otherhand, imagine a newbie looking:
>
> bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2) if (isInputRange!Range1 && isInputRange!Range2 && !isInfinite!Range1 && !isInfinite!Range2);

They can look at the examples below and see that the function accepts strings and arrays. And they can look at the parameters section and see that r1 and r2 need to be "finite input range"s if they can't read the function signature.

On Mon, Dec 14, 2015 at 08:08:20PM +0000, Jack Stouffer via Digitalmars-d wrote:
> On Monday, 14 December 2015 at 19:56:29 UTC, dnewbie wrote:
[...]
> >On the otherhand, imagine a newbie looking:
> >
> >bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2) if
> >(isInputRange!Range1 && isInputRange!Range2 && !isInfinite!Range1 &&
> >!isInfinite!Range2);
> 
> They can look at the examples below and see that the function accepts strings and arrays. And they can look at the parameters section and see that r1 and r2 need to be "finite input range"s if they can't read the function signature.

While I agree with you in principle, I also think that one has to admit, that function signature looks far more scary than it actually is. A lot of this can probably be attributed to lack of control over the formatting of various elements in the signature. It's just a single dense blob of stuff that you have to stare at for at least 2 full seconds before you can parse it completely (or longer if you're new to D).

Imagine, for example, if the docs were to be formatted a little better, say something like this:

	bool isSameLength(Range1, Range2)
	                 (Range1 r1, Range2 r2)
		if (isInputRange!Range1 &&
		    isInputRange!Range2 &&
		    !isInfinite!Range1 &&
		    !isInfinite!Range2)

The sig constraint block can be rendered in a different font / font size / color / whatever. The CT parameters similarly can be visually distinguished from the RT parameters.

Currently, this isn't possible yet, due to limitations in ddoc:

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

In theory, though, this should not be hard to add -- somebody just has to take the time to implement it in ddoc.d. Once we have that, it's just a matter of putting in the right macros in the ddoc stylesheets.


T

-- 
Computerese Irregular Verb Conjugation: I have preferences.  You have biases.  He/She has prejudices. -- Gene Wirchenko

On Monday, 14 December 2015 at 19:38:26 UTC, Jack Stouffer wrote:

> If you're trying to use Phobos without knowing what template constraints and ranges are, you're going to have a bad time.

D is doomed if new users have to understand template constraints and ranges to use the standard library. To be honest, I don't know why you should have to understand either of those to test if two arrays have the same length.

> I'm not sure what else to say here. You can't expect to use the language to it's fullest without understanding these features.

There's a difference between using all the features of a language and the documentation of the standard library. The documentation should be accessible to new users of the language.

> I wrote that function, it's documentation, and wrote the examples. In the examples, I clearly show that the function can be used with normal arrays and the explaination in the docs of what the function does is drop dead simple to understand.

I don't think you wrote the part I quoted - as far as I know, it was generated automatically. The parts that you wrote are really good. Other functions should be documented like that. The only criticism I'd have is that there needs to be a link to intro material on ranges.

On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
> It's unanimous, at least among the three of us posting in this Reddit thread:
>
> https://www.reddit.com/r/programming/comments/3wqt3p/programming_in_d_ebook_is_at_major_retailers_and/cxyqxuz
>
> Something has to be done with the documentation for Phobos functions that involve ranges and templates.

Instead of rewriting all the doc I suggest another approach: someone writes a reference article or special phobos page such as

"Understanding D ranges, their constraints and the error messages",

that could teach how to interpret and undertstand the error messages and the doc. The problem is that new comers really have to learn std.range primitives as well as a big part of std.traits. The article would cover the most encountered functions from this two modules:

- isInputRange
- isForwardRange
- ElementType
- isNarrowString
- ...

Because clearly when you know these functions you understand the constraints. That's the key.

~~~~~~~~~~~~~~~~~~~

Another idea would be to put each condition of a constraint on a new line (I speak about DDoc formating):

bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
if (isInputRange!Range1
    && isInputRange!Range2
    && !isInfinite!Range1
    && !isInfinite!Range2);


~~~~~~~~~~~~~~~~~~~

In the same vein, but a bit better, put the constraint in a separate ddoc section, for example "constraint".

On Monday, 14 December 2015 at 19:50:47 UTC, H. S. Teoh wrote:

>> There is nothing I can do about this. Who makes these decisions? Can we change it to something useful?
>
> What would constitute "useful" to you?

Removing what is there and leaving it blank would be better. At least new D programmers wouldn't run away.

>> Also, I think the documentation for functions involving ranges needs more "for dummies" examples. Too many of those functions leave the reader not having a clue what to do after calling the function. I know how that can be fixed.
>
> Let's see the PR's, then.

You have and you will, as it fits my schedule. Hopefully I'm not the only one or it will take a long time.

On Monday, 14 December 2015 at 19:38:26 UTC, Jack Stouffer wrote:
> If you're trying to use Phobos without knowing what template constraints and ranges are, you're going to have a bad time.
>
> I'm not sure what else to say here.

No, stuff like the following is indefensible. The current documentation is nearly opaque to newcomers and *needs* to be fixed.

bool isPermutation(AllocateGC allocate_gc, Range1, Range2)(Range1 r1, Range2 r2) if (allocate_gc == AllocateGC.yes && isForwardRange!Range1 && isForwardRange!Range2 && !isInfinite!Range1 && !isInfinite!Range2);




Compare that with the DDOX output, which is at least a little bit more readable (but also leaves a lot of room for improvement).

bool isPermutation(std.typecons.Flag!("allocateGC").Flag allocate_gc, Range1, Range2)(
  Range1 r1,
  Range2 r2
)
if (allocate_gc == AllocateGC.yes && isForwardRange!Range1 && isForwardRange!Range2 && !isInfinite!Range1 && !isInfinite!Range2);