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 reply "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
parent reply "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
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 "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 "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
next sibling parent reply "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
parent reply "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
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
parent reply "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
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 reply 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
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 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 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
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 reply "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
next sibling parent reply "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
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 reply "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
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
parent reply "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
parent reply "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
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 reply "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
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 reply "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
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 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 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 reply "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
parent reply "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
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 "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 reply 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
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 parent reply "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
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