D docs too. (Was: Getting started with D - Phobos documentation sucks)
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 :(
Re: D docs too. (Was: Getting started with D - Phobos documentation sucks)
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).
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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?
Re: Getting started with D - Phobos documentation sucks
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
Re: Getting started with D - Phobos documentation sucks
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
Re: Getting started with D - Phobos documentation sucks
On Sun, 30 Sep 2012 07:02:15 -0400, Jacob Carlborg d...@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
Re: Getting started with D - Phobos documentation sucks
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?
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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
Re: Getting started with D - Phobos documentation sucks
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
Re: Getting started with D - Phobos documentation sucks
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
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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?
Re: Getting started with D - Phobos documentation sucks
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
Re: Getting started with D - Phobos documentation sucks
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
Re: Getting started with D - Phobos documentation sucks
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
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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
Re: Getting started with D - Phobos documentation sucks
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
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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
Re: Getting started with D - Phobos documentation sucks
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.
Getting started with D - Phobos documentation sucks
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?
Re: Getting started with D - Phobos documentation sucks
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
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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().
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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)
Re: Getting started with D - Phobos documentation sucks
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
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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
Re: Getting started with D - Phobos documentation sucks
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.
Re: Getting started with D - Phobos documentation sucks
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
