For about 2 months I've been sinking into D.  I really enjoy it and I want to love it but I'm constantly annoyed by the presentation of information. Several times I've built things that were in the standard library because the website is poorly organized and doesn't contain sufficient examples.  The online documentation has a bunch of cluttered links at the top, no hierarchy, no dates, and it reads like a list of nutritional facts.  My only recourse is to grep like mad through the source files and find the actual implementations and unit tests.  It's bad enough that there are no modern IDEs so that it already feels like it's 1994 again.


Here are some particular annoyances that need further
clarification/examples/comparisons to their siblings:
std.concurrency vs std.thread
std.date vs. std.datetime
std.regex vs. std.regexp
std.file vs. std.cstream and there's quite a bit of crossover with std.stream
std.xml: unfortunately one of the few modules that doesn't have a sibling.


And Andrei, you're a great programmer but your example-giving skills could be
strengthened.  From std.array to std.range to std.random, all your examples
are equivalent to this:
auto a = [ 1, 2, 3 ];
assert( ... );

auto a = obj.method( "guess what i'm returning" );


I like auto.  I use it sometimes.  But it's not always clear what's taking place in the examples.  I believe you should exclude auto from all examples except when explaining auto.


I see great potential in D and enjoy it.  I would like to see the documentation improve and the standard library cleaned up.  I'm sure there are a million reasons why it evolved into what it has so far but for a new user those reasons are unimportant.  Put them in the "History of D".


No hard feelings.  Just some thoughts.

Nicholas:

> auto a = obj.method( "guess what i'm returning" );
> 
> 
> I like auto.  I use it sometimes.  But it's not always clear what's taking place in the examples.  I believe you should exclude auto from all examples except when explaining auto.

Unfortunately this happens in normal code too, not just in examples. auto is practically necessary when you use lazy iterables, because their type is usually too much complex to write, but in the other cases it obfuscates the code a little.

In dynamic languages it's like using auto everywhere. But programmers of dynamic languages survive because they program in a way that makes the implicit types a bit more easy to guess :-) D code that uses "auto" a lot needs to be written in the same way, with very well chosen variable names, etc.

Bye,
bearophile

Nicholas wrote:
> The online documentation has a bunch of cluttered links at the top, no hierarchy, no dates, and it reads like a list of nutritional facts.

Andrei and I are both working on improving the situation. I forgot where Andrei's playground is, but I copied a lot of his ideas on my site too. Here's one page:

Andrei's cheat sheet idea is visible here: http://arsdnet.net/d-web-site/std_stdio.html

And my first draft at hierarchy: http://arsdnet.net/d-web-site/std_algorithm.html

(the cheat sheet is significantly better IMO)


Once you get the know the library, my other project, a documentation name search might be useful to you: http://dpldocs.info/

You can jump to a module or function by putting it on the url:

http://dpldocs.info/std.stdio.File

And it does a quick keyword search too if you don't give a full name. Note it lags a bit on Phobos versions because I only update it every other release.

On 02/23/2011 01:15 AM, bearophile wrote:
> Nicholas:
>
>> auto a = obj.method( "guess what i'm returning" );
>>
>>
>> I like auto.  I use it sometimes.  But it's not always clear what's taking
>> place in the examples.  I believe you should exclude auto from all examples
>> except when explaining auto.
>
> Unfortunately this happens in normal code too, not just in examples. auto is practically necessary when you use lazy iterables, because their type is usually too much complex to write, but in the other cases it obfuscates the code a little.
>
> In dynamic languages it's like using auto everywhere. But programmers of dynamic languages survive because they program in a way that makes the implicit types a bit more easy to guess :-) D code that uses "auto" a lot needs to be written in the same way, with very well chosen variable names, etc.

???

unittest {
    auto a = [1,2,3];
    auto x = map!((i) { return i+1; })(a);
    writeln(typeid(x));
    // --> test.__unittest3.Map!(__dgliteral1,int[]).Map
}

There's no such type in any dynamic language I know of ;-)

Denis
-- 
_________________
vita es estrany
spir.wikidot.com

Things are moving in the direction you want, but it is slow. Wiki4D is a good place to put tutorials and read them.

http://www.prowiki.org/wiki4d/wiki.cgi?FrontPage

Here are some quick comments:

Nicholas Wrote:

> Here are some particular annoyances that need further clarification/examples/comparisons to their siblings: std.concurrency vs std.thread

MPI vs Threads

> std.date vs. std.datetime

std.date is deprecated.

> std.regex vs. std.regexp (scheduled for)

std.regexp is deprecated. (scheduled for)

> std.file vs. std.cstream and there's quite a bit of crossover with std.stream std.xml: unfortunately one of the few modules that doesn't have a sibling.

