www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Getting started with D - Phobos documentation sucks

reply "Mr. Anonymous" <mailnew4ster gmail.com> writes:
Hi guys.

I was browsing the book "Programming in D" by Ali Çehreli. It 
was pretty much clear, and then I stumbled upon this on page 89:
 20.9 Exercises
 1. Browse the documentations of the std.string, std.array, 
 std.algorithm, and std.range modules.

OK, let's open the D website and browse the documentation of std.string: http://dlang.org/phobos/std_string.html What do we see? A bunch of links that look like SEO tags of a spam website, followed by a mess of anything - structs, classes, functions, and what not. Do you really think somebody who learns programming can understand anything here? Compare this with, e.g., an msdn reference: http://msdn.microsoft.com/en-us/library/windows/desktop/ms684852(v=vs.85).aspx A clear division of enums, functions, macros, structs, ... http://msdn.microsoft.com/en-us/library/windows/desktop/ms684847(v=vs.85).aspx The functions are divided by usage, with a short explanation next to each function. I think documentation is really important, and something has to be done about it. How can a newcomer get started with D when he doesn't have a readable documentation of Phobos?
Sep 29 2012
next sibling parent Timon Gehr <timon.gehr gmx.ch> writes:
On 09/29/2012 05:30 PM, Mr. Anonymous wrote:
 Hi guys.

 I was browsing the book "Programming in D" by Ali Çehreli. It was pretty
 much clear, and then I stumbled upon this on page 89:
 20.9 Exercises
 1. Browse the documentations of the std.string, std.array,
 std.algorithm, and std.range modules.

OK, let's open the D website and browse the documentation of std.string: http://dlang.org/phobos/std_string.html What do we see? A bunch of links that look like SEO tags of a spam website, followed by a mess of anything - structs, classes, functions, and what not. Do you really think somebody who learns programming can understand anything here? Compare this with, e.g., an msdn reference: http://msdn.microsoft.com/en-us/library/windows/desktop/ms684852(v=vs.85).aspx A clear division of enums, functions, macros, structs, ... http://msdn.microsoft.com/en-us/library/windows/desktop/ms684847(v=vs.85).aspx The functions are divided by usage, with a short explanation next to each function. I think documentation is really important, and something has to be done about it. How can a newcomer get started with D when he doesn't have a readable documentation of Phobos?

https://github.com/D-Programming-Language/d-programming-language.org
Sep 29 2012
prev sibling next sibling parent "MattCoder" <mattcoder hotmail.com> writes:
On Saturday, 29 September 2012 at 15:29:46 UTC, Mr. Anonymous 
wrote:
 1. Browse the documentations of the std.string, std.array, 
 std.algorithm, and std.range modules.

OK, let's open the D website and browse the documentation of std.string: http://dlang.org/phobos/std_string.html What do we see? A bunch of links that look like SEO tags of a spam website, followed by a mess of anything - structs, classes, functions, and what not. Compare this with, e.g., an msdn reference.....

Just remembering that most of the things that you see here is made by the community itself and the most important, it's free. But well this is not an excuse, but anyway, Microsoft come doing this since long time ago and was not always as you see today.
Sep 29 2012
prev sibling next sibling parent "Mr. Anonymous" <mailnew4ster gmail.com> writes:
On Saturday, 29 September 2012 at 15:46:36 UTC, MattCoder wrote:
 On Saturday, 29 September 2012 at 15:29:46 UTC, Mr. Anonymous 
 wrote:
 1. Browse the documentations of the std.string, std.array, 
 std.algorithm, and std.range modules.

OK, let's open the D website and browse the documentation of std.string: http://dlang.org/phobos/std_string.html What do we see? A bunch of links that look like SEO tags of a spam website, followed by a mess of anything - structs, classes, functions, and what not. Compare this with, e.g., an msdn reference.....

Just remembering that most of the things that you see here is made by the community itself and the most important, it's free. But well this is not an excuse, but anyway, Microsoft come doing this since long time ago and was not always as you see today.

Don't get me wrong, I'm not saying somebody owes me something. I love D and appreciate the effort the community puts in it, otherwise I probably wouldn't write this post. I'm just saying that, in my opinion, it's a high priority and it has to be addressed, so that newcomers would be able to get started with D.
Sep 29 2012
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
I agree that the docs do suck.

