Getting started with D - Phobos documentation sucks

[Tommi]

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