Hi guys.

I was browsing the book "Programming in D" by Ali Çehreli. It was pretty much clear, and then I stumbled upon this on page 89:
> 20.9 Exercises
> 1. Browse the documentations of the std.string, std.array, std.algorithm, and std.range modules.

OK, let's open the D website and browse the documentation of std.string:
http://dlang.org/phobos/std_string.html

What do we see? A bunch of links that look like SEO tags of a spam website, followed by a mess of anything - structs, classes, functions, and what not.
Do you really think somebody who learns programming can understand anything here?

Compare this with, e.g., an msdn reference:

http://msdn.microsoft.com/en-us/library/windows/desktop/ms684852(v=vs.85).aspx
A clear division of enums, functions, macros, structs, ...

http://msdn.microsoft.com/en-us/library/windows/desktop/ms684847(v=vs.85).aspx
The functions are divided by usage, with a short explanation next to each function.

I think documentation is really important, and something has to be done about it. How can a newcomer get started with D when he doesn't have a readable documentation of Phobos?

On 09/29/2012 05:30 PM, Mr. Anonymous wrote:
> Hi guys.
>
> I was browsing the book "Programming in D" by Ali Çehreli. It was pretty
> much clear, and then I stumbled upon this on page 89:
>> 20.9 Exercises
>> 1. Browse the documentations of the std.string, std.array,
>> std.algorithm, and std.range modules.
>
> OK, let's open the D website and browse the documentation of std.string:
> http://dlang.org/phobos/std_string.html
>
> What do we see? A bunch of links that look like SEO tags of a spam
> website, followed by a mess of anything - structs, classes, functions,
> and what not.
> Do you really think somebody who learns programming can understand
> anything here?
>
> Compare this with, e.g., an msdn reference:
>
> http://msdn.microsoft.com/en-us/library/windows/desktop/ms684852(v=vs.85).aspx
>
> A clear division of enums, functions, macros, structs, ...
>
> http://msdn.microsoft.com/en-us/library/windows/desktop/ms684847(v=vs.85).aspx
>
> The functions are divided by usage, with a short explanation next to
> each function.
>
> I think documentation is really important, and something has to be done
> about it. How can a newcomer get started with D when he doesn't have a
> readable documentation of Phobos?

https://github.com/D-Programming-Language/d-programming-language.org

On Saturday, 29 September 2012 at 15:29:46 UTC, Mr. Anonymous wrote:
>> 1. Browse the documentations of the std.string, std.array, std.algorithm, and std.range modules.
>
> OK, let's open the D website and browse the documentation of std.string:
> http://dlang.org/phobos/std_string.html
>
> What do we see? A bunch of links that look like SEO tags of a spam website, followed by a mess of anything - structs, classes, functions, and what not.
>
> Compare this with, e.g., an msdn reference.....

Just remembering that most of the things that you see here is made by the community itself and the most important, it's free.

But well this is not an excuse, but anyway, Microsoft come doing this since long time ago and was not always as you see today.

On Saturday, 29 September 2012 at 15:46:36 UTC, MattCoder wrote:
> On Saturday, 29 September 2012 at 15:29:46 UTC, Mr. Anonymous wrote:
>>> 1. Browse the documentations of the std.string, std.array, std.algorithm, and std.range modules.
>>
>> OK, let's open the D website and browse the documentation of std.string:
>> http://dlang.org/phobos/std_string.html
>>
>> What do we see? A bunch of links that look like SEO tags of a spam website, followed by a mess of anything - structs, classes, functions, and what not.
>>
>> Compare this with, e.g., an msdn reference.....
>
> Just remembering that most of the things that you see here is made by the community itself and the most important, it's free.
>
> But well this is not an excuse, but anyway, Microsoft come doing this since long time ago and was not always as you see today.

Don't get me wrong, I'm not saying somebody owes me something.
I love D and appreciate the effort the community puts in it, otherwise I probably wouldn't write this post.

I'm just saying that, in my opinion, it's a high priority and it has to be addressed, so that newcomers would be able to get started with D.

I agree that the docs do suck.