A while ago I wrote a post-processor to make nicer tables:
http://arsdnet.net/d-web-site/std_datetime.html

And I'm doing my own D docs thing:
http://dpldocs.info/search/index
http://dpldocs.info/search/search

but it still sucks. I have been so busy with other stuff that 
these initatives have sat unfinished for a long time now.
Sep 29 2012
prev sibling next sibling parent "Tommi" <tommitissari hotmail.com> writes:
On Saturday, 29 September 2012 at 15:29:46 UTC, Mr. Anonymous 
wrote:
 Hi guys.

 I was browsing the book "Programming in D" by Ali Çehreli. It 
 was pretty much clear, and then I stumbled upon this on page 89:
 20.9 Exercises
 1. Browse the documentations of the std.string, std.array, 
 std.algorithm, and std.range modules.

OK, let's open the D website and browse the documentation of std.string: http://dlang.org/phobos/std_string.html What do we see? A bunch of links that look like SEO tags of a spam website, followed by a mess of anything - structs, classes, functions, and what not. Do you really think somebody who learns programming can understand anything here? Compare this with, e.g., an msdn reference: http://msdn.microsoft.com/en-us/library/windows/desktop/ms684852(v=vs.85).aspx A clear division of enums, functions, macros, structs, ... http://msdn.microsoft.com/en-us/library/windows/desktop/ms684847(v=vs.85).aspx The functions are divided by usage, with a short explanation next to each function. I think documentation is really important, and something has to be done about it. How can a newcomer get started with D when he doesn't have a readable documentation of Phobos?

You should really read first "The D Programming Language", or TDPL. http://www.amazon.com/The-Programming-Language-Andrei-Alexandrescu/dp/0321635361 It's a great read, entertaining, informative. But notice that it doesn't cover everything, like template specializations (signature constraints are not the same thing). Then read the strictly less entertaining language reference pages starting from: http://dlang.org/lex.html But notice that it doesn't cover everything either. For example it fails to mention that pointers to structs and classes are implicitly dereferenced when you use the member access operator with them, like ptrToStruct.callMethod().
Sep 29 2012
prev sibling next sibling parent "MattCoder" <mattcoder hotmail.com> writes:
On Saturday, 29 September 2012 at 15:53:17 UTC, Mr. Anonymous 
wrote:
 Don't get me wrong, I'm not saying somebody owes me something.
 I love D and appreciate the effort the community puts in it, 
 otherwise I probably wouldn't write this post.

 I'm just saying that, in my opinion, it's a high priority and 
 it has to be addressed, so that newcomers would be able to get 
 started with D.

No problem fellow and be sure that I don't wanted to surpress your feelings, because I had the same feelings in the first time that I saw the doc's. But be sure the guys behind D knows that, but you know this is a hard job which demands some time.
Sep 29 2012
prev sibling next sibling parent "Tommi" <tommitissari hotmail.com> writes:
And there's also the D Templates Tutorial at:

https://github.com/PhilippeSigaud/D-templates-tutorial/blob/master/dtemplates.pdf

(click "View Raw" on that page)
Sep 29 2012
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/29/12 11:30 AM, Mr. Anonymous wrote:
 I think documentation is really important, and something has to be done
 about it. How can a newcomer get started with D when he doesn't have a
 readable documentation of Phobos?

Agree. It's high time we replace the silly litany of names at the top with a more sensible index (or, indeed, nothing at all!) Andrei
Sep 29 2012
parent reply deadalnix <deadalnix gmail.com> writes:
Le 29/09/2012 19:09, Adam D. Ruppe a écrit :
 On Saturday, 29 September 2012 at 17:03:26 UTC, monarch_dodra wrote:
 Well, they *are* better than nothing at all. Sure, in the best of
 worlds, we'd have lovingly hand written indexes and documentation,
 such as for std_algorithm. However, for those modules that *don't*
 have that hand written doc, it is better than nothing.

It is possible to do something like that automatically: http://arsdnet.net/d-web-site/std_stdio.html http://arsdnet.net/d-web-site/std_datetime.html

