www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Frustratingly D

reply Nicholas <nicholas.hansYouSpammingMe gmail.com> writes:
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.
Feb 22 2011
next sibling parent reply bearophile <bearophileHUGS lycos.com> writes:
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
Feb 22 2011
parent spir <denis.spir gmail.com> writes:
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
Feb 22 2011
prev sibling next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
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.
Feb 22 2011
prev sibling next sibling parent reply Jesse Phillips <jessekphillips+D gmail.com> writes:
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.
Feb 22 2011
parent reply Nicholas <nicholas.hansDontSpamMeBro gmail.com> writes:
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
Feb 23 2011
next sibling parent Daniel Gibson <metalcaedes gmail.com> writes:
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
Feb 23 2011
prev sibling next sibling parent Trass3r <un known.com> writes:
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.
Feb 23 2011
prev sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
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
Feb 23 2011
prev sibling parent Jesse Phillips <jessekphillips+D gmail.com> writes:
Nicholas Wrote:


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


The problem is those are things that specifically interest you, but everyone
has something they'd want to be the first thing to hear about.


 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.


Right, but scattered sources also mean more places to stumble across D.

I'm not sure if the main site needs extensive amounts of tutorials. It should
definitely reference where community tutorials can be found. Wiki4D also
doesn't house a lot of content and only refers to other locations.

I made some suggestions to have some more links going to specific Wiki4D pages.
There is a link for every Phobos module, but I think Wiki4D is a horrible place
for discussion.
Feb 23 2011