digitalmars.D - reference documentation format
- Nicolae Mihalache <xpromache gmail.com> Nov 19 2011
- Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> Nov 19 2011
- Nicolae Mihalache <xpromache gmail.com> Nov 20 2011
- Jonathan M Davis <jmdavisProg gmx.com> Nov 20 2011
- Nicolae Mihalache <xpromache gmail.com> Nov 20 2011
- Jonathan M Davis <jmdavisProg gmx.com> Nov 20 2011
- Nicolae Mihalache <xpromache gmail.com> Nov 21 2011
- Jonathan M Davis <jmdavisProg gmx.com> Nov 21 2011
- Dejan Lekic <dejan.lekic gmail.com> Nov 23 2011
- Nicolae Mihalache <xpromache gmail.com> Nov 24 2011
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
Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> 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
--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'= 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's difficult to say which is wh= at.</p><p>Maybe I'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, "Andrei Alexandres= cu" <<a href=3D"mailto:SeeWebsiteForEmail erdani.org" target=3D"_bl= ank">SeeWebsiteForEmail erdani.org</a>> 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'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'd like= ?<br> <br> Andrei<br> </blockquote></div> --0016e6546cf4ce76fe04b2299644--
Nov 20 2011
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
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
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
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
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
Nicolae, you can also browse the http://cutedoc.dav1d.de - it is an alternative "view" of the runtime documentation. :)
Nov 23 2011
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