Re: [boost] Bind documentation - request for clarification

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2001-12-26 15:25:38

On Wednesday, December 26, 2001, at 09:27 AM, Peter Dimov wrote:

> From: "David Abrahams" <david.abrahams_at_[hidden]>
>> The documentation for bind says:
>>
>> "Note that the first argument - the bound function object - is an
> exception
>> to the nesting rules. A nested bind expression passed to bind as a 
>> first
>> argument is not treated differently from any other function object: "
>>
>> But it never says explicitly what "the nesting rules" are. With some 
>> work
> I
>> can infer that bind objects passed as arguments to bind (other than the
>> first), are evaluated when the outer bind is called, and the results 
>> are
>> used in place of the bind objects themseves.
>
> Here's what the documentation says:
>
> "Some of the arguments passed to bind may be nested bind expressions
> themselves:
>
> bind(f, bind(g, _1))(x);               // f(g(x))
>
> The nested subexpressions are evaluated when the function object is 
> called."
>
> This looks pretty similar to your explanation.

Of course it does - you wrote the documentation! When it comes to 
documentation, I go by the policy that "the customer is always right". 
The person who wrote the code always knows exactly what (s)he means when 
(s)he writes the documentation, but it doesn't mean that it will 
communicate clearly to others. I still think that mentioning "the 
nesting rules" when there is only one rule and it is never even 
described as such is confusing, but hey, maybe I'm in the minority.

>> One reason I find the passage confusing is that in the example, it says
> g(5,
>> 8) is called, but that appears to violate arity constraints since x is
>> passed as an argument but apparently never used.
>
> The example is a bit contrived, but so is the situation. The point is 
> that
> the first subexpression (the bound function object) is not evaluated 
> when
> it's a nested bind.
>
> It is a feature of bind that unreferenced arguments are silently 
> ignored;
> the bound function object's arity is enforced, but the function object
> returned by bind is flexible (it enforces only the minimal arity.)

The example is sufficiently hard to grok without this little twist. Is 
it possible to strip the example down so that it is much clearer what 
you are saying?

If not, it would help a lot if you would give a step-by-step description 
of what happens (and, by contrast, what doesn't happen) in the example.

-Dave