That is much better than what we currently have.
Sep 29 2012
parent reply Dmitry Olshansky <dmitry.olsh gmail.com> writes:
On 29-Sep-12 21:13, deadalnix wrote:
 Le 29/09/2012 19:09, Adam D. Ruppe a écrit :
 On Saturday, 29 September 2012 at 17:03:26 UTC, monarch_dodra wrote:
 Well, they *are* better than nothing at all. Sure, in the best of
 worlds, we'd have lovingly hand written indexes and documentation,
 such as for std_algorithm. However, for those modules that *don't*
 have that hand written doc, it is better than nothing.

It is possible to do something like that automatically: http://arsdnet.net/d-web-site/std_stdio.html http://arsdnet.net/d-web-site/std_datetime.html

That is much better than what we currently have.

Agreed. What's needed to make it a reality ? -- Dmitry Olshansky
Sep 29 2012
next sibling parent Dmitry Olshansky <dmitry.olsh gmail.com> writes:
On 30-Sep-12 06:17, Adam D. Ruppe wrote:
 On Saturday, 29 September 2012 at 17:20:48 UTC, Dmitry Olshansky wrote:
 Agreed. What's needed to make it a reality ?

Need to integrate my helper program into the website build process. Program here: http://arsdnet.net/d-web-site/improveddoc.d libs needed https://github.com/adamdruppe/misc-stuff-including-D-programming-language-web-stuff dom.d and characterencodings.d When I tried this earlier, I couldn't even get the basic website to build on my box from github. I think it needs github phobos too but meh, I moved on to something else and never got back to it. But if the website makefile built and ran that program across the html it generates, it should be set.

I'll give it a whirl. The current auto generated _index_ at the top is intolerable. It won't surprise me if this alone has attributed to having say 20% less newcomers. Not to mention some cool functions that just got lost in this noise :) -- Dmitry Olshansky
Sep 30 2012
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2012-09-30 04:17, Adam D. Ruppe wrote:
 On Saturday, 29 September 2012 at 17:20:48 UTC, Dmitry Olshansky wrote:
 Agreed. What's needed to make it a reality ?

Need to integrate my helper program into the website build process.

Is it just me that thinks that having a tool that fixes the generated documentation is ridiculous. The compiler should be modified to generate the documentation we want to have. -- /Jacob Carlborg
Sep 30 2012
next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2012-09-30 17:00, foobar wrote:

 Which is why the doc generation utility should be a separate tool and
 not built directly into the compiler. I understand Walter's desire to
 have batteries included with D (doc generation, unit-testing, profiling,
 ...) but that does not mean they should be welded in. The DMD
 distribution could just as well provide a set of auxiliary _standalone_
 utilities for that.

And we're back at the fact that we need a compiler library. -- /Jacob Carlborg
Sep 30 2012
parent Jacob Carlborg <doob me.com> writes:
On 2012-09-30 17:37, Adam D. Ruppe wrote:
 On Sunday, 30 September 2012 at 15:31:30 UTC, Jacob Carlborg wrote:
 And we're back at the fact that we need a compiler library.

Not necessarily... the ddoc comments are available in the compiler's json output (use -X and -D together in dmd). It doesn't do syntax highlighting and could offer a lot more info than it does now... but it does give enough to approximate your own ddoc. I'm using the json output for dpldocs.info version two: http://dpldocs.info/search/search?searchTerm=std.regex

If think the whole idea of the JSON output is a workaround for not having the compiler available as a library. -- /Jacob Carlborg
Sep 30 2012
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2012-09-30 15:49, Adam D. Ruppe wrote:

 Eh, maybe. I just find doing fancier things inside the compiler to be a
 pain in the butt. Basically D > C++. And it is harder to get code into
 dmd than it is to just do your own thing.

 But really what matters is that we get something that doesn't suck
 results wise. We could always change the ddoc implementation later.

That might be true but it's this kind of attitude that makes the source code a big mess and software suck. It's always "we fix this later", well "later" is never going to happen. It's always patch on workaround on fix on patch, and so on. What's wrong with "hey, lets fix this the right way for a change". -- /Jacob Carlborg
Sep 30 2012
next sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2012-09-30 17:53, Adam D. Ruppe wrote:
 On Sunday, 30 September 2012 at 15:41:46 UTC, Adam D. Ruppe wrote:
 If you want to write the code, feel free.

