www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - reference documentation format

reply Nicolae Mihalache <xpromache gmail.com> writes:
Hello,

(I'm a complete newbie in D)
I find that the format of the reference documentation (e.g.
http://www.d-programming-language.org/phobos/std_datetime.html) does
not make it very easy to find what you need.
I think it would be much easier if at the top of each module would be
an overview with all the structs, classes and methods defined in that
module.
I'm studying in parallel also the go language and I find their
documentation system better exactly because of this overview:
http://golang.org/pkg/runtime/

mache
Nov 19 2011
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 11/19/11 2:11 PM, Nicolae Mihalache wrote:

 Hello,

 (I'm a complete newbie in D)
 I find that the format of the reference documentation (e.g.
 http://www.d-programming-language.org/phobos/std_datetime.html) does
 not make it very easy to find what you need.


Is the structure in 
http://www.d-programming-language.org/phobos/std_algorithm.html closer 
to what you'd like?

Andrei
Nov 19 2011
next sibling parent Nicolae Mihalache <xpromache gmail.com> writes:
If this module contains only functions, it looks fine. But I see it's
manually written.

I would think it is possible to generate an index with all the functions,
classes, structs, etc and with a short description of each and with a link
to the full description.

Currently all the top level functions, classes, structs, method of classes
and structs appear in one list and it's difficult to say which is what.

Maybe I'm too biased by javadoc. I will try to work a bit more with D and
perhaps I will have a better idea.


mache





On Nov 20, 2011 12:30 AM, "Andrei Alexandrescu" <
SeeWebsiteForEmail erdani.org> wrote:


 On 11/19/11 2:11 PM, Nicolae Mihalache wrote:


 Hello,

 (I'm a complete newbie in D)
 I find that the format of the reference documentation (e.g.
 http://www.d-programming-**language.org/phobos/std_**datetime.html<http://www.d-programming-language.org/phobos/std_datetime.html>)
 does
 not make it very easy to find what you need.


 Is the structure in http://www.d-programming-**language.org/phobos/std_**
 algorithm.html<http://www.d-programming-language.org/phobos/std_a
gorithm.html>closer to what you'd like?

 Andrei
Nov 20 2011
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Sunday, November 20, 2011 13:20:00 Nicolae Mihalache wrote:

 If this module contains only functions, it looks fine. But I see it's
 manually written.
 
 I would think it is possible to generate an index with all the functions,
 classes, structs, etc and with a short description of each and with a link
 to the full description.
 
 Currently all the top level functions, classes, structs, method of classes
 and structs appear in one list and it's difficult to say which is what.
 
 Maybe I'm too biased by javadoc. I will try to work a bit more with D and
 perhaps I will have a better idea.


There's no reason why ddoc shouldn't be capable of generating a nice set of 
links at the top that give proper structure. The problem is that the anchors 
that it currently generates only hold the function name, so all hierarchical 
information is lost. Once that's fixed, then it shouldn't be a problem to have 
hierarchical links, but at the moment, it requires creating the links by hand, 
and in the case where multiple functions in the same file have the same name 
(including between user-defined types) results in a set of identical anchors, 
so you can't link to them individually, so you _can't_ have proper links in 
that case without editing the file after it's been generated - which definitely 
wouldn't work with the official docs and would obviously be a pain regardless.

I expect that the situation will be fixed eventually, but until then, the links 
on ddoc are limited in how well-structured they can be. Modules of only free 
functions can do fairly well as long the links are created by hand (e.g. 
std.algorithm), but modules which define types are currently out of luck (e.g. 
std.datetime).

- Jonathan M Davis
Nov 20 2011
prev sibling parent Nicolae Mihalache <xpromache gmail.com> writes:
I also expect that the situation will be fixed eventually, but in the
meanwhile, can I issue a feature request?
I see the Issues page is disabled on the dmd github page:
https://github.com/D-Programming-Language/dmd
Is there any reason for that?


On Sun, Nov 20, 2011 at 1:31 PM, Jonathan M Davis <jmdavisProg gmx.com> wrote:

 On Sunday, November 20, 2011 13:20:00 Nicolae Mihalache wrote:

 If this module contains only functions, it looks fine. But I see it's
 manually written.

 I would think it is possible to generate an index with all the functions,
 classes, structs, etc and with a short description of each and with a link
 to the full description.

 Currently all the top level functions, classes, structs, method of classes
 and structs appear in one list and it's difficult to say which is what.

 Maybe I'm too biased by javadoc. I will try to work a bit more with D and
 perhaps I will have a better idea.


 There's no reason why ddoc shouldn't be capable of generating a nice set of
 links at the top that give proper structure. The problem is that the anchors
 that it currently generates only hold the function name, so all hierarchical
 information is lost. Once that's fixed, then it shouldn't be a problem to have
 hierarchical links, but at the moment, it requires creating the links by hand,
 and in the case where multiple functions in the same file have the same name
 (including between user-defined types) results in a set of identical anchors,
 so you can't link to them individually, so you _can't_ have proper links in
 that case without editing the file after it's been generated - which definitely
 wouldn't work with the official docs and would obviously be a pain regardless.

 I expect that the situation will be fixed eventually, but until then, the links
 on ddoc are limited in how well-structured they can be. Modules of only free
 functions can do fairly well as long the links are created by hand (e.g.
 std.algorithm), but modules which define types are currently out of luck (e.g.
 std.datetime).

 - Jonathan M Davis
Nov 20 2011
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Monday, November 21, 2011 05:30:53 Nicolae Mihalache wrote:

 I also expect that the situation will be fixed eventually, but in the
 meanwhile, can I issue a feature request?
 I see the Issues page is disabled on the dmd github page:
 https://github.com/D-Programming-Language/dmd
 Is there any reason for that?


Because we use bugzilla: d.puremagic.com/issues

As far as the anchors go though, I'm pretty sure that a report already exists 
for it - probably one that I made too.

- Jonathan M Davis
Nov 20 2011
prev sibling next sibling parent Nicolae Mihalache <xpromache gmail.com> writes:
Ok, thanks. The bugzilla should also be linked from the main page or
from a page "Contributing".

I see there is the bug 3161 which points to an alternative ddoc:
http://downloads.dsource.org/projects/descent/ddoc/phobos/
which is already including some structure.



On Mon, Nov 21, 2011 at 5:40 AM, Jonathan M Davis <jmdavisProg gmx.com> wrote:

 On Monday, November 21, 2011 05:30:53 Nicolae Mihalache wrote:

 I also expect that the situation will be fixed eventually, but in the
 meanwhile, can I issue a feature request?
 I see the Issues page is disabled on the dmd github page:
 https://github.com/D-Programming-Language/dmd
 Is there any reason for that?


 Because we use bugzilla: d.puremagic.com/issues

 As far as the anchors go though, I'm pretty sure that a report already exists
 for it - probably one that I made too.

 - Jonathan M Davis
Nov 21 2011
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Monday, November 21, 2011 10:43:17 Nicolae Mihalache wrote:

 Ok, thanks. The bugzilla should also be linked from the main page or
 from a page "Contributing".


Open a bug report for the website. I supect that it was appropriately 
displayed on digitalmars' site but not the new one.

- Jonathan M Davis
Nov 21 2011
prev sibling parent reply Dejan Lekic <dejan.lekic gmail.com> writes:
Nicolae, you can also browse the http://cutedoc.dav1d.de - it is an 
alternative "view" of the runtime documentation. :)
Nov 23 2011
parent Nicolae Mihalache <xpromache gmail.com> writes:
This looks much better than the official one.
How is it generated?






On Wed, Nov 23, 2011 at 6:04 PM, Dejan Lekic <dejan.lekic gmail.com> wrote:

 Nicolae, you can also browse the http://cutedoc.dav1d.de - it is an
 alternative "view" of the runtime documentation. :)
Nov 24 2011