Re: [boost] Bind documentation - request for clarification

From: Peter Dimov (pdimov_at_[hidden])
Date: 2001-12-27 07:57:36

From: "David Abrahams" <david.abrahams_at_[hidden]>
> 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.

Oh well, I agree with you. I simply need to know what makes my explanation
inadequate; is it only the inappropriate use of "nesting rules" or there is
something else as well.

> >> 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?

I think that the example is a bit too abstract and stripped down. I'll try
to think of a better one.

--
Peter Dimov
Multi Media Ltd.