I'm sorry, this probably came across as rude, but the answer for why not do it the right way is simply that the right way takes time and I don't feel like putting it in. Apparently not very many other people do either, since we've had the status quo for a long time now. A quick helper app can be slapped together in a fraction of the time of a more proper fix.

Yeah I know. I would like to fix it but I think the DMD code base is quite horrible and just a big mess. I've tried several times to fix small bugs or tried to do some other modifications. But every time I fail because I have no idea what I'm doing and the DMD code base is far from easy to work. -- /Jacob Carlborg
Sep 30 2012
parent Jacob Carlborg <doob me.com> writes:
On 2012-09-30 21:23, Adam D. Ruppe wrote:

 What hurts me most in doing it is just that it is C++... I know my way
 around the compiler reasonably well. Not great but good enough to get
 by... but doing new code is just such a pain. Little things like no
 auto, forward declarations, weak sauce arrays and strings. Ugh, it just
 isn't D.

I completely agree. Can't we start to use C++11 soon. At least it has "auto".
 And then dmd has its own rules that trip me up. Aren't supposed to use
 dynamic_cast, can't use tabs, just all kinds of style things that grind me.

I know a few of these rules were due to old compilers having problem with some of the C++ features (templates). Is this still a problem or is there other reasons? I know that Clang doesn't use "dynamic_cast" or RTTI for that matter. -- /Jacob Carlborg
Sep 30 2012
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/30/12 11:53 AM, Adam D. Ruppe wrote:
 On Sunday, 30 September 2012 at 15:41:46 UTC, Adam D. Ruppe wrote:
 If you want to write the code, feel free.

I'm sorry, this probably came across as rude, but the answer for why not do it the right way is simply that the right way takes time and I don't feel like putting it in. Apparently not very many other people do either, since we've had the status quo for a long time now. A quick helper app can be slapped together in a fraction of the time of a more proper fix.

I don't think the comeback was rude because many great improvements to D came exactly this way - pull requests followed through by talented and interested contributors. On the other hand, if I were to criticize anything, Adam has a lot of great work brought to the proof-of-concept stage but not finalized. It would be great if we had some more finalized things. Andrei
Sep 30 2012
parent Jacob Carlborg <doob me.com> writes:
On 2012-10-01 04:55, Adam D. Ruppe wrote:

 A problem I've been having ever since I started doing professional
 programming is that my focus time is a lot less than it used to be.

 I used to be able to sit down and spend a full month on one single
 thing, very few distractions as the monday return to work was /not/
 inevitable... But recently that time has been limited to only three
 days, if I'm lucky, before something comes up and takes my attention away.

That's the big issue. I'm basically limited to one or two hours per day, if I'm lucky. Last week I only got a couple of minutes per day. This weekend I spent debugging DWT which lead nowhere, which felt like quite waste. -- /Jacob Carlborg
Sep 30 2012
prev sibling next sibling parent "monarch_dodra" <monarchdodra gmail.com> writes:
On Saturday, 29 September 2012 at 16:34:41 UTC, Andrei 
Alexandrescu wrote:
 On 9/29/12 11:30 AM, Mr. Anonymous wrote:
 I think documentation is really important, and something has 
 to be done
 about it. How can a newcomer get started with D when he 
 doesn't have a
 readable documentation of Phobos?

Agree. It's high time we replace the silly litany of names at the top with a more sensible index (or, indeed, nothing at all!) Andrei

Well, they *are* better than nothing at all. Sure, in the best of worlds, we'd have lovingly hand written indexes and documentation, such as for std_algorithm. However, for those modules that *don't* have that hand written doc, it is better than nothing. IMO, however, anything "nested" should NOT appear in the top index though, just the module's global functions and classes/structs. Anything else is clutter: std_container is a blatant example of the clutter I'm talking about: There is everything in there from "front" to "opIndexOpAssign"... Either that, or reorganized, as in: Array (front, back, ... opIndexOpAssiggn) Rather than the current free for all.
Sep 29 2012
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Saturday, 29 September 2012 at 17:03:26 UTC, monarch_dodra 
wrote:
 Well, they *are* better than nothing at all. Sure, in the best 
 of worlds, we'd have lovingly hand written indexes and 
 documentation, such as for std_algorithm. However, for those 
 modules that *don't* have that hand written doc, it is better 
 than nothing.

