On Monday, 14 December 2015 at 20:08:20 UTC, Jack Stouffer wrote:
> You're not really comparing apples to apples here

In fact I'm not, but the main focus here was about the simplicity of the layout used on the C# doc. You can see others examples there easily including templates and generics interface.

>> 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.

Yes they can and this isn't hard to understand, but remember there are newcomers every day. I think it should be simpler like MSDN does:

Syntax:
    bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
Parameters:
    Type r1, r2 : Input range.
    Both r1, r2 : needs to be finite.

I think it's better than currently. But this is my thoughts over the problems that my friends encounter with D's docs.

Ron.

On Monday, 14 December 2015 at 20:25:17 UTC, bachmeier wrote:
> 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 think you raise valid concerns both with respect to improving the presentation of the documentation and the examples.

Function signatures are clearly important for the documentation. It's just a matter of presenting the information so that it is clear to someone new, but also so that an expert can find the information they need easily as well.

On Monday, 14 December 2015 at 20:25:17 UTC, bachmeier wrote:
> 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.

C is doomed if you have to understand pointers to use the standard library
C++ is doomed if you have to understand templates and iterators to use the STL
Rust is doomed if you have to understand borrowing to use the standard library
Haskell is doomed if you have to understand functional programming to use the standard library
Java is doomed if you have to understand OOP to use the standard library

All this is to say that there is a necessary level of overhead to use any language. You can't expect to jump into most languages without learning new concepts and changing the way you look at things. The only languages I know of that doesn't require you to change the way you think are scripting languages and Go, and that's bitting the latter in the ass.

Also, most of Phobos doesn't use ranges.

> 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.

You don't: array1.length == array2.length. isSameLength is designed for comparing input ranges but optimizes down to length checks if either range has a defined length. If you are dealing with strings or arrays you don't need this function at all.

>> 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 disagree. The Phobos documentation is not a tutorial and shouldn't act like it. If there are concepts that aren't obvious to someone who knows D, for example the fact that you can use lambdas in place of string predicates in a lot of Phobos functions, then fine, document away. But the function signatures require only knowledge that you would gain by reading Ali's book, which is called the official tutorial for a reason.

> The only criticism I'd have is that there needs to be a link to intro material on ranges.

There is, look at the top of this page: http://dlang.org/phobos/std_algorithm.html

One thing we definitely need to do is make the template constraints rendered better in documentation, and also allow user content in them. We've discussed this several times but no clear path emerged so far. Maybe a strong champion would come forward?

I'm thinking along the lines of:

* Change ddoc to output the constraint separately under a DDOC_CONSTRAINT macro.

* Allow ddoc comments inside macros:

bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
if (isInputRange!Range1 && isInputRange!Range2 && !isInfinite!Range1 && !isInfinite!Range2
/**
`Range1` and `Range2` must be both non-infinite input ranges.
*/
);

then format that comment as a DDOC_CONSTRAINT_USERTEXT or something.

These would be good steps to take.


Andrei

On 12/14/2015 12:53 PM, Andrei Alexandrescu wrote:

> I'm thinking along the lines of:
>
> * Change ddoc to output the constraint separately under a
> DDOC_CONSTRAINT macro.
>
> * Allow ddoc comments inside macros:
>
> bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
> if (isInputRange!Range1 && isInputRange!Range2 && !isInfinite!Range1 &&
> !isInfinite!Range2
> /**
> `Range1` and `Range2` must be both non-infinite input ranges.
> */
> );

Can we simplify it even more? Just this much:

    bool isSameLength(Range1 r1, Range2 r2)

Then some text that follows:

    Range1 is a template parameter:
        default value: blah

    Range2 is a template parameter

    Template constraints:

        if (isInputRange!Range1 &&
            isInputRange!Range2 &&
            !isInfinite!Range1 &&
            !isInfinite!Range2)

There can be a hover-over or a click to see the full signature.

Ali

I think it's really just a design issue--I agree that you can't ignore information about ranges and constraints altogether. But the documentation doesn't reflect any hierarchy of the importance of information. In the example:

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

The most important thing to know is that it accepts two ranges and outputs a bool. The template constraints are secondary (and for the most part obvious), but they're in the same visual hierarchy (line, font size, weight, etc.) as the basic signature. So it's just extremely noisy.

I think even just putting template constraints in a subordinate section of the documentation would help a lot. Beginners can just look at the signature and be good to go 99% of the time; others can look under the hood easily.

The other noisy aspect is the type repetition of Range1 and Range2. I don't know what to do about that---maybe a terser convention for range type params would help. (Typically type parameters are single letters for this reason in many languages.) I notice some functions use R1 and R2 instead of Range1 and Range2.


On Monday, 14 December 2015 at 19:38:26 UTC, Jack Stouffer 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:
>>
>> 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 Monday, 14 December 2015 at 20:53:53 UTC, Andrei Alexandrescu wrote:
> One thing we definitely need to do is make the template constraints rendered better in documentation, and also allow user content in them. We've discussed this several times but no clear path emerged so far. Maybe a strong champion would come forward?
>
> I'm thinking along the lines of:
>
> * Change ddoc to output the constraint separately under a DDOC_CONSTRAINT macro.
>
> * Allow ddoc comments inside macros:
>
> bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
> if (isInputRange!Range1 && isInputRange!Range2 && !isInfinite!Range1 && !isInfinite!Range2
> /**
> `Range1` and `Range2` must be both non-infinite input ranges.
> */
> );
>
> then format that comment as a DDOC_CONSTRAINT_USERTEXT or something.
>
> These would be good steps to take.
>
>
> Andrei

I'm not particularly familiar with DDOC. Is there some documentation on creating new macros?

On Monday, 14 December 2015 at 21:02:10 UTC, Meta wrote:
> I'm not particularly familiar with DDOC. Is there some documentation on creating new macros?

This text is output by the compiler, so it would be a matter of making the compiler output it with more information.

It used to be called doc.c.... I'm sure it is doc.d now, the code is fairly simple and just builds strings from the code objects.

On Mon, Dec 14, 2015 at 08:53:53PM +0000, Andrei Alexandrescu via Digitalmars-d wrote:
> One thing we definitely need to do is make the template constraints rendered better in documentation, and also allow user content in them. We've discussed this several times but no clear path emerged so far. Maybe a strong champion would come forward?
> 
> I'm thinking along the lines of:
[...]

This has already been filed since a long time ago:

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

It just needs somebody to actually implement it. AFAICT it shouldn't be too hard, as ddoc.d already has most of the necessary machinery for it.


T

-- 
First Rule of History: History doesn't repeat itself -- historians merely repeat each other.

On Monday, 14 December 2015 at 21:02:05 UTC, Ali Çehreli wrote:
> > bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
> > if (isInputRange!Range1 && isInputRange!Range2 &&
> !isInfinite!Range1 &&
> > !isInfinite!Range2
> Can we simplify it even more? Just this much:


You know, I think it is a lot more readable already just putting in some whitespace.

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


Maybe we could run the outputted code through a D source formatter?!


Heck, the compiler error messages might be easier to read if it formatted with liberal whitespace too, though there is the tiny concern there that other tools might expect one error per line... but i say meh to that, we already break that rule.