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!