It is possible to do something like that automatically: http://arsdnet.net/d-web-site/std_stdio.html http://arsdnet.net/d-web-site/std_datetime.html
Sep 29 2012
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Saturday, 29 September 2012 at 17:20:48 UTC, Dmitry Olshansky 
wrote:
 Agreed. What's needed to make it a reality ?

Need to integrate my helper program into the website build process. Program here: http://arsdnet.net/d-web-site/improveddoc.d libs needed https://github.com/adamdruppe/misc-stuff-including-D-programming-language-web-stuff dom.d and characterencodings.d When I tried this earlier, I couldn't even get the basic website to build on my box from github. I think it needs github phobos too but meh, I moved on to something else and never got back to it. But if the website makefile built and ran that program across the html it generates, it should be set.
Sep 29 2012
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Sunday, September 30, 2012 04:17:59 Adam D. Ruppe wrote:
 When I tried this earlier, I couldn't even get the basic website
 to build on my box from github. I think it needs github phobos
 too but meh, I moved on to something else and never got back to
 it.

Unless something's changed recently, to build the website docs, you need both druntime and Phobos to be the latest from github (just like d-programming- language.org) and to have them all in the same directory. Otherwise, it doesn't work. And personally, I'm always having to change the makefile so that it doesn't try and build previous versions of Phobos or it doesn't work. It's far too dependent on having a very specific setup on your box and probably should be fixed as part of the initiatize to better automize the release process. It's far too fragile as it is. - Jonathan M Davis
Sep 29 2012
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Sunday, September 30, 2012 13:02:15 Jacob Carlborg wrote:
 On 2012-09-30 04:17, Adam D. Ruppe wrote:
 On Saturday, 29 September 2012 at 17:20:48 UTC, Dmitry Olshansky wrote:
 Agreed. What's needed to make it a reality ?

Need to integrate my helper program into the website build process.

Is it just me that thinks that having a tool that fixes the generated documentation is ridiculous. The compiler should be modified to generate the documentation we want to have.

That's what I've always thought. The main problem IMHO is how the links are generated, making it impossible to have links to symbols with the same name in the same module even if they're in different scopes (e.g. a free function and one in a class). And that's definitely not the sort of thing that an external tool should be fixing. - Jonathan M Davis
Sep 30 2012
prev sibling next sibling parent "JN" <666total wp.pl> writes:
While we're speaking about docs improvement, I believe there is 
one more thing that could use a fix - clickable identifiers. I 
don't know how much of an effort it would require, so consider it 
a wishlist, but for stuff like:

static  property  safe TickDuration currAppTick();

TickDuration should be a clickable link leading to 
core.time.TickDuration class docs.

Example: 
http://docs.oracle.com/javase/1.4.2/docs/api/javax/swing/Icon.html#paintIcon
java.awt.Component, 
java.awt.Graphics, int, int)

notice how Component and Graphics are clickable so you can 
instantly jump to their relevant declarations. This feature along 
with the abovementioned improvements would probably make the 
documentation a useful and intuitive tool.
Sep 30 2012
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Sunday, 30 September 2012 at 11:22:02 UTC, Jonathan M Davis 
wrote:
 The main problem IMHO is how the links are generated,
 making it impossible to have links to symbols with the
 same name in the same module

Yeah, I did a pull request to dmd to add a new macro to fix this, but I also included a change to the escaping rules and the powers that be weren't convinced of them (though they should be, ddoc is virtually unusable for documenting html and also for outputting other document formats without it or something like it). Anyway though I need to separate out my ddoc fixes into individual pull requests and I haven't gotten around to it yet. Maybe I'll try to fit it in today. After we allow a DDOC_PSYMBOL macro, we update std.ddoc to use it for the anchors and then we're set. Though, it still doesn't account for overloaded functions... but meh it's a *lot* better than we have now.
Sep 30 2012
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Sunday, 30 September 2012 at 10:08:17 UTC, Dmitry Olshansky 
wrote:
 I'll give it a whirl.

cool. BTW search the code for the word "HACK". There's one that rewrites css links to be absolute and one that adds some inline style. Those are there so I can test it from a different domain that doesn't have the whole website available. Probably safe to leave them there, but surely cleaner to comment that out before committing to the real thing.
Sep 30 2012
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Sunday, 30 September 2012 at 11:01:50 UTC, Jacob Carlborg 
wrote:
 Is it just me that thinks that having a tool that fixes the 
 generated documentation is ridiculous. The compiler should be 
 modified to generate the documentation we want to have.

