hi all,

i run a small engineering shop, and i've recently become very interested in D - mainly because it is so much like C, killer performance, but without the VM, and all sorts of the nice properties that so many recent language have (like memory management, etc.)

my background: software engineer, C/C++, some perl and python.

anyway, about 72 hours ago i started on my quest: "let's explore D and see if it's a good language to use for our next engineering project".

so far, i'm still on the fence.

my number one complaint is about the documentation.  it's HORRIBLE.  i mean, this language is almost 5 years old, and the basic runtime library doesn't even have a function index?  and it seems like i'm really lucky if i get a definition that includes expected return codes.

if this language is ever going to make an impact, it needs some work on the basic docs.  i think it's great that there are all these library projects going on, but can someone who knows this language well PLEASE take a few days and make the docs usable??

most of the last few days i've spent using the archaic search mechanism on the d site to figure things out, but that's awful because the google search include all the C++ docs/posts from digital mars - which is a mess to sort through. also, the web interface to this newsgroup has no search mechanism at all, so that's no help.

the most recent language i evaluated was python, and it's got fantastic documentation.  kudos to python!!  why can't D take a few days and bust out some *good* docs so people like me don't have to pound their heads against a wall to try and figure out if i'm too dumb to understand the std.thread docs, or if they are just broken - or when i have to grep for 'sleep' in the phobos 'source' to figure out if it's available since it isn't documented anywhere.  the list goes on.  i'm sure i'll figure all this our over the next 72-196 hours, but i think most people will probably give up and say "D is cool, but it's not ready for prime time yet" just because of the immaturity of the documentation.

here are two simple suggestions that wouldn't take a couple of experienced D developer too much time:

-an index of all functions, with links to docs (or at least source) -a 'complete' phobos reference w/ code snippets

holy crap, i think D is awesome (thank you bright et al!!), but is this asking
for too much?? WTF?

On Tue, 16 Aug 2005 18:36:19 +0200, prefetch <prefetch_member@pathlink.com> wrote:
> -an index of all functions, with links to docs (or at least source)
> -a 'complete' phobos reference w/ code snippets
>
> holy crap, i think D is awesome (thank you bright et al!!), but is this asking
> for too much?? WTF?

I think language is not realy stable right now, so nobody take care of writing realy great docs of things that may change soon.

D is awesome right now and will be awesone^2 when it'll reach it's next stage. And I bet it will have great docs even sooner. With help of this newsgroup, current docs and D sources you can get comfortable right now, but I know what you mean.

Just have to wait ... love don't come easy ... it's a game ... oh sorry ... wrong place.
-- 
Dawid Ciężarkiewicz

I agree , though I use PHP myself and love their documentation.


"prefetch" <prefetch_member@pathlink.com> wrote in message news:ddt4m3$h8q$1@digitaldaemon.com...
> hi all,
>
> i run a small engineering shop, and i've recently become very interested
in D -
> mainly because it is so much like C, killer performance, but without the
VM, and
> all sorts of the nice properties that so many recent language have (like
memory
> management, etc.)
>
> my background: software engineer, C/C++, some perl and python.
>
> anyway, about 72 hours ago i started on my quest: "let's explore D and see
if
> it's a good language to use for our next engineering project".
>
> so far, i'm still on the fence.
>
> my number one complaint is about the documentation.  it's HORRIBLE.  i
mean,
> this language is almost 5 years old, and the basic runtime library doesn't
even
> have a function index?  and it seems like i'm really lucky if i get a
definition
> that includes expected return codes.
>
> if this language is ever going to make an impact, it needs some work on
the
> basic docs.  i think it's great that there are all these library projects
going
> on, but can someone who knows this language well PLEASE take a few days
and make
> the docs usable??
>
> most of the last few days i've spent using the archaic search mechanism on
the d
> site to figure things out, but that's awful because the google search
include
> all the C++ docs/posts from digital mars - which is a mess to sort
through.
> also, the web interface to this newsgroup has no search mechanism at all,
so
> that's no help.
>
> the most recent language i evaluated was python, and it's got fantastic documentation.  kudos to python!!  why can't D take a few days and bust
out some
> *good* docs so people like me don't have to pound their heads against a
wall to
> try and figure out if i'm too dumb to understand the std.thread docs, or
if they
> are just broken - or when i have to grep for 'sleep' in the phobos
'source' to
> figure out if it's available since it isn't documented anywhere.  the list
goes
> on.  i'm sure i'll figure all this our over the next 72-196 hours, but i
think
> most people will probably give up and say "D is cool, but it's not ready
for
> prime time yet" just because of the immaturity of the documentation.
>
> here are two simple suggestions that wouldn't take a couple of experienced
D
> developer too much time:
>
> -an index of all functions, with links to docs (or at least source) -a 'complete' phobos reference w/ code snippets
>
> holy crap, i think D is awesome (thank you bright et al!!), but is this
asking
> for too much?? WTF?
>
>