A while ago I wrote a post-processor to make nicer tables:
http://arsdnet.net/d-web-site/std_datetime.html

And I'm doing my own D docs thing:
http://dpldocs.info/search/index
http://dpldocs.info/search/search

but it still sucks. I have been so busy with other stuff that these initatives have sat unfinished for a long time now.

On Saturday, 29 September 2012 at 15:29:46 UTC, Mr. Anonymous wrote:
> Hi guys.
>
> I was browsing the book "Programming in D" by Ali Çehreli. It was pretty much clear, and then I stumbled upon this on page 89:
>> 20.9 Exercises
>> 1. Browse the documentations of the std.string, std.array, std.algorithm, and std.range modules.
>
> OK, let's open the D website and browse the documentation of std.string:
> http://dlang.org/phobos/std_string.html
>
> What do we see? A bunch of links that look like SEO tags of a spam website, followed by a mess of anything - structs, classes, functions, and what not.
> Do you really think somebody who learns programming can understand anything here?
>
> Compare this with, e.g., an msdn reference:
>
> http://msdn.microsoft.com/en-us/library/windows/desktop/ms684852(v=vs.85).aspx
> A clear division of enums, functions, macros, structs, ...
>
> http://msdn.microsoft.com/en-us/library/windows/desktop/ms684847(v=vs.85).aspx
> The functions are divided by usage, with a short explanation next to each function.
>
> I think documentation is really important, and something has to be done about it. How can a newcomer get started with D when he doesn't have a readable documentation of Phobos?

You should really read first "The D Programming Language", or TDPL.

http://www.amazon.com/The-Programming-Language-Andrei-Alexandrescu/dp/0321635361

It's a great read, entertaining, informative. But notice that it doesn't cover everything, like template specializations (signature constraints are not the same thing).

Then read the strictly less entertaining language reference pages starting from:

http://dlang.org/lex.html

But notice that it doesn't cover everything either. For example it fails to mention that pointers to structs and classes are implicitly dereferenced when you use the member access operator with them, like ptrToStruct.callMethod().

On Saturday, 29 September 2012 at 15:53:17 UTC, Mr. Anonymous wrote:
> Don't get me wrong, I'm not saying somebody owes me something.
> I love D and appreciate the effort the community puts in it, otherwise I probably wouldn't write this post.
>
> I'm just saying that, in my opinion, it's a high priority and it has to be addressed, so that newcomers would be able to get started with D.

No problem fellow and be sure that I don't wanted to surpress your feelings, because I had the same feelings in the first time that I saw the doc's. But be sure the guys behind D knows that, but you know this is a hard job which demands some time.

And there's also the D Templates Tutorial at:

https://github.com/PhilippeSigaud/D-templates-tutorial/blob/master/dtemplates.pdf

(click "View Raw" on that page)

On 9/29/12 11:30 AM, Mr. Anonymous wrote:
> I think documentation is really important, and something has to be done
> about it. How can a newcomer get started with D when he doesn't have a
> readable documentation of Phobos?

Agree. It's high time we replace the silly litany of names at the top with a more sensible index (or, indeed, nothing at all!)

Andrei

On Saturday, 29 September 2012 at 16:34:41 UTC, Andrei Alexandrescu wrote:
> On 9/29/12 11:30 AM, Mr. Anonymous wrote:
>> I think documentation is really important, and something has to be done
>> about it. How can a newcomer get started with D when he doesn't have a
>> readable documentation of Phobos?
>
> Agree. It's high time we replace the silly litany of names at the top with a more sensible index (or, indeed, nothing at all!)
>
> Andrei

Well, they *are* better than nothing at all. Sure, in the best of worlds, we'd have lovingly hand written indexes and documentation, such as for std_algorithm. However, for those modules that *don't* have that hand written doc, it is better than nothing.

IMO, however, anything "nested" should NOT appear in the top index though, just the module's global functions and classes/structs. Anything else is clutter:

std_container is a blatant example of the clutter I'm talking about: There is everything in there from "front" to "opIndexOpAssign"...

Either that, or reorganized, as in:
Array (front, back, ... opIndexOpAssiggn)
Rather than the current free for all.