Eh, maybe. I just find doing fancier things inside the compiler to be a pain in the butt. Basically D > C++. And it is harder to get code into dmd than it is to just do your own thing. But really what matters is that we get something that doesn't suck results wise. We could always change the ddoc implementation later.
Sep 30 2012
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Sunday, 30 September 2012 at 11:35:48 UTC, JN wrote:
 TickDuration should be a clickable link leading to 
 core.time.TickDuration class docs.

Yeah, I looked for that once before too, but the current implementation makes that difficult. IIRC the compiler has already stringified that data by the time it gets to the documentation generation code, so the details aren't really available. I do vaguely recall seeing someone post a proper solution to github or bugzilla once though. Another possibility is to connect it through to a search engine. My (currently low quality) dpldocs.info does an ok job: http://dpldocs.info/TickDuration So we could just wire all clicks to go through that. Somehow. But I think that's still suck hard because it couldn't tell what words to allow to be clickable and would have pointless ambiguity compared to the compiler just showing the right data. idk, I just kinda hate doing C++ too. D has spoiled me.
Sep 30 2012
prev sibling next sibling parent "foobar" <foo bar.com> writes:
On Sunday, 30 September 2012 at 13:48:41 UTC, Adam D. Ruppe wrote:
 On Sunday, 30 September 2012 at 11:01:50 UTC, Jacob Carlborg 
 wrote:
 Is it just me that thinks that having a tool that fixes the 
 generated documentation is ridiculous. The compiler should be 
 modified to generate the documentation we want to have.

Eh, maybe. I just find doing fancier things inside the compiler to be a pain in the butt. Basically D > C++. And it is harder to get code into dmd than it is to just do your own thing. But really what matters is that we get something that doesn't suck results wise. We could always change the ddoc implementation later.

Which is why the doc generation utility should be a separate tool and not built directly into the compiler. I understand Walter's desire to have batteries included with D (doc generation, unit-testing, profiling, ...) but that does not mean they should be welded in. The DMD distribution could just as well provide a set of auxiliary _standalone_ utilities for that. DMD already has JSON output. Can't that be standardized and used with a separate ddoc utility written in D?
Sep 30 2012
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Sunday, 30 September 2012 at 15:31:30 UTC, Jacob Carlborg 
wrote:
 And we're back at the fact that we need a compiler library.

Not necessarily... the ddoc comments are available in the compiler's json output (use -X and -D together in dmd). It doesn't do syntax highlighting and could offer a lot more info than it does now... but it does give enough to approximate your own ddoc. I'm using the json output for dpldocs.info version two: http://dpldocs.info/search/search?searchTerm=std.regex
Sep 30 2012
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Sunday, 30 September 2012 at 15:36:50 UTC, Jacob Carlborg 
wrote:
 What's wrong with "hey, lets fix this the right way for a 
 change".

If you want to write the code, feel free.
Sep 30 2012
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Sunday, 30 September 2012 at 15:41:46 UTC, Adam D. Ruppe wrote:
 If you want to write the code, feel free.

I'm sorry, this probably came across as rude, but the answer for why not do it the right way is simply that the right way takes time and I don't feel like putting it in. Apparently not very many other people do either, since we've had the status quo for a long time now. A quick helper app can be slapped together in a fraction of the time of a more proper fix.
Sep 30 2012
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Sunday, 30 September 2012 at 17:27:43 UTC, Jacob Carlborg 
wrote:
 I would like to fix it but I think the DMD code base is quite 
 horrible and just a big mess.

What hurts me most in doing it is just that it is C++... I know my way around the compiler reasonably well. Not great but good enough to get by... but doing new code is just such a pain. Little things like no auto, forward declarations, weak sauce arrays and strings. Ugh, it just isn't D. And then dmd has its own rules that trip me up. Aren't supposed to use dynamic_cast, can't use tabs, just all kinds of style things that grind me.
Sep 30 2012
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Sunday, 30 September 2012 at 20:24:17 UTC, Andrei Alexandrescu 
wrote:
 It would be great if we had some more finalized things.

