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 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
prev sibling next sibling parent Nicolae Mihalache <xpromache gmail.com> writes:
--0016e6546cf4ce76fe04b2299644
Content-Type: text/plain; charset=ISO-8859-1

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

--0016e6546cf4ce76fe04b2299644 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable <p>If this module contains only functions, it looks fine. But I see it&#39;= s manually written.</p><p>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.</p> <p>Currently all the top level functions, classes, structs, method of class= es and structs appear in one list and it&#39;s difficult to say which is wh= at.</p><p>Maybe I&#39;m too biased by javadoc. I will try to work a bit mor= e with D and perhaps I will have a better idea.</p> <p><br></p><p>mache</p><p><br></p><p><br></p> <div class=3D"gmail_quote"><br></div><div class=3D"gmail_quote"><br></div><= div class=3D"gmail_quote">On Nov 20, 2011 12:30 AM, &quot;Andrei Alexandres= cu&quot; &lt;<a href=3D"mailto:SeeWebsiteForEmail erdani.org" target=3D"_bl= ank">SeeWebsiteForEmail erdani.org</a>&gt; wrote:<br type=3D"attribution"> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> On 11/19/11 2:11 PM, Nicolae Mihalache wrote:<br> <blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p= x #ccc solid;padding-left:1ex"> Hello,<br> <br> (I&#39;m a complete newbie in D)<br> I find that the format of the reference documentation (e.g.<br> <a href=3D"http://www.d-programming-language.org/phobos/std_datetime.html" = target=3D"_blank">http://www.d-programming-<u></u>language.org/phobos/std_<= u></u>datetime.html</a>) does<br> not make it very easy to find what you need.<br> </blockquote> <br> Is the structure in <a href=3D"http://www.d-programming-language.org/phobos= /std_algorithm.html" target=3D"_blank">http://www.d-programming-<u></u>lang= uage.org/phobos/std_<u></u>algorithm.html</a> closer to what you&#39;d like= ?<br> <br> Andrei<br> </blockquote></div> --0016e6546cf4ce76fe04b2299644--
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 next 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 next sibling parent 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
prev sibling 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