std.bind documentation sucks hard

[Georg Wrede]

At first sight I thought I had become stupid. Reading the page once 
through left me with absolutely no notion on how or to what one should 
or could use bind. (And that coming from someone who actually has 
studied the STL hard (albeit 10 years ago)). I can only imagine how much 
the average D-newcomer gets out of the page.

First of all, the function bind itself is impossible to find simply by 
scanning the page. It also isn't in the Jump List at the top. Turns out 
it is hidden behind a scary line starting with typeof(new 
BoundFunc...)... stuff. (Yes, I understand it has to be there, but the 
word bind itself *has* to be "findable" by eyeballing the page down from 
the top. So put the word bind, e.g. in a mini-heading or whatever right 
before that line!)

There are no examples. Yes, there are commands in example-style boxes, 
but they aren't examples, since all we have is the bare command invocation.


An example (heh, even this post has one) of what I mean:

- bind(&foo, _0, _1) // will yield a delegate accepting two parameters
- bind(&foo, _1, _0) // will yield a delegate accepting two parameters
- bind(&bar, _0, _1, _2, _0) // will yield a delegate accepting three 
parameters

What does this tell the _new_ reader??

Another example is "const DynArg!(2) _2;" What do I use it for, and 
where. And how do I use it?


One would also expect that at the start of the page there is some text 
explaining the concept itself, where one should use bind, and for what 
benefit.

The fact that nobody has yet pointed out the blatant typo in the "long" 
"example" that I pasted above, only serves to show that most readers try 
to read and understand the page, and give up. And the page has been 
there for over 2 years.


It is not impossible to write good D doc pages, for example std.signals 
does a much better job. Or std.getopt.

And before any smarta** says well, georg, why don't you fix it, I have 
to remind that currently I hardly have the time to read these NGs. But 
even then, for every few hours of reading, I at least try to give a 
meaningful contribution in exchange.

Another smarta** might say that "it says References: boost" so read 
that. Well, one could say this about every single doc page on the site.

Anyhow, if Tomasz Stachowiak (whom I'm not attacking with this post!) is 
unavailable, then I wish somebody who actually uses bind, could submit a 
better version. Even a little improvement would be most welcome.


PS: with the newest developments in D2, bind is suddenly becoming an 
essential part of the new kind of D programming that is currently 
becoming possible!