A problem I've been having ever since I started doing professional programming is that my focus time is a lot less than it used to be. I used to be able to sit down and spend a full month on one single thing, very few distractions as the monday return to work was /not/ inevitable... But recently that time has been limited to only three days, if I'm lucky, before something comes up and takes my attention away. And after I switch focus to something else, I often don't come back to the other thing for quite a long time. It is pushed down to the bottom of an ever growing list. So if it isn't finished in just a few days, it means I probably won't finish it for at least many months, and there's not a great deal I can do about that in the short term, at least not without spending 14 hours a day every day doing nothing but code, and blargh.
Sep 30 2012
prev sibling next sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Sun, 30 Sep 2012 07:02:15 -0400, Jacob Carlborg <doob me.com> wrote:

 On 2012-09-30 04:17, Adam D. Ruppe wrote:
 On Saturday, 29 September 2012 at 17:20:48 UTC, Dmitry Olshansky wrote:
 Agreed. What's needed to make it a reality ?

Need to integrate my helper program into the website build process.

Is it just me that thinks that having a tool that fixes the generated documentation is ridiculous. The compiler should be modified to generate the documentation we want to have.

it's not just you... -Steve
Oct 01 2012
prev sibling next sibling parent "David Piepgrass" <qwertie256 gmail.com> writes:
 I think documentation is really important, and something has to 
 be done about it. How can a newcomer get started with D when he 
 doesn't have a readable documentation of Phobos?

A couple of random things I'd like to see: 1. Improve index.html. It's the first thing new users are likely to see about Phobos and it appears to contain an overview of the modules, but in fact it only lists half the modules of Phobos and the description of most modules is too short to be useful. There should also be a getting-started guide that lists the most common data types and functions and which module contains them (to!T, Tuple, writeln, ....) and it should also discuss the 'built-in' types for completeness, like slices, hashes and strings, since in other languages these are standard library components.) 2. To make the documentation easier to Google, put the keyword "D2" on every page of the Phobos documentation, e.g. the heading could change from "std.file" to "std.file (D2)". Nowadays when I search for something about "D Language", I often find a page about D1 instead of D2. The "articles" should be reviewed too. For example the page on tuples http://dlang.org/tuple.html makes it sound like you're supposed to define your own Tuple type instead of using the one in std.typecons; in fact it suggests template Tuple(E...) { alias E Tuple; } which is really a TypeTuple isn't it?
Oct 01 2012
prev sibling next sibling parent reply "Mr. Anonymous" <mailnew4ster gmail.com> writes:
On Saturday, 29 September 2012 at 15:29:46 UTC, Mr. Anonymous 
wrote:
 Hi guys.

 I was browsing the book "Programming in D" by Ali Çehreli. It 
 was pretty much clear, and then I stumbled upon this on page 89:
 20.9 Exercises
 1. Browse the documentations of the std.string, std.array, 
 std.algorithm, and std.range modules.

OK, let's open the D website and browse the documentation of std.string: http://dlang.org/phobos/std_string.html What do we see? A bunch of links that look like SEO tags of a spam website, followed by a mess of anything - structs, classes, functions, and what not. Do you really think somebody who learns programming can understand anything here? Compare this with, e.g., an msdn reference: http://msdn.microsoft.com/en-us/library/windows/desktop/ms684852(v=vs.85).aspx A clear division of enums, functions, macros, structs, ... http://msdn.microsoft.com/en-us/library/windows/desktop/ms684847(v=vs.85).aspx The functions are divided by usage, with a short explanation next to each function. I think documentation is really important, and something has to be done about it. How can a newcomer get started with D when he doesn't have a readable documentation of Phobos?

OK, I looked at it, and I saw that the links are generated by javascript. So I decided to try and write a better javascript function for creating links. Here's what I came up with: The JS code: http://pastebin.com/Pz4fb4JR Screenshots: http://i.imgur.com/gwxrI.png, http://i.imgur.com/qGGQn.png As you can see, the code works for both the website html and the one bundled with dmd. If my function finds nothing, it falls back to it's old version of anchor list. This solution is quite bad and temporary, but what we have now is not much better, so, for a while, I think it's worth using. P.S. I saw in the comments that Adam D. Ruppe came up with a better solution, but it requires an external tool. My solution requires a small javascript change, which should be very easy to integrate.
Oct 01 2012
parent Piotr Szturmaj <bncrbme jadamspam.pl> writes:
Mr. Anonymous wrote:
 OK, I looked at it, and I saw that the links are generated by javascript.
 So I decided to try and write a better javascript function for creating
 links.

 Here's what I came up with:
 The JS code: http://pastebin.com/Pz4fb4JR
 Screenshots: http://i.imgur.com/gwxrI.png, http://i.imgur.com/qGGQn.png

 As you can see, the code works for both the website html and the one
 bundled with dmd.
 If my function finds nothing, it falls back to it's old version of
 anchor list.

 This solution is quite bad and temporary, but what we have now is not
 much better, so, for a while, I think it's worth using.

