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