On Tuesday, 15 December 2015 at 08:08:10 UTC, landaire wrote:
>
> I started exploring D a couple of months ago and I was the original poster in the reddit thread who sparked this discussion. While on the topic of documentation I wanted to quickly put in my thoughts about what frustrated me with the documentation:
>
> [...]

Dang, no responses to this?

On Tuesday, 15 December 2015 at 08:08:10 UTC, landaire wrote:
> - Runnable examples would be *so* useful! They're present on the homepage, why can't the examples provided in the inline docs be runnable as well?
[snip]
> Here's an imgur album I created to show some suggestions for function signatures: http://imgur.com/a/njHKI

These are all great suggestions. Please add them to the bug report already mentioned in this thread.

> - Dead links = compile error when compiling documentation? This was annoying when trying to find out more about OutputRanges. The only resource I found was on the std.range page in the tee definition, and the link was dead: http://dlang.org/phobos/std_range.html#.tee

I think CyberShadow was working on this. It is a problem though that needs fixing.

> - Link to where the code is implemented in Phobos at the time of compilation. e.g. clicking the actual name of "find" could link me here: https://github.com/D-Programming-Language/phobos/blob/b6a61d9e719a9d680936db44b98fbb5dd28bf6b1/std/algorithm/searching.d#L1498. More than once I found that reading the code was more useful than reading the documentation.

Also a good idea.

On Tuesday, 15 December 2015 at 08:08:10 UTC, landaire wrote:
> On Tuesday, 15 December 2015 at 02:39:16 UTC, Steven Schveighoffer wrote:
>> [...]
>
> I started exploring D a couple of months ago and I was the original poster in the reddit thread who sparked this discussion. While on the topic of documentation I wanted to quickly put in my thoughts about what frustrated me with the documentation:
>
> [...]

I think these are some great suggestions, particularly the 3rd example where the function signature is emphasized.

On Tue, 15 Dec 2015 16:10:49 +0000, wobbles wrote:

> I think some whitespace and some color-coding will go a long way to making the function signatures better.

We'll want to make sure we test with color-blindness filters, of course.

On Tue, 15 Dec 2015 15:55:31 +0000, ZombineDev wrote:

> On Tuesday, 15 December 2015 at 14:03:50 UTC, rumbu wrote:
>>
>> We are talking about a better documentation, not about the C# vs D performance, we already know the winner. Since C# is an OOP-only language, there is only one way to do reflection - using OOP, (voluntarily ignoring the fact that NGen will reduce this call to a simple memory read in case of arrays).
>>
>> Your affirmation:
>>
>>> the docs don't even bother to mention that it is almost always O(n), because non of the Enumerable extention methods preserve the underlying ICollection interace
>>
>> was false and you don't need to look to the source code to find out, the Remarks section is self-explanatory:
>>
>> "If the type of source implements ICollection<T>, that implementation is used to obtain the count of elements. Otherwise, this method determines the count."
> 
> Sorry, I do not know how to make this clear:
> 
> NONE OF THE System.Linq.Enumerable EXTENSION METHODS PRESERVE THE STRUCTURE (THE INTERFACES THEY IMPLEMENT) OF THE SEQUENCE THEY ARE OPERATING ON. DON'T BELIEVE THAT NGEN WILL AUTOMAGICALLY MAKE YOUR CODE FASTER. IT WILL NOT. UNICORNS DO NOT EXISTS. AT LEAST THEY DO NOT IN .NET OR JAVA. DO NOT BLINDLY BELIEVE. TEST!

    'I said it very loud and clear:
    I went and shouted in his ear.'

Humpty Dumpty raised his voice almost to a scream as he repeated this verse, and Alice thought with a shudder, 'I wouldn't have been the messenger for anything!'

    'But he was very stiff and proud:
    He said, "You needn't shout so loud!"

    And he was very proud and stiff:
    He said 'I'd go and wake them, if --"'

> See for yourself: https://ideone.com/L5FatQ
> 
> This what I got on my machine:
> 00:00:00.0011011 for N = 1 -> 1, List<int>.Select(..).Count()

You have observed that System.Linq hasn't fully propagated metadata about collections through operations where it could and where D's equivalents do.

You are blaming this on object oriented programming. It is easy to support a handful of extra operations (like O(1) collection length) on all System.Linq types with object oriented code. It gets harder as you try to support more operations, but there are probably only a few you need to worry about.

It is more convenient to use templates and static if, especially as the number of operations grows. But it's certainly possible to do in OOP.

You are also explicitly opting out of adaptive optimizations by using ngen. That's a much smaller effect, of course. ngen is better for fast startup and to guarantee that the runtime won't try to re-JIT your code when you're executing code that can't stand for such a pause.

>> - You don't need to understand computer science terms to find out what a function does;
> 
> A major disadvantage, if you ask me :D

"Come learn D, it's actively hostile toward novices!" ...perhaps a different marketing campaign would work better.

>> There is no indication what happens if the range contains more than
>> size_t.max elements:
>> - integer overflow;
> 
> Practically impossible on 64-bit and unlikely that someone will use walkLength with files on 32-bit. It's called *walk*Length for a reason.

Not all ranges are backed by data in memory or on disk. I could create a range over the time from the Big Bang to today in 10-femtosecond intervals, for instance. Granted, it would be silly for me to call walkLength on that.