I've also tried to improve it: http://forum.dlang.org/thread/jb0ril$17oa$1 digitalmars.com But I think that top positioned index is bad. It should be on the left, or the right pane.
Oct 01 2012
prev sibling next sibling parent "Mr. Anonymous" <mailnew4ster gmail.com> writes:
On Monday, 1 October 2012 at 19:39:35 UTC, Piotr Szturmaj wrote:
 Mr. Anonymous wrote:
 OK, I looked at it, and I saw that the links are generated by 
 javascript.
 So I decided to try and write a better javascript function for 
 creating
 links.

 Here's what I came up with:
 The JS code: http://pastebin.com/Pz4fb4JR
 Screenshots: http://i.imgur.com/gwxrI.png, 
 http://i.imgur.com/qGGQn.png

 As you can see, the code works for both the website html and 
 the one
 bundled with dmd.
 If my function finds nothing, it falls back to it's old 
 version of
 anchor list.

 This solution is quite bad and temporary, but what we have now 
 is not
 much better, so, for a while, I think it's worth using.

I've also tried to improve it: http://forum.dlang.org/thread/jb0ril$17oa$1 digitalmars.com But I think that top positioned index is bad. It should be on the left, or the right pane.

Why hasn't it been integrated? I guess the reason is that everybody says "that's not a solution, we have to fix x and y", but nobody actually fixes that stuff, and the reality is that we're left with an unusable list of anchored SEO-spam links for years. That's why I did the change as simple as possible - it should take no more than a minute to replace the function. P.S. can somebody create a pull request for this at github? I'm not familiar with this stuff.
Oct 01 2012
prev sibling next sibling parent "Gary Willoughby" <dev kalekold.net> writes:
On Saturday, 29 September 2012 at 16:34:41 UTC, Andrei 
Alexandrescu wrote:
 On 9/29/12 11:30 AM, Mr. Anonymous wrote:
 I think documentation is really important, and something has 
 to be done
 about it. How can a newcomer get started with D when he 
 doesn't have a
 readable documentation of Phobos?

Agree. It's high time we replace the silly litany of names at the top with a more sensible index (or, indeed, nothing at all!) Andrei

That sounds great. I'm an experience developer new to D and i find the documentation quite frustrating to navigate and use. Things are kind of all over the place at the minute.
Oct 02 2012
prev sibling next sibling parent "JN" <666total wp.pl> writes:
http://forum.dlang.org/thread/k4f4tp$8p4$1 digitalmars.com#post-k4fdsc:24v9u:241:40digitalmars.com

vibe.d got clickable types in documentation, perhaps this could 
be somehow integrated into phobos docs?
Oct 02 2012
prev sibling next sibling parent "mist" <none none.none> writes:
Reviving old topic.

I've been recently checking few general dlang.org pages like 
http://dlang.org/cpptod.html and noticed that there is plenty of 
stuff that is either deprecated ( like typedef ) or not really 
advised ( like C-style function type declarations ). Probably all 
language docs need a good pass-through to cleanup all possible 
misunderstandings. It is especially important for newbie-oriented 
pages like cpptod.html

I'd gladly do it but it feels like someones pretty experienced 
time is required to actually validate stuff :(
Oct 05 2012
prev sibling parent "Jesse Phillips" <Jessekphillips+D gmail.com> writes:
On Friday, 5 October 2012 at 15:38:13 UTC, mist wrote:
 I'd gladly do it but it feels like someones pretty experienced 
 time is required to actually validate stuff :(

That is where the pull request is great. The hard work of finding and making the change can be done by the many, and review can be done by the authorities (and sometimes more knowledgeable).
Oct 05 2012