Download Reference Manual
The Developer's Library for D
About Wiki Forums Source Search Contact

Documentantion is not of much help

Moderators: kris

Posted: 08/21/07 07:37:43

Please, fix the docs.

1) With so MANY classes that, at least myself but suspect others too, have no idea what are they for. It NEEDS search.

2) Examples IN the API reference.

3) This is candydoc have nice style sheets but otherwise is pretty much useless. There is absolutely no information which class comes from where. What it derives from, what classes are derived from it. Names of other classes needs to be clickable. And for library with structure like tango, where everything is based on everything else <g> this IS important. For example all these streams and stuff that works together. You look the docs of Stdout and there is 3 functions there. But you don't have a slightest idea that you can do something like Stdout.stream.copy(FileConduit?)... Much of the docs becomes useless this way.

4) SEARCH! .chm would be great for offline reference.

5) Explain how to do BASIC things. OK, tango works with Time which uses 100ns or something like that, but the rest of the world doesn't. So how can one convert this 100ns to int ?!? And other things like that that doesn't come to mind in this moment.

6) Explain what is the purpose of the classes. For example Mutex. I open the docs for mutex because I need a cross-process lock. I know that mutexes in win32 are some kind of named things that you can have only one of each name in the OS. So I can use it for cross-process locks. I open the tango docs of Mutex and it have three methods - lock,tryLock,unlock without any arguments. Obviously it is not the same thing as win32 mutex but what is it? Who knows...

Author Message

Posted: 08/21/07 08:18:13

Heya bobef

We're certainly aware that the docs could be much better (there really is a lot of it, but not everything is easy enough to find as you say, and many things have not much written about it yet, etc. There are quite a few tickets even, several related to your exact points), but we need help. Some of your issues are technical problems (connect class hierarchies in the API-docs, API search), whereas the rest is more of "get writing" issue.

We would be very happy if you and everyone else could help us improve the situation :)

Posted: 08/21/07 09:01:04

The problem with me or anyone else helping, is that we need to get experienced in tango first, because this is my first attempt with tango. And this experience is going to happen the tough way :)

Posted: 09/02/07 08:16:20

I know it's not much, but, regarding Time, there's some info here

Posted: 09/11/07 22:54:50

The problem is: candydoc is just "eyecandy", it doesn't do anything usefull, docs don't have to look pretty, they have to be usefull and intuitive. Ddoc itself it a poor doc generation tool too. I just started a javadoc like doc generator based on ddoc output, when (and if) it becomes usable i'll release it. Putting someone in the tango team to handle the docs would be cool too. Any ideas in the doc generator would be appreciated. =)

Posted: 09/11/07 23:58:35

Can you help us by writing some doc?

Posted: 09/12/07 00:37:26

Write docs with my crap english? I don't think so...
Unless you want docs full of gramatical errors. =P
The documentation of a sofwtare/library is it's window to the world,
a good software with bad documentation would be viewed as amateur stuff.
I'll see what can I do to make ddoc looks as pro as javadoc.

Posted: 09/19/07 21:05:19

stack_overflow wrote:

Write docs with my crap english? I don't think so...
Unless you want docs full of gramatical errors. =P
The documentation of a sofwtare/library is it's window to the world,
a good software with bad documentation would be viewed as amateur stuff.
I'll see what can I do to make ddoc looks as pro as javadoc.

Wouldn't chipping in to doxygen be a better idea? ( speaks the person who isn't going to be doing it ;) )

According to dm, it already has some support for D and the output from doxygen is very handy for getting to grips with a new c++ project. I'm quite a fan of doxygen...

Posted: 09/19/07 22:33:02

doxygen is great for C/C++, and I used it for 2 years with D. Having said that, it just doesn't support D at the level we need it to. For example using version() in the code results in havoc. Became necessary to abandon it for Tango

Posted: 09/20/07 08:50:14

I think DDoc has what is necessary to become a good tool, but the current implementation in DMD is not good. AFAIK, the same stuff is enabled in Rebuild, and I think Gregor said that he would accept patches (for bugs at least that takes forever in DMD, and possibly also features).