std.jason? Actually std.xml is probably gone in the next release, too many bugs.

> And Andrei, you're a great programmer but your example-giving skills could be
> strengthened.  From std.array to std.range to std.random, all your examples
> are equivalent to this:
> auto a = [ 1, 2, 3 ];
> assert( ... );

I think this is a good way to show the input and output. Unlike other examples where the program must be run because it uses print statements.

> auto a = obj.method( "guess what i'm returning" );

That is what the documentation is for. Since the example is in the documentation that shouldn't be hard to find.

I don't know about other people but documentation for the library is one of the things I keep open/available when I'm using the library. I just hope that the return type for an 'auto function' is printed in the documentation instead of just 'auto'

> I like auto.  I use it sometimes.  But it's not always clear what's taking place in the examples.  I believe you should exclude auto from all examples except when explaining auto.

A lot of Phobos returns templated structs, these things can get quite scary to a new user. There is also an aspect where being concerned about the type is unimportant. And good documentation will make it easier to find the information you are really after.


> I see great potential in D and enjoy it.  I would like to see the documentation improve and the standard library cleaned up.  I'm sure there are a million reasons why it evolved into what it has so far but for a new user those reasons are unimportant.  Put them in the "History of D".

It is much better than it used to be. More work is being done on these issues though. Now we just need them finished a little more.

Jesse,

Thanks for clarifying some of those.  Something like that, but with more detail, should go right on the front page.


That's a shame about std.xml being lost completely.  I thought maybe someone was working on it and might have an updated version.  std.json would probably work okay for small files.  Unfortunately, neither std.xml or std.json is geared for handling time/memory tradeoffs where file IO is concerned.  They just assume everything is fully loaded into memory.


I keep the library open for the most part but find that grep is a more effective tool for examples, especially since other Phobos developers build off the tools that are already in the library (as well as seeing the unit tests).  I didn't mean to pick on just Andrei either, the examples in his book are better.


It would be nice to have a single location for documentation rather than the scattered sources.  The reply I got from Adam Ruppe shows a foot in the right direction.  I understand it's a work in progress but D isn't necessarily new and I think there's a sense of what's expected from the official documentation for new users.


On top of that the D community seems active and exciting but also scattered and unorganized.  There are many open projects that compete instead of complement each other.  For example, there's Visual D, Entice (I find myself using both), D-IDE, and Poseidon to name a few.  Each project with limited functionality but each one has parts that would benefit the other.  This, of course, in addition to the old Tango/Phobos situation.  A lot of great energy thinly spread across the D domain.


I'm not saying these things just to nitpick either.  I'd like to get involved.  My D skills aren't up to snuff yet but even with organization, I'd be glad to help out.  I just don't know where to start and find myself getting tripped up along the way.


Nicholas

Am 23.02.2011 17:47, schrieb Nicholas:
> Jesse,
>
> Thanks for clarifying some of those.  Something like that, but with more detail,
> should go right on the front page.
>
>
> That's a shame about std.xml being lost completely.  I thought maybe someone was
> working on it and might have an updated version.  std.json would probably work
> okay for small files.  Unfortunately, neither std.xml or std.json is geared for
> handling time/memory tradeoffs where file IO is concerned.  They just assume
> everything is fully loaded into memory.
>

You could use http://dsource.org/projects/xmlp instead of std.xml.
Also a replacement for std.xml is in the works.

Cheers,
- Daniel

Nicholas Wrote:
> This, of course, in addition to the old Tango/Phobos situation.  A lot of great energy thinly spread across the D domain.

Yep, at least there's 1 or 2 attempts to port Tango to D2 or rather get it to compile with dmd2. Hopefully these don't peter out.

On Wednesday, February 23, 2011 08:47:31 Nicholas wrote:
> Jesse,
> 
> Thanks for clarifying some of those.  Something like that, but with more detail, should go right on the front page.
> 
> 
> That's a shame about std.xml being lost completely.  I thought maybe someone was working on it and might have an updated version.  std.json would probably work okay for small files.  Unfortunately, neither std.xml or std.json is geared for handling time/memory tradeoffs where file IO is concerned.  They just assume everything is fully loaded into memory.

Work is being done on at least one potential replacement for std.xml (as in total replacement, no a fixed version of the current implementation). We _will_ have a std.xml in the long run. The problem is that the current implementation is unacceptably bad, and we decided that we're going to remove it soon so that people don't keep trying to use it. We'll definitely be replacing it though. I think that someone is working std.json too (though I don't remember who), but I don't know what it's current state is or whether it's a replacement or just an improvement of what's currently there.

The current state of Phobos _is_ improving - both the code and the documentation - but there's plenty more to do, and it takes time.

- Jonathan M Davis