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

I agree the phobos doc need work. There are whole modules that are
undocumented from what I can tell (eg std.math2, std.loader). Even the doc
for Object isn't accurate (it's missing opEquals) Also the phobos modules
themselves need work. The topic flares up every now and then but I guess
with the summer vacations people haven't been posting alot about it.
Personally I'm still not sure what the scope is for changing phobos or
unifying it more. Right now files have lots of different copyright and/or
licenses and coding styles and it's not easy figuring out how the thing fits
together. A fairly old post about process
http://www.digitalmars.com/d/archives/digitalmars/D/20303.html
seems to indicate posting changes to send to Walter and then just emailing
him the changes would work. That would probably work fine for individual
modules but structural or cross-module changes are an unknown. I don't know
who should fix up the doc.

In article <op.svl34ciq58xlqs@localhost.localdomain>, =?utf-8?B?RGF3aWQgQ2nEmcW8YXJraWV3aWN6?= says...
>
>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.
>

Just wanted to add that by "not realy stable", I think Dawid meant there are still some changes being made to the language and libs., but those are primarily additions. This is actually a good thing IMO - Walter has been continuously implementing improvements along with the bug fix releases.

Both compilers and Phobos I think are reasonably stable (a lot of libraries and some good size applications developed with them), and the last major change where people had to do a wide-spread search-and-replace through their code was - I think - a consolidation of some io modules, and that happened a few months ago already, and only if they were using stream io.

>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

prefetch wrote:

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

I agree that the docs are in bad shape, but I don't see that as an issue right now. They are enough to get started and point you in the right direction on most things. Obviously, the final release of the compiler and spec would be harmed if the docs are left in their current state, but I don't see that happening. I'm confident the docs will go through a complete overhaul before 1.0 is out the door. In the meantime, we work with what we have.

> the most recent language i evaluated was python, and it's got
> fantastic documentation.  kudos to python!!

I should hope so, considering it's been in a released state for several years! I don't think user documentation is ever a high priority on a project until the latter stages, and for a one man show like Digital Mars I wouldn't expect it to be. And considering how fluid the spec and features were for a while, I'm thankful to have any docs at all!

You're right. I've reorganized the phobos doc a bit, at least it should be easier to navigate now. Also, please use the [Comments] link whereever you need it! -Walter

www.digitalmars.com/d/phobos.html

In article <de8m9o$25pl$1@digitaldaemon.com>, Walter says...
>
>You're right. I've reorganized the phobos doc a bit, at least it should be easier to navigate now. Also, please use the [Comments] link whereever you need it! -Walter

Wow, nice job! The frameless navigation is a _great_ improvement.

Hopefully the rest of the D spec will follow? ;)

Cheers,
--AJG.