Ugh , accidentaly hit send.

http://www.quit-clan.de/docwiki/view.php?pageid=1

There is a community based documentation site with a real nice layout.

Charlie


"Charles" <noone@nowhere.com> wrote in message news:ddta2m$o2j$1@digitaldaemon.com...
> I agree , though I use PHP myself and love their documentation.
>
>
> "prefetch" <prefetch_member@pathlink.com> wrote in message news:ddt4m3$h8q$1@digitaldaemon.com...
> > hi all,
> >
> > i run a small engineering shop, and i've recently become very interested
> in D -
> > mainly because it is so much like C, killer performance, but without the
> VM, and
> > all sorts of the nice properties that so many recent language have (like
> memory
> > management, etc.)
> >
> > my background: software engineer, C/C++, some perl and python.
> >
> > anyway, about 72 hours ago i started on my quest: "let's explore D and
see
> if
> > it's a good language to use for our next engineering project".
> >
> > so far, i'm still on the fence.
> >
> > my number one complaint is about the documentation.  it's HORRIBLE.  i
> mean,
> > this language is almost 5 years old, and the basic runtime library
doesn't
> even
> > have a function index?  and it seems like i'm really lucky if i get a
> definition
> > that includes expected return codes.
> >
> > if this language is ever going to make an impact, it needs some work on
> the
> > basic docs.  i think it's great that there are all these library
projects
> going
> > on, but can someone who knows this language well PLEASE take a few days
> and make
> > the docs usable??
> >
> > most of the last few days i've spent using the archaic search mechanism
on
> the d
> > site to figure things out, but that's awful because the google search
> include
> > all the C++ docs/posts from digital mars - which is a mess to sort
> through.
> > also, the web interface to this newsgroup has no search mechanism at
all,
> so
> > that's no help.
> >
> > the most recent language i evaluated was python, and it's got fantastic documentation.  kudos to python!!  why can't D take a few days and bust
> out some
> > *good* docs so people like me don't have to pound their heads against a
> wall to
> > try and figure out if i'm too dumb to understand the std.thread docs, or
> if they
> > are just broken - or when i have to grep for 'sleep' in the phobos
> 'source' to
> > figure out if it's available since it isn't documented anywhere.  the
list
> goes
> > on.  i'm sure i'll figure all this our over the next 72-196 hours, but i
> think
> > most people will probably give up and say "D is cool, but it's not ready
> for
> > prime time yet" just because of the immaturity of the documentation.
> >
> > here are two simple suggestions that wouldn't take a couple of
experienced
> D
> > developer too much time:
> >
> > -an index of all functions, with links to docs (or at least source) -a 'complete' phobos reference w/ code snippets
> >
> > holy crap, i think D is awesome (thank you bright et al!!), but is this
> asking
> > for too much?? WTF?
> >
> >
>
>

>http://www.quit-clan.de/docwiki/view.php?pageid=1
>There is a community based documentation site with a real nice layout.

Oh, wow. That is _nice_. Good find, man!
--AJG.

thanks charles, but there is simply no content there yet.

i think it's the responsibility of digital mars to at least make their bare bones documentation (phobos) complete and accurate.

hey, but i'm new here - maybe i'm out of line.  it just seems to me that if this sort of basic documentation is missing then the adoption for production use will be stunted.  then again, maybe D is on a 10 year plan and we're only half way there.

In article <ddta42$o54$1@digitaldaemon.com>, Charles says...
>
>Ugh , accidentaly hit send.
>
>http://www.quit-clan.de/docwiki/view.php?pageid=1
>
>There is a community based documentation site with a real nice layout.
>
>Charlie
>

Hi,

>I agree , though I use PHP myself and love their documentation.

Indeed. The PHP docs single-handedly turn the PHP language from:

Highly inconsistent use of functions, variables, parameters and naming in general, in addition to lots of irregularities between versions.

To:

Incredibly useful in spite of it.

IMHO if it weren't for the PHP docs, and their impressive mirroring and localization capabilities, PHP wouldn't have been nearly as succesful.

I particularly like the live commenting, because as we know, docs can be confusing, weird, or just plain wrong at times.

This is better than a full-blown wiki because it's a better balance of authoritative ("official") information with responsive feedback.

>> holy crap, i think D is awesome (thank you bright et al!!), but is this asking for too much?? WTF?

Nope, I don't think you are asking for too much.

D docs, get your act together.
--AJG.

prefetch wrote:

> 
> thanks charles, but there is simply no content there yet.
> 
> i think it's the responsibility of digital mars to at least make their bare bones documentation (phobos) complete and accurate.
> 
> hey, but i'm new here - maybe i'm out of line.  it just seems to me that
> if this sort of basic documentation is missing then the adoption for
> production use will
> be stunted.  then again, maybe D is on a 10 year plan and we're only half
> way there.

You're not really out-of-line, but Digital Mars is a one man show, implementing both a C++, D and ECMA-interpreter, among other things. Thus thourough documentation of an unstable API seems rather minor priority for the main man. Note that there are possible, communitydriven, replacements underway (www.dsource.org/projects/ares) that might be better documented if the community wants it.

Lars Ivar Igesund

>You're not really out-of-line, but Digital Mars is a one man show, implementing both a C++, D and ECMA-interpreter, among other things. Thus thourough documentation of an unstable API seems rather minor priority for the main man.

hm.  sounds like an alligator/swamp problem.  we can't drain the swamp because we're busy fighting off aligators, and there are too many aligators because we can't drain the swamp.

or maybe the leaky bucket metaphor works better here?

until you stop and properly document a basic runtime library, the support required to grow a strong stable language won't come.

again, this is just from an engineering management position - if the one-man show is too busy to make basic, accurate documentation, and the veterans in the community are unable to help, then i don't think this language will go mainstream.  just my $.02

at this point, i've started just reading the source instead of looking at the docs, which is a shame.  it takes away from some of the "D is written to be fast" because as we all know, execution time is only 1/2 of speed - the other is development time. :-/

> at this point, i've started just reading the source instead of looking at
the
> docs

You might try Elephant www.thecodebase.com .  If you create a phobos 'project' , there is a class browser that will show all modules / classes / functions etc.  Granted its a pain to add all those files by hand , the next version will have a 'Add Dir' option that will recreate the filesystem structure and add all the files to the project.

Charlie


"prefetch" <prefetch_member@pathlink.com> wrote in message news:ddtgdi$u6k$1@digitaldaemon.com...
> >You're not really out-of-line, but Digital Mars is a one man show, implementing both a C++, D and ECMA-interpreter, among other things. Thus thourough documentation of an unstable API seems rather minor priority
for
> >the main man.
>
> hm.  sounds like an alligator/swamp problem.  we can't drain the swamp
because
> we're busy fighting off aligators, and there are too many aligators
because we
> can't drain the swamp.
>
> or maybe the leaky bucket metaphor works better here?
>
> until you stop and properly document a basic runtime library, the support required to grow a strong stable language won't come.
>
> again, this is just from an engineering management position - if the
one-man
> show is too busy to make basic, accurate documentation, and the veterans
in the
> community are unable to help, then i don't think this language will go mainstream.  just my $.02
>
> at this point, i've started just reading the source instead of looking at
the
> docs, which is a shame.  it takes away from some of the "D is written to
be
> fast" because as we all know, execution time is only 1/2 of speed - the
other is
> development time. :-/
>
>