View mode: basic / threaded / horizontal-split · Log in · Help
September 29, 2012
Getting started with D - Phobos documentation sucks
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?
September 29, 2012
Re: Getting started with D - Phobos documentation sucks
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
September 29, 2012
Re: Getting started with D - Phobos documentation sucks
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.
September 29, 2012
Re: Getting started with D - Phobos documentation sucks
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.
September 29, 2012
Re: Getting started with D - Phobos documentation sucks
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.
September 29, 2012
Re: Getting started with D - Phobos documentation sucks
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().
September 29, 2012
Re: Getting started with D - Phobos documentation sucks
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.
September 29, 2012
Re: Getting started with D - Phobos documentation sucks
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)
September 29, 2012
Re: Getting started with D - Phobos documentation sucks
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
September 29, 2012
Re: Getting started with D - Phobos documentation sucks
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.
« First   ‹ Prev
1 2 3 4 5
Top | Discussion index | About this forum | D home