Also, there's no indication what the return type is. It could be a short for all I know. Maybe the writer accidentally wrote 'auto count = 0;' instead of explicitly using size_t, in which case by three billion entry range will report that its walk length is negative.

I read the source code and know it's using size_t (and should perhaps just be ulong). But it's not documented anywhere.

On 12/15/2015 11:24 AM, landaire wrote:
> On Tuesday, 15 December 2015 at 08:08:10 UTC, landaire wrote:
>>
>> I started exploring D a couple of months ago and I was the original
>> poster in the reddit thread who sparked this discussion. While on the
>> topic of documentation I wanted to quickly put in my thoughts about
>> what frustrated me with the documentation:
>>
>> [...]
>
> Dang, no responses to this?

I started a long answer and then my Ubuntu froze. Will redo it... -- Andrei

On Tuesday, 15 December 2015 at 08:08:10 UTC, landaire wrote:

> Here's an imgur album I created to show some suggestions for function signatures: http://imgur.com/a/njHKI

I really like the one titled "Put more emphasis on the function signature". With proper spacing and reducing the noise caused by the constraints, it's actually readable.

On Tuesday, 15 December 2015 at 14:41:34 UTC, Adam D. Ruppe wrote:
> Just something I want to throw out as a reminder, a part of the ranges chapter of my book is public on the packt website:
>
> https://www.packtpub.com/books/content/ranges
>
> and a longer things from Mike Parker's book is too:
>
> https://www.packtpub.com/books/content/understanding-ranges
>
> a lot of us have talked about ranges, it all ought to be nicely referenced in the docs as much as we can.

Are those links permanent, so that we don't have to worry about broken links in the future?

On 12/15/2015 03:08 AM, landaire wrote:
> - Runnable examples would be *so* useful! They're present on the
> homepage, why can't the examples provided in the inline docs be runnable
> as well?

The runnable examples were first provided by nazriel (he's to be found around here and on IRC). He also started to expand runnable examples, but then got busy with other things. This would be a great project.

> - Linking types, functions, etc. in the function signatures would be
> great *if possible*. e.g.:
>
> bool startsWith(alias pred = "a == b", R1, R2)(R1 doesThisStart, R2
> withThis) if (isInputRange!R1 && isInputRange!R2 &&
> is(typeof(binaryFun!pred(doesThisStart.front, withThis.front)) : bool));
>
> Make bool, isInputRange, typeof, and binaryFun all links to their
> definitions. If I don't know what "isInputRange" does, do I really have
> to go spend more time to figure out where it lives?

This is a good idea that would require changes to ddoc.

> - Add another line break between overloaded methods! Having no
> separation between lines makes things very difficult to sort out

This is easy. You need to figure out what separator ddoc introduces between overloads. "make verbatim" in dlang.org was conceived exactly for that kind of stuff.

> Here's an imgur album I created to show some suggestions for function
> signatures: http://imgur.com/a/njHKI
>
> - Dead links = compile error when compiling documentation? This was
> annoying when trying to find out more about OutputRanges. The only
> resource I found was on the std.range page in the tee definition, and
> the link was dead: http://dlang.org/phobos/std_range.html#.tee

There are a number of dead link detectors, online and offline. We just haven't integrated any although Vladimir was looking into it at a point. This would be a fine project to get into, too.

> - Link to where the code is implemented in Phobos at the time of
> compilation. e.g. clicking the actual name of "find" could link me here:
> https://github.com/D-Programming-Language/phobos/blob/b6a61d9e719a9d680936db44b98fbb5dd28bf6b1/std/algorithm/searching.d#L1498.
> More than once I found that reading the code was more useful than
> reading the documentation.

We already have a SOURCE macro for that I think.

> I find that I learn best by reading documentation. Go's documentation is
> phenomenal and it's very easy to follow and understand (yes, I realize
> this is kind of comparing apples to oranges in terms of complexity). I
> don't want to have to have to read documentation on understanding the
> documentation.
>
> I'm currently on winter break from university and would love to help
> contribute some of these changes if people think they're useful as well.

I suggest you start with the simpler stuff, such as better formatting of overloads. That'll allow you to find your way around the doc build and see what the macros are and what they generate. It'd be great if you got the verbatim build going, it's seldom used but very helpful. Make some css changes while at it. Then move into more involved stuff.

Overall doc building is a territory where there's plenty of easy-hanging fruit, and the satisfaction is high. I have a great time whenever I get into it, just less often than I wish.


Andrei

On Tuesday, 15 December 2015 at 19:51:37 UTC, Andrei Alexandrescu wrote:
> I suggest you start with the simpler stuff, such as better formatting of overloads. That'll allow you to find your way around the doc build and see what the macros are and what they generate. It'd be great if you got the verbatim build going, it's seldom used but very helpful. Make some css changes while at it. Then move into more involved stuff.
>
> Overall doc building is a territory where there's plenty of easy-hanging fruit, and the satisfaction is high. I have a great time whenever I get into it, just less often than I wish.
>
>
> Andrei

Thanks for the feedback Andrei and everyone else. I'll start stabbing at things this weekend. Setting up the site in a vagrant environment shouldn't be too difficult. I don't want to shoot for too much but I'll also see about setting up a staging environment on my server